summarise_sequence_motif_positions: Summarise Sequence Motif Positions

In gp3sequences: Transparent Analysis of Ordered Categorical Sequences

Summarise Sequence Motif Positions

Description

Summarises where contiguous motif occurrences appear within sequences.

Usage

summarise_sequence_motif_positions(
  x,
  position = c("start", "centre", "end"),
  scale = c("absolute", "relative"),
  by = NULL
)

Arguments

x	An object returned by extract_sequence_ngrams().
position	Position represented by each occurrence: motif "start", "centre", or "end".
scale	Position scale: one-based "absolute" sequence positions or "relative" positions from 0 to 1.
by	Optional character vector naming preserved metadata columns used to produce separate summaries, such as "group" or "condition".

Details

Absolute positions use the one-based state index within each validated sequence. Relative positions are calculated as (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.

Value

A named list containing:

• summary: one row per motif and optional metadata group;

• occurrences: occurrence-level absolute, relative, and selected-scale positions;

• sequences, validation metadata, and extraction settings;

• 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.

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

gp3sequences documentation built on Aug. 23, 2026, 5:10 p.m.