% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-encoding-summaries.R
\name{encode_sequence_data}
\alias{encode_sequence_data}
\title{Encode Ordered Sequence States}
\usage{
encode_sequence_data(
  data,
  sequence_id_col,
  order_col,
  state_col,
  duration_col = NULL,
  metadata_cols = NULL,
  expected_states = NULL,
  state_levels = NULL,
  prefix = "S",
  width = 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.}

\item{state_levels}{Optional atomic vector defining the complete state
ordering. When omitted, factor levels are respected; otherwise observed
state labels are sorted alphabetically.}

\item{prefix}{Character prefix used for labelled codes.}

\item{width}{Optional positive integer width for the numeric part of each
labelled code. The default is determined from the dictionary size.}
}
\value{
A named list containing:
\itemize{
\item \code{data}: deterministically sorted canonical data with \code{state_index} and
\code{state_code};
\item \code{dictionary}: state labels, integer indices, labelled codes, and an
observed-state indicator;
\item \code{audit}, \code{status}, and \code{mapping} from input validation;
\item \code{settings}: the resolved code prefix and width.
}
}
\description{
Creates a deterministic dictionary and adds integer and labelled state
codes to long-format sequence data.
}
\details{
The function does not reinterpret states. State codes are transparent
identifiers derived from an explicit or deterministic state ordering.
}
\examples{
sequences <- data.frame(
  id = c("s1", "s1", "s2", "s2"),
  position = c(1, 2, 1, 2),
  state = c("home", "search", "home", "product")
)

encoded <- encode_sequence_data(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state"
)

encoded$dictionary
encoded$data

}
