Getting Started with gp3sequences
In gp3sequences: Transparent Analysis of Ordered Categorical Sequences

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4.5
)
library(gp3sequences)

Purpose

gp3sequences accepts ordinary long-format ordered categorical data. This article introduces the complete structural workflow: audit, preparation, encoding, descriptive summaries, contiguous motifs, distances, clustering, consensus, group comparison, and transition structure.

All outputs are structural or statistical. They do not independently establish attention, cognition, emotion, comprehension, intention, diagnosis, causality, or other psychological attributes.

Synthetic long-format data

Each sequence has an identifier, an explicit order, a categorical state, a positive duration, participant metadata, and an assigned interface group.

paths <- list(
  s1 = c("home", "search", "product", "cart", "checkout"),
  s2 = c("home", "search", "product", "cart", "home"),
  s3 = c("home", "category", "product", "cart", "checkout"),
  s4 = c("home", "category", "product", "search", "checkout"),
  s5 = c("home", "category", "search", "product", "checkout"),
  s6 = c("home", "search", "category", "product", "home"),
  s7 = c("home", "category", "product", "cart", "home"),
  s8 = c("home", "search", "product", "checkout", "home")
)

raw_sequences <- do.call(
  rbind,
  lapply(seq_along(paths), function(i) {
    data.frame(
      sequence_id = names(paths)[i],
      sequence_order = seq_along(paths[[i]]),
      state = paths[[i]],
      duration = 80 + 10 * seq_along(paths[[i]]) + i,
      participant_id = sprintf("p%02d", i),
      group = if (i <= 4L) "interface_a" else "interface_b",
      stringsAsFactors = FALSE
    )
  })
)

raw_sequences

Audit, validate, and prepare

audit_sequence_data() returns a machine-readable issue table without modifying the input. validate_sequence_data() adds a compact status contract. prepare_sequence_data() applies explicit policies and returns canonical data, an audit trail, and a decision log.

audit <- audit_sequence_data(
  raw_sequences,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  duration_col = "duration",
  metadata_cols = c("participant_id", "group")
)

validation <- validate_sequence_data(
  raw_sequences,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  duration_col = "duration",
  metadata_cols = c("participant_id", "group")
)

prepared <- prepare_sequence_data(
  raw_sequences,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  duration_col = "duration",
  metadata_cols = c("participant_id", "group"),
  missing_state_policy = "error",
  duplicate_position_policy = "error",
  repeated_state_policy = "preserve",
  zero_duration_policy = "preserve",
  unknown_state_policy = "preserve",
  unused_state_levels = "preserve"
)

validation$status
prepared$status
prepared$mapping
prepared$decisions
head(prepared$data)

Encode states and inspect basic structure

State codes are transparent identifiers derived from a deterministic state ordering. The state, transition, and path helpers describe the observed structure without assigning substantive meaning to the labels.

encoded <- encode_sequence_data(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  duration_col = "duration",
  metadata_cols = c("participant_id", "group")
)

state_summary <- summarise_sequence_states(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  duration_col = "duration",
  metadata_cols = c("participant_id", "group")
)

transition_summary <- summarise_sequence_transitions(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  metadata_cols = c("participant_id", "group"),
  include_self = TRUE
)

paths_table <- format_sequence_paths(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  metadata_cols = c("participant_id", "group")
)

encoded$dictionary
state_summary$overall
head(transition_summary$overall)
paths_table$paths

Discover contiguous motifs

Motifs are exact contiguous state windows. Their lengths, overlap rule, prevalence denominator, filtering thresholds, and tie policy remain explicit.

motif_occurrences <- extract_sequence_ngrams(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  metadata_cols = "group",
  min_length = 2L,
  max_length = 3L,
  overlap = "allow"
)

motif_summary <- summarise_sequence_motifs(motif_occurrences)

motif_filter <- filter_sequence_motifs(
  motif_summary,
  min_occurrences = 2L,
  min_sequences = 2L,
  min_prevalence = 0.20,
  motif_lengths = c(2L, 3L),
  top_n = 10L,
  rank_by = "sequence_prevalence",
  ties = "include"
)

motif_table <- format_sequence_motifs(
  motif_filter,
  prevalence = "percent",
  digits = 1L
)

motif_table$table

Compare sequences through distances and clustering

Distance choice is part of the analysis specification. This example uses LCS distance followed by average-linkage hierarchical clustering. Validation summaries describe the supplied solution; they do not prove that the clusters are natural or substantively meaningful.

lcs_distance <- compute_sequence_distance(
  prepared$data,
  method = "lcs",
  normalise = "max_length"
)

cluster_fit <- cluster_sequences(
  lcs_distance,
  k = 2L,
  method = "hierarchical",
  linkage = "average"
)

cluster_validation <- validate_sequence_clusters(cluster_fit)
representatives <- extract_representative_sequences(cluster_fit)

summarise_sequence_distance(lcs_distance)$overall
cluster_fit$assignments
cluster_validation$overall
representatives

Consensus and descriptive group comparison

Aligned-position consensus and group contrasts remain descriptive. The consensus is not a behavioural norm, and contrasts do not establish a causal mechanism.

consensus <- create_consensus_sequence(
  prepared$data,
  group_cols = "group",
  tie_method = "first",
  state_levels = encoded$dictionary$state
)

group_comparison <- compare_sequence_groups(
  prepared$data,
  group_col = "group"
)

summarise_consensus_agreement(consensus, by = "group")
format_consensus_sequence(consensus, include_agreement = TRUE)
head(group_comparison$state_contrasts)
head(group_comparison$transition_contrasts)
group_comparison$length_contrasts

Transition structure

A first-order transition network summarises observed state-to-state movement. Centrality and community outputs are graph descriptors, not measures of attention, influence, preference, or intention.

network <- create_transition_network(
  prepared$data,
  normalise = "from",
  include_self = TRUE
)

network
summarise_transition_centrality(network)
detect_transition_communities(network)

Continue with focused articles

The package website contains focused articles for motif positions, consensus and groups, distances and clustering, transition networks, latent models, and optional ecosystem adapters. The method-selection article provides a compact guide to choosing among them.