plot_state_frequencies: Plot State Frequency Distributions

In Nestimate: Network Estimation, Bootstrap, and Higher-Order Analysis

Plot State Frequency Distributions

Description

Visualise state (node) frequency distributions across groups for any Nestimate object that carries sequence data: a single netobject, a netobject_group, an mcml model, or an htna network.

Usage

plot_state_frequencies(x, ...)

## S3 method for class 'netobject'
plot_state_frequencies(
  x,
  style = "marimekko",
  metric = "prop",
  label = "prop",
  legend = "auto",
  legend_dir = "auto",
  legend_frame = "none",
  sort_states = "frequency",
  colors = NULL,
  label_size = 3.5,
  abbreviate = FALSE,
  include_macro = FALSE,
  combine = "auto",
  ncol = NULL,
  node_groups = NULL,
  ...
)

## S3 method for class 'htna'
plot_state_frequencies(
  x,
  style = "marimekko",
  metric = "prop",
  label = "prop",
  legend = "auto",
  legend_dir = "auto",
  legend_frame = "none",
  sort_states = "frequency",
  colors = NULL,
  label_size = 3.5,
  abbreviate = FALSE,
  include_macro = FALSE,
  combine = "auto",
  ncol = NULL,
  node_groups = NULL,
  ...
)

## S3 method for class 'mcml'
plot_state_frequencies(
  x,
  style = "marimekko",
  metric = "prop",
  label = "prop",
  legend = "auto",
  legend_dir = "auto",
  legend_frame = "none",
  sort_states = "frequency",
  colors = NULL,
  label_size = 3.5,
  abbreviate = FALSE,
  include_macro = FALSE,
  combine = "auto",
  ncol = NULL,
  node_groups = NULL,
  ...
)

## S3 method for class 'netobject_group'
plot_state_frequencies(
  x,
  style = "marimekko",
  metric = "prop",
  label = "prop",
  legend = "auto",
  legend_dir = "auto",
  legend_frame = "none",
  sort_states = "frequency",
  colors = NULL,
  label_size = 3.5,
  abbreviate = FALSE,
  include_macro = FALSE,
  combine = "auto",
  ncol = NULL,
  node_groups = NULL,
  ...
)

## Default S3 method:
plot_state_frequencies(x, ...)

Arguments

x	A netobject, netobject_group, mcml, or htna object.
...	Reserved for future use.
style	One of: "marimekko" (default) – per-group treemap panels with cumulative-width geometry; tile area = within-group state share. "bars" – horizontal bars sorted by frequency, faceted per group. For chi-square mosaics of a (group x state) contingency table, use mosaic_plot directly – it is kept as a separate function with its own dispatch surface.
metric	For style = "bars": which value the bar length encodes – "prop" (default) or "freq". Treemap and hierarchical-marimekko areas always encode proportion within group.
label	Inline tile / bar annotation. All formats render on a single line. "prop" (default) – proportion only, e.g. "66%" "freq" – count only, e.g. "1,234" "both" – count + proportion, e.g. "1,234 (66%)" "state" – state name only, e.g. "Average" "all" – state + proportion, e.g. "Average (66%)" "none" – no inline labels
legend	Legend position. "auto" (default) resolves per style: "none" for style = "bars" (the y-axis already names every state, so a colour legend is redundant); "per_facet" for htna/mcml treemaps (state vocabularies differ per panel, so each gets its own legend); "bottom" for single-network and netobject_group treemaps (shared state vocabulary, one shared legend). Override with any of "bottom", "top", "right", "left", "none", or "per_facet". The "per_facet" option requires the gridExtra package and returns a gtable.
legend_dir	Legend internal layout: "auto" (default – horizontal for top/bottom, vertical for left/right), or force "horizontal" or "vertical" regardless of position.
legend_frame	"none" (default) for an unframed legend, or "border" to draw a thin grey rectangle around the legend ("legend enclosed in a square").
sort_states	One of "frequency" (default – most frequent first), "alpha", or "none".
colors	Optional character vector overriding the default Okabe-Ito state palette. Length must be at least the number of unique states.
label_size	Numeric size of inline labels (max size when ggfittext is installed – text auto-shrinks per tile).
abbreviate	Abbreviate state names. FALSE (default) shows full names; TRUE truncates to the first 3 characters via base::abbreviate() (which extends the truncation as needed to keep names unique after collision); a positive integer sets the target minimum length explicitly (e.g. abbreviate = 4). Affects tile labels, legend, and the returned $table.
include_macro	For mcml only: prepend a "macro" reference column showing aggregate state frequencies across all clusters. Default FALSE.
combine	For legend = "per_facet" only. "auto" (default) returns a single combined gtable for 1-3 panels and a list of ggplots (one per panel) for 4+ panels – many-cluster mcml layouts read better as separate figures than as a tile grid. TRUE forces a combined gtable via gridExtra; FALSE forces a list (knitr renders each at the chunk's full fig.width / fig.height).
ncol	For legend = "per_facet" with combine = TRUE: number of columns in the grid arrangement. NULL (default) picks 1, 2, or 3 columns based on the number of panels.
node_groups	Optional named character vector mapping node labels to semantic groups. When supplied, panels (or bars) are coloured / annotated by group rather than by individual state, so state-level palettes can collapse onto a smaller categorical legend.

Details

The marimekko layout is dispatched per class:

• For mcml, where states partition cleanly into clusters, the chart is a hierarchical 2D marimekko: cluster columns of width proportional to cluster total, segments stacked vertically with heights proportional to within-cluster state proportions.

• For all other classes (netobject, netobject_group, htna), each group is rendered as its own panel containing a squarified treemap: each state becomes a rectangular tile whose AREA is exactly proportional to the state's share within that group. Single-panel when no groups exist; faceted when groups are present.

The bar style produces horizontal bars (state on the y-axis), faceted by group when groups exist. All variants use the Okabe-Ito palette.

Value

A state_freq object: a list with the rendered $plot (a ggplot or gtable), the tidy $table (a data.frame with columns group, state, count, proportion), and the call's $style, $metric, $source_class. The class supports print() (shows the tidy table in the console), plot() (renders the chart), and as.data.frame() (returns the table).

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  data(group_regulation_long, package = "Nestimate")
  nw <- build_network(group_regulation_long,
                      method = "relative", format = "long",
                      actor = "Actor", action = "Action",
                      order = "Time", group = "Course")
  res <- plot_state_frequencies(nw)
  print(res)            # tidy frequency table in the console
  plot(res)             # ggplot chart
  head(as.data.frame(res))
}

Nestimate documentation built on July 11, 2026, 1:09 a.m.