% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-motifs.R
\name{extract_sequence_ngrams}
\alias{extract_sequence_ngrams}
\title{Extract Contiguous Sequence N-Grams}
\usage{
extract_sequence_ngrams(
  data,
  sequence_id_col,
  order_col,
  state_col,
  duration_col = NULL,
  metadata_cols = NULL,
  expected_states = NULL,
  min_length = 2L,
  max_length = 3L,
  overlap = c("allow", "disallow"),
  separator = " > ",
  state_levels = 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{min_length}{Positive whole number giving the shortest motif length.}

\item{max_length}{Positive whole number giving the longest motif length.}

\item{overlap}{Character value specifying whether overlapping occurrences of
the same motif within the same sequence are \code{"allow"}ed or
\code{"disallow"}ed.}

\item{separator}{Character value used only to display state labels in the
human-readable \code{motif} column.}

\item{state_levels}{Optional atomic vector defining the complete state
ordering. When omitted, factor levels are respected; otherwise observed
labels are sorted deterministically.}
}
\value{
A named list containing:
\itemize{
\item \code{occurrences}: one row per retained contiguous motif occurrence;
\item \code{motifs}: the distinct motif dictionary;
\item \code{sequences}: sequence-level counts of candidate and retained occurrences;
\item \code{state_dictionary}: the deterministic state dictionary;
\item \code{audit}, \code{status}, and \code{mapping} from input validation;
\item \code{settings}: the resolved motif extraction settings.
}
}
\description{
Enumerates contiguous state motifs from validated long-format sequence data.
}
\details{
Motifs are contiguous windows only. No subsequence gaps, edit distances,
statistical tests, or substantive interpretations are introduced.
Consecutive repeated states are used exactly as supplied; any repeat
collapsing should be performed explicitly with \code{prepare_sequence_data()}
before extraction.

With \code{overlap = "disallow"}, overlap is resolved independently within each
sequence-motif pair by a deterministic left-to-right greedy rule. Different
motifs and different motif lengths do not compete for positions.

The collision-resistant \code{motif_id} and \code{motif_key} columns are derived from
deterministic state codes. The display separator may therefore also occur
inside a state label without changing motif identity.
}
\examples{
sequences <- data.frame(
  id = c(rep("s1", 5L), rep("s2", 4L)),
  position = c(1:5, 1:4),
  state = c("A", "B", "A", "B", "A", "A", "B", "A", "C")
)

ngrams <- extract_sequence_ngrams(
  sequences,
  sequence_id_col = "id",
  order_col = "position",
  state_col = "state",
  min_length = 2,
  max_length = 3,
  overlap = "allow"
)

ngrams$occurrences
ngrams$motifs

}
