% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-encoding-summaries.R
\name{format_sequence_paths}
\alias{format_sequence_paths}
\title{Format Ordered Sequence Paths}
\usage{
format_sequence_paths(
  data,
  sequence_id_col,
  order_col,
  state_col,
  metadata_cols = NULL,
  expected_states = NULL,
  separator = " > ",
  collapse_repeats = FALSE
)
}
\arguments{
\item{data}{A data frame containing ordered state observations.}

\item{sequence_id_col}{Name of the sequence identifier column.}

\item{order_col}{Name of the numeric sequence-order column.}

\item{state_col}{Name of the categorical state column.}

\item{metadata_cols}{Optional character vector naming columns that should
remain constant within each sequence.}

\item{expected_states}{Optional vector of known or permitted state values.}

\item{separator}{Character value inserted between adjacent state labels.}

\item{collapse_repeats}{Logical value indicating whether consecutive
repeated states should be collapsed for path display.}
}
\value{
A named list containing:
\itemize{
\item \code{paths}: one row per sequence with observation counts, formatted-state
counts, unique-state counts, start and end states, and the path string;
\item \code{audit}, \code{status}, and \code{mapping} from input validation;
\item \code{settings}: the path separator and repeat-collapsing choice.
}
}
\description{
Creates a compact one-row-per-sequence representation of ordered state
paths.
}
\details{
Repeat collapsing affects only the formatted representation. It does not
modify the supplied data or alter non-consecutive repeated states.
Input rows are ordered deterministically for formatting, but review-level
diagnostics such as \code{unordered_rows} remain reflected in the returned
\code{status} and \code{audit}.
}
\examples{
sequences <- data.frame(
  id = c("s1", "s1", "s1", "s2", "s2"),
  position = c(1, 2, 3, 1, 2),
  state = c("A", "B", "C", "A", "C")
)

paths <- format_sequence_paths(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state"
)

paths$paths

}
