% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-encoding-summaries.R
\name{summarise_sequence_states}
\alias{summarise_sequence_states}
\title{Summarise Sequence States}
\usage{
summarise_sequence_states(
  data,
  sequence_id_col,
  order_col,
  state_col,
  duration_col = NULL,
  metadata_cols = NULL,
  expected_states = NULL
)
}
\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{duration_col}{Optional name of a numeric duration 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.}
}
\value{
A named list containing:
\itemize{
\item \code{by_sequence}: state counts and proportions within each sequence;
\item \code{overall}: state counts and proportions across all sequences;
\item \code{audit}, \code{status}, and \code{mapping} from input validation.
}

When \code{duration_col} is supplied, both tables also include duration sums,
duration proportions, and mean durations.
}
\description{
Produces per-sequence and overall state-frequency summaries from validated
ordered sequence data.
}
\details{
Observation proportions use state rows as the denominator. Sequence
proportions report the proportion of sequences in which each state occurs.
Missing durations are excluded from duration calculations; an all-missing
duration group returns \code{NA}.
}
\examples{
sequences <- data.frame(
  id = c("s1", "s1", "s1", "s2", "s2"),
  position = c(1, 2, 3, 1, 2),
  state = c("A", "B", "A", "B", "C")
)

summaries <- summarise_sequence_states(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state"
)

summaries$by_sequence
summaries$overall

}
