% 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,
  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,
  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 (\code{data.frame} or \code{matrix})
or a \code{net_clustering}. When a \code{net_clustering} is passed,
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{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)}.}

\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}}
}
