% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-encoding-summaries.R
\name{summarise_sequence_transitions}
\alias{summarise_sequence_transitions}
\title{Summarise Adjacent Sequence Transitions}
\usage{
summarise_sequence_transitions(
  data,
  sequence_id_col,
  order_col,
  state_col,
  metadata_cols = NULL,
  expected_states = NULL,
  include_self = TRUE
)
}
\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{include_self}{Logical value indicating whether transitions from a
state to the same state should be included.}
}
\value{
A named list containing:
\itemize{
\item \code{by_sequence}: transition counts, proportions within each sequence, and
conditional proportions within each origin state;
\item \code{overall}: transition counts, sequence coverage, global proportions, and
conditional origin-state proportions;
\item \code{audit}, \code{status}, \code{mapping}, and the resolved \code{include_self} setting.
}
}
\description{
Counts transitions between adjacent ordered states for each sequence and
across the complete data set.
}
\details{
A transition is defined only between adjacent rows after deterministic
ordering by sequence identifier, sequence order, and original row.
Sequences with one state contribute no transitions.
}
\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")
)

transitions <- summarise_sequence_transitions(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state"
)

transitions$by_sequence
transitions$overall

}
