% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence_plot.R
\name{sequence_plot}
\alias{sequence_plot}
\title{Sequence Plot (heatmap, index, or distribution)}
\usage{
sequence_plot(
  x,
  type = c("heatmap", "index", "distribution"),
  sort = c("lcs", "frequency", "start", "end", "hamming", "osa", "lv", "dl", "qgram",
    "cosine", "jaccard", "jw"),
  tree = NULL,
  group = NULL,
  scale = c("proportion", "count"),
  geom = c("area", "bar"),
  na = TRUE,
  normalize = FALSE,
  trim = NULL,
  trim_clusterwise = FALSE,
  row_gap = 0,
  dendrogram_width = 1.2,
  k = NULL,
  k_color = "white",
  k_line_width = 2.5,
  state_colors = NULL,
  na_color = "grey90",
  cell_border = NA,
  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 = NULL,
  legend_size = NULL,
  legend_title = NULL,
  legend_ncol = NULL,
  legend_border = NA,
  legend_bty = "n"
)
}
\arguments{
\item{x}{Wide-format sequence data. Accepts:
\describe{
\item{data.frame / matrix}{Rows = sequences, columns = time points.}
\item{netobject}{Extracts \code{$data}.}
\item{net_clustering}{From \code{\link{build_clusters}}. Uses
\code{$data}, \code{$assignments} for grouping, and \code{$distance}
for dendrogram.}
\item{netobject_group}{From \code{\link{cluster_network}} or
\code{\link{build_network}} on a clustering. Extracts data and
assignments from \code{attr(, "clustering")}.
}
\item{net_mmm}{From \code{\link{build_mmm}}. Uses \code{$models[[1]]$data}
and \code{$assignments}.}
\item{tna}{From the tna package. Decodes integer-encoded sequences.}
\item{mcml}{From \code{\link{build_mcml}} (built from sequences).
Produces a \strong{multichannel} plot: one panel per cluster plus a
macro \code{Summary} panel. \code{type = "heatmap"}/\code{"index"}
draw the carpet (each channel's own states solid, other clusters a
faded wash); \code{type = "distribution"} draws the stacked
distribution (add \code{normalize = TRUE} for a TraMineR-style
\code{seqdplot} where each time point sums to 1). Returns a
\code{ggplot} object.}
}}

\item{type}{One of \code{"heatmap"} (default), \code{"index"}, or
\code{"distribution"}.}

\item{sort}{Row-ordering strategy for heatmap / within-panel for index.
One of \code{"lcs"} (default), \code{"frequency"}, \code{"start"},
\code{"end"}, or any \code{\link{build_clusters}} distance
(\code{"hamming"}, \code{"osa"}, \code{"lv"}, \code{"dl"},
\code{"qgram"}, \code{"cosine"}, \code{"jaccard"}, \code{"jw"}).}

\item{tree}{Optional \code{hclust}/\code{dendrogram}/\code{agnes}
object to supply row ordering (heatmap only; overrides \code{sort}).}

\item{group}{Optional grouping vector (length \code{nrow(x)}) producing
one facet per group. Index/distribution only. Ignored for heatmap.}

\item{scale, geom, na}{Passed to \code{\link{distribution_plot}} when
\code{type = "distribution"}.}

\item{normalize}{\code{mcml} + \code{type = "distribution"} only. When
\code{TRUE}, each time point is normalised to sum to 1 within its channel
(TraMineR-style \code{seqdplot} composition); when \code{FALSE} (default)
the stack shows prevalence and is capped with an \code{NA} band.}

\item{trim}{Optional time-axis truncation, to stop a few long
sequences from stretching the plot. Applies to all three types
(including the \code{mcml} multichannel view). \code{NULL} (default)
plots the full width. A fraction in \code{(0, 1)} drops everything
past that quantile of sequence lengths (e.g. \code{trim = 0.95} keeps
the columns covering the shortest 95\\% of sequences); a value
\code{>= 1} is an absolute cut (\code{trim = 50} keeps the first 50
time points).}

\item{trim_clusterwise}{Grouped \code{type = "index"} /
\code{"distribution"} only, and only when \code{trim} is a fraction.
\code{FALSE} (default) computes one cutoff on the pooled data and
applies it to every panel, so all facets share the same width and the
time axes stay aligned. \code{TRUE} crops each group to its own
length quantile, so panels can end up at different widths (ragged
axes). Absolute \code{trim} (\code{>= 1}) ignores this - the column is
the same everywhere either way.}

\item{row_gap}{Fraction of row height used as vertical gap between
sequences in index plots. \code{0} (default) = dense like heatmap.
Try \code{0.15} for visible separators at low row counts.}

\item{dendrogram_width}{Width ratio of the dendrogram panel (heatmap).}

\item{k}{Optional integer. When supplied in \code{type = "heatmap"},
cuts the dendrogram into \code{k} clusters and draws thin horizontal
separators between them in the carpet. Ignored when there is no
dendrogram (e.g. \code{sort = "start"}) or for other types.}

\item{k_color}{Colour for the cluster separator lines. Default
\code{"white"}.}

\item{k_line_width}{Line width for the cluster separators. Default
\code{2.5}.}

\item{state_colors}{Vector of colours, one per state.}

\item{na_color}{Colour for \code{NA} cells.}

\item{cell_border}{Cell border colour. \code{NA} = off.}

\item{frame}{If \code{TRUE} (default), draw a box around each panel.
If \code{FALSE}, no box - axis ticks and labels still appear.}

\item{width, height}{Optional device dimensions in inches. When supplied,
opens a new graphics device via \code{grDevices::dev.new()}. In knitr
chunks use the \code{fig.width} / \code{fig.height} chunk options
instead.}

\item{main}{Plot title.}

\item{show_n}{Append \code{"(n = N)"} to the title.}

\item{time_label, xlab}{X-axis label. \code{xlab} is an alias.}

\item{y_label, ylab}{Y-axis label (distribution only). \code{ylab} alias.}

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

\item{ncol, nrow}{Facet grid dimensions (index + distribution).
Ignored when \code{combined = FALSE}.}

\item{combined}{Index and distribution types only. 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). Single-group calls (\code{G == 1}) ignore this argument.
Heatmap is always single-figure.}

