% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-motifs.R
\name{summarise_sequence_motifs}
\alias{summarise_sequence_motifs}
\title{Summarise Contiguous Sequence Motifs}
\usage{
summarise_sequence_motifs(x)
}
\arguments{
\item{x}{An object returned by \code{extract_sequence_ngrams()}.}
}
\value{
A named list containing:
\itemize{
\item \code{by_sequence}: occurrence counts for each sequence-motif pair;
\item \code{overall}: total occurrence counts, sequence counts, sequence prevalence,
occurrence share, and mean occurrence rates;
\item \code{sequences} and \code{state_dictionary} from extraction;
\item \code{audit}, \code{status}, \code{mapping}, and extraction settings;
\item scalar counts for sequences, occurrences, and distinct motifs.
}
}
\description{
Aggregates extracted contiguous motif occurrences by sequence and overall.
}
\details{
Sequence prevalence uses every validated sequence in the extraction object as
its denominator, including sequences too short to contain a requested motif.
Results are sorted deterministically by sequence prevalence, occurrence
count, motif length, and motif key.

The function reports structural recurrence only. It does not perform
significance testing or infer psychological, cognitive, emotional, or
diagnostic attributes.
}
\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")
)

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

summaries <- summarise_sequence_motifs(extracted)
summaries$by_sequence
summaries$overall

}
