% 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,
  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,
  legend = NULL,
  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}. One row per sequence, one column per
time point.}

\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{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).}

\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{
Invisibly, a list describing the plot (shape depends on
\code{type}).
}
\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")
}
}
\seealso{
\code{\link{distribution_plot}}, \code{\link{build_clusters}}
}