\item{legend}{Legend position: \code{"bottom"}, \code{"right"}, or
\code{"none"}. Default varies by type.}

\item{legend_size}{Legend text size. \code{NULL} (default) auto-scales
from the device width so the legend looks proportional at 5 in vs
12 in figures (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"} or \code{"o"}.}
}
\value{
For base-graphics types, invisibly a list describing the plot
(shape depends on \code{type}). For an \code{mcml} input, a \code{ggplot}
object.
}
\description{
Single entry point for three categorical-sequence visualisations.
\itemize{
\item \code{type = "heatmap"} (default): dense carpet, rows reordered
by \code{sort} / dendrogram (single panel).
\item \code{type = "index"}: same data layout, but rows separated by
thin gaps (no dendrogram). Supports grouping via \code{group} or a
\code{net_clustering}, plus a \code{ncol} x \code{nrow} facet grid.
\item \code{type = "distribution"}: dispatches to
\code{\link{distribution_plot}}.
}
}
\examples{
\donttest{
sequence_plot(trajectories)
sequence_plot(trajectories, type = "index")
sequence_plot(trajectories, type = "distribution")

# Multichannel MCML view: one channel per cluster + a macro Summary.
fit <- build_mcml(
  group_regulation_long,
  clusters = list(Cognitive  = c("discuss", "synthesis", "consensus", "cohesion"),
                  Regulation = c("plan", "monitor", "adapt", "coregulate"),
                  Affective  = "emotion"),
  actor = "Actor", action = "Action", time = "Time")
sequence_plot(fit)                                          # multichannel carpet
sequence_plot(fit, type = "distribution")                  # prevalence + NA band
sequence_plot(fit, type = "distribution", normalize = TRUE) # seqdplot (sums to 1)
}
}
\seealso{
\code{\link{distribution_plot}}, \code{\link{build_clusters}},
\code{\link{build_mcml}}
}
