% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-motif-visualisation.R
\name{summarise_sequence_motif_positions}
\alias{summarise_sequence_motif_positions}
\title{Summarise Sequence Motif Positions}
\usage{
summarise_sequence_motif_positions(
  x,
  position = c("start", "centre", "end"),
  scale = c("absolute", "relative"),
  by = NULL
)
}
\arguments{
\item{x}{An object returned by \code{extract_sequence_ngrams()}.}

\item{position}{Position represented by each occurrence: motif \code{"start"},
\code{"centre"}, or \code{"end"}.}

\item{scale}{Position scale: one-based \code{"absolute"} sequence positions or
\code{"relative"} positions from 0 to 1.}

\item{by}{Optional character vector naming preserved metadata columns used
to produce separate summaries, such as \code{"group"} or \code{"condition"}.}
}
\value{
A named list containing:
\itemize{
\item \code{summary}: one row per motif and optional metadata group;
\item \code{occurrences}: occurrence-level absolute, relative, and selected-scale
positions;
\item \code{sequences}, validation metadata, and extraction settings;
\item \code{settings}: the resolved position basis, scale, and grouping columns.
}

The summary reports motif identifiers and labels, motif length, occurrence
and sequence counts, and minimum, maximum, mean, and median positions.
}
\description{
Summarises where contiguous motif occurrences appear within sequences.
}
\details{
Absolute positions use the one-based state index within each validated
sequence. Relative positions are calculated as
\code{(absolute_position - 1) / (n_states - 1)} and are constrained to the
interval from 0 to 1. A sequence containing one state is assigned relative
position 0.

Grouping is descriptive. The function does not test differences or attach
behavioural, psychological, cognitive, or causal interpretations to motif
location.
}
\examples{
sequences <- data.frame(
  id = c(rep("s1", 5L), rep("s2", 4L)),
  position = c(1:5, 1:4),
  state = c("A", "B", "A", "B", "C", "A", "B", "C", "B"),
  group = c(rep("g1", 5L), rep("g2", 4L))
)

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

positions <- summarise_sequence_motif_positions(
  extracted,
  position = "centre",
  scale = "relative",
  by = "group"
)

positions$summary

}
