% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_state_frequencies.R
\name{plot_state_frequencies}
\alias{plot_state_frequencies}
\alias{plot_state_frequencies.netobject}
\alias{plot_state_frequencies.htna}
\alias{plot_state_frequencies.mcml}
\alias{plot_state_frequencies.netobject_group}
\alias{plot_state_frequencies.default}
\title{Plot State Frequency Distributions}
\usage{
plot_state_frequencies(x, ...)

\method{plot_state_frequencies}{netobject}(
  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,
  ...
)

\method{plot_state_frequencies}{htna}(
  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,
  ...
)

\method{plot_state_frequencies}{mcml}(
  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,
  ...
)

\method{plot_state_frequencies}{netobject_group}(
  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,
  ...
)

\method{plot_state_frequencies}{default}(x, ...)
}
\arguments{
\item{x}{A \code{netobject}, \code{netobject_group}, \code{mcml}, or
\code{htna} object.}

\item{...}{Reserved for future use.}

\item{style}{One of:
\itemize{
\item \code{"marimekko"} (default) -- per-group treemap panels with
cumulative-width geometry; tile area = within-group state share.
\item \code{"bars"} -- horizontal bars sorted by frequency, faceted
per group.
}
For chi-square mosaics of a (group x state) contingency table, use
\code{\link{mosaic_plot}} directly -- it is kept as a separate
function with its own dispatch surface.}

\item{metric}{For \code{style = "bars"}: which value the bar length
encodes -- \code{"prop"} (default) or \code{"freq"}. Treemap and
hierarchical-marimekko areas always encode proportion within group.}

\item{label}{Inline tile / bar annotation. All formats render on a
single line.
\itemize{
\item \code{"prop"} (default) -- proportion only, e.g. \code{"66\%"}
\item \code{"freq"} -- count only, e.g. \code{"1,234"}
\item \code{"both"} -- count + proportion, e.g. \code{"1,234 (66\%)"}
\item \code{"state"} -- state name only, e.g. \code{"Average"}
\item \code{"all"} -- state + proportion, e.g. \code{"Average (66\%)"}
\item \code{"none"} -- no inline labels
}}

\item{legend}{Legend position. \code{"auto"} (default) resolves per
style: \code{"none"} for \code{style = "bars"} (the y-axis already
names every state, so a colour legend is redundant);
\code{"per_facet"} for \code{htna}/\code{mcml} treemaps (state
vocabularies differ per panel, so each gets its own legend);
\code{"bottom"} for single-network and \code{netobject_group}
treemaps (shared state vocabulary, one shared legend).
Override with any of \code{"bottom"}, \code{"top"}, \code{"right"},
\code{"left"}, \code{"none"}, or \code{"per_facet"}. The
\code{"per_facet"} option requires the \pkg{gridExtra} package and
returns a \code{gtable}.}

\item{legend_dir}{Legend internal layout: \code{"auto"} (default --
horizontal for top/bottom, vertical for left/right), or force
\code{"horizontal"} or \code{"vertical"} regardless of position.}

\item{legend_frame}{\code{"none"} (default) for an unframed legend, or
\code{"border"} to draw a thin grey rectangle around the legend
("legend enclosed in a square").}

\item{sort_states}{One of \code{"frequency"} (default -- most frequent
first), \code{"alpha"}, or \code{"none"}.}

\item{colors}{Optional character vector overriding the default
Okabe-Ito state palette. Length must be at least the number of unique
states.}

\item{label_size}{Numeric size of inline labels (max size when
\pkg{ggfittext} is installed -- text auto-shrinks per tile).}

\item{abbreviate}{Abbreviate state names. \code{FALSE} (default) shows
full names; \code{TRUE} truncates to the first 3 characters via
\code{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. \code{abbreviate = 4}).
Affects tile labels, legend, and the returned \code{$table}.}

\item{include_macro}{For \code{mcml} only: prepend a \code{"macro"}
reference column showing aggregate state frequencies across all
clusters. Default \code{FALSE}.}

\item{combine}{For \code{legend = "per_facet"} only. \code{"auto"}
(default) returns a single combined gtable for 1-3 panels and a
list of ggplots (one per panel) for 4+ panels -- many-cluster
\code{mcml} layouts read better as separate figures than as a tile
grid. \code{TRUE} forces a combined gtable via \pkg{gridExtra};
\code{FALSE} forces a list (knitr renders each at the chunk's full
\code{fig.width} / \code{fig.height}).}

\item{ncol}{For \code{legend = "per_facet"} with \code{combine = TRUE}:
number of columns in the grid arrangement. \code{NULL} (default)
picks 1, 2, or 3 columns based on the number of panels.}

\item{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.}
}
\value{
A \code{state_freq} object: a list with the rendered \code{$plot}
(a \code{ggplot} or \code{gtable}), the tidy \code{$table} (a
\code{data.frame} with columns \code{group}, \code{state}, \code{count},
\code{proportion}), and the call's \code{$style}, \code{$metric},
\code{$source_class}. The class supports \code{print()} (shows the
tidy table in the console), \code{plot()} (renders the chart), and
\code{as.data.frame()} (returns the table).
}
\description{
Visualise state (node) frequency distributions across groups for any
Nestimate object that carries sequence data: a single \code{netobject},
a \code{netobject_group}, an \code{mcml} model, or an \code{htna} network.
}
\details{
The marimekko layout is dispatched per class:
\itemize{
\item For \code{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.
\item For all other classes (\code{netobject}, \code{netobject_group},
\code{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.
}
\examples{
\donttest{
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))
}
}
}
