% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/distribution_plot.R
\name{distribution_plot}
\alias{distribution_plot}
\title{State Distribution Plot Over Time}
\usage{
distribution_plot(
  x,
  group = NULL,
  scale = c("proportion", "count"),
  geom = c("area", "bar"),
  na = TRUE,
  trim = NULL,
  trim_clusterwise = FALSE,
  state_colors = NULL,
  na_color = "grey90",
  frame = FALSE,
  width = NULL,
  height = NULL,
  main = NULL,
  show_n = TRUE,
  time_label = "Time",
  xlab = NULL,
  y_label = NULL,
  ylab = NULL,
  tick = NULL,
  ncol = NULL,
  nrow = NULL,
  combined = TRUE,
  legend = c("right", "bottom", "none"),
  legend_size = NULL,
  legend_title = NULL,
  legend_ncol = NULL,
  legend_border = NA,
  legend_bty = "n"
)
}
\arguments{
\item{x}{Wide-format sequence data. Accepts the same inputs as
\code{\link{sequence_plot}}: \code{data.frame}, \code{matrix},
\code{netobject}, \code{net_clustering}, \code{netobject_group},
\code{net_mmm}, or \code{tna}. When clustering info is available,
one panel is drawn per cluster.}

\item{group}{Optional grouping vector (length \code{nrow(x)}) producing
one panel per group. Ignored if \code{x} is a \code{net_clustering}.}

\item{scale}{\code{"proportion"} (default) divides each column by its
total so bands fill 0..1. \code{"count"} keeps raw counts.}

\item{geom}{\code{"area"} (default) draws stacked polygons;
\code{"bar"} draws stacked bars.}

\item{na}{If \code{TRUE} (default), \code{NA} cells are shown as an
extra band coloured \code{na_color}.}

\item{trim}{Optional time-axis truncation, to stop a few long
sequences from stretching the plot. \code{NULL} (default) keeps the
full width. A fraction in \code{(0, 1)} drops everything past that
quantile of sequence lengths (e.g. \code{trim = 0.95}); a value
\code{>= 1} is an absolute cut (\code{trim = 50} keeps the first 50
time points). See \code{\link{sequence_plot}}.}

\item{trim_clusterwise}{Grouped plots only, fractional \code{trim}
only. \code{FALSE} (default) uses one pooled cutoff for every panel
so the time axes stay aligned; \code{TRUE} crops each group to its
own length quantile (panels can differ in width). See
\code{\link{sequence_plot}}.}

\item{state_colors}{Vector of colours, one per state. Defaults to
Okabe-Ito.}

\item{na_color}{Colour for the \code{NA} band.}

\item{frame}{If \code{TRUE} (default), draw a box around each panel.}

\item{width, height}{Optional device dimensions. See
\code{\link{sequence_plot}}.}

\item{main}{Plot title.}

\item{show_n}{Append \code{"(n = N)"} (per-group when grouped) to the
title.}

\item{time_label}{X-axis label.}

\item{xlab}{Alias for \code{time_label}.}

\item{y_label}{Y-axis label. Defaults to \code{"Proportion"} or
\code{"Count"} based on \code{scale}.}

\item{ylab}{Alias for \code{y_label}.}

\item{tick}{Show every Nth x-axis label. \code{NULL} = auto.}

\item{ncol, nrow}{Facet grid dimensions. \code{NULL} = auto:
\code{ncol = ceiling(sqrt(G))}, \code{nrow = ceiling(G / ncol)}.
Ignored when \code{combined = FALSE}.}

\item{combined}{When \code{TRUE} (default), groups are arranged on one
figure via \code{graphics::layout()}. When \code{FALSE}, each group
is drawn on its own page (one full-size figure per group, with its
own legend). Useful when you want each group at full size in knitr
(\code{fig.show = "asis"}) or to save each as a separate file.
Single-group calls (\code{G == 1}) ignore this argument.}

\item{legend}{Legend position: \code{"right"} (default),
\code{"bottom"}, or \code{"none"}.}

\item{legend_size}{Legend text size. \code{NULL} (default) auto-scales
from device width (clamped to \code{[0.65, 1.2]}).}

\item{legend_title}{Optional legend title.}

\item{legend_ncol}{Number of legend columns.}

\item{legend_border}{Swatch border colour.}

\item{legend_bty}{\code{"n"} (borderless) or \code{"o"} (boxed).}
}
\value{
Invisibly, a list with \code{counts}, \code{proportions},
\code{levels}, \code{palette}, and \code{groups}.
}
\description{
Draws how state proportions (or counts) evolve across time points. For
each time column, tabulates how many sequences are in each state and
renders the result as a stacked area (default) or stacked bar chart.
Accepts the same inputs as \code{\link{sequence_plot}}.
}
\examples{
\donttest{
distribution_plot(as.data.frame(trajectories))
}
}
\seealso{
\code{\link{sequence_plot}}, \code{\link{build_clusters}}
}
