% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-data.R
\name{prepare_sequence_data}
\alias{prepare_sequence_data}
\title{Prepare Long-Format Sequence Data}
\usage{
prepare_sequence_data(
  data,
  sequence_id_col,
  order_col,
  state_col,
  duration_col = NULL,
  metadata_cols = NULL,
  expected_states = NULL,
  missing_state_policy = c("error", "drop"),
  duplicate_position_policy = c("error", "first", "last"),
  repeated_state_policy = c("preserve", "collapse"),
  zero_duration_policy = c("preserve", "drop", "error"),
  unknown_state_policy = c("preserve", "drop", "error"),
  unused_state_levels = c("preserve", "drop")
)
}
\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{missing_state_policy}{Policy for missing states: \code{"error"} or
\code{"drop"}.}

\item{duplicate_position_policy}{Policy for duplicated sequence positions:
\code{"error"}, \code{"first"}, or \code{"last"}.}

\item{repeated_state_policy}{Policy for consecutive repeated states:
\code{"preserve"} or \code{"collapse"}.}

\item{zero_duration_policy}{Policy for zero durations: \code{"preserve"},
\code{"drop"}, or \code{"error"}.}

\item{unknown_state_policy}{Policy for states absent from
\code{expected_states}: \code{"preserve"}, \code{"drop"}, or \code{"error"}.}

\item{unused_state_levels}{Policy for unused factor levels: \code{"preserve"}
or \code{"drop"}.}
}
\value{
A named list containing:
\itemize{
\item \code{data}: canonical prepared data, or \code{NULL} when unresolved errors remain;
\item \code{audit}: input- and output-stage diagnostics;
\item \code{decisions}: a machine-readable preprocessing decision log;
\item \code{mapping}: source-to-contract column mappings;
\item \code{status}: \code{pass}, \code{review}, or \code{fail};
\item row counts and final state levels.
}

The canonical columns are \code{sequence_id}, \code{sequence_order}, \code{state},
\code{original_row}, and optional \code{duration}. Unmapped columns are preserved.
}
\description{
Applies explicit preprocessing policies and returns a deterministic,
canonical long-format representation.
}
\details{
Rows are sorted deterministically by sequence identifier, sequence order,
and original row number. When consecutive repeats are collapsed, the first
row supplies non-duration values and available durations are summed.

Unresolved errors produce \code{status = "fail"} and \code{data = NULL}; diagnostics
and decision records remain available.
}
\examples{
sequences <- data.frame(
  id = c("s2", "s1", "s1", "s2"),
  position = c(2, 2, 1, 1),
  state = c("product", "search", "home", "home")
)

prepared <- prepare_sequence_data(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state"
)

prepared$status
prepared$data

}
