gp3sequences

gp3sequences is an independent R package for transparent, reproducible, and auditable analysis of ordered categorical sequences. It is designed for ordinary long-format data frames and is not restricted to Gazepoint exports, eye-tracking data, particular hardware, or proprietary software.

Development status

The package is in initial development and does not yet provide a stable public analytical API. The first development series prioritises a neutral data contract, explicit preprocessing policies, machine-readable diagnostics, and deterministic structural summaries.

Intended applications

Potential applications include:

• eye-tracking AOI scanpaths;
• website-navigation and customer-journey sequences;
• behavioural-state and task-action sequences;
• interface-interaction sequences;
• educational activity sequences;
• other repeated ordered categorical data.

Neutral long-format input

The core data contract will require configurable columns corresponding to sequence_id, sequence_order, and state. Optional participant, trial, condition, group, timing, duration, weight, and metadata columns may also be mapped explicitly.

A minimal input may look like this:

example_sequences <- data.frame(
  sequence_id = rep(c("s1", "s2"), each = 4L),
  sequence_order = rep(1:4, times = 2L),
  state = c(
    "home", "search", "product", "checkout",
    "home", "category", "product", "home"
  ),
  stringsAsFactors = FALSE
)

example_sequences
#>   sequence_id sequence_order    state
#> 1          s1              1     home
#> 2          s1              2   search
#> 3          s1              3  product
#> 4          s1              4 checkout
#> 5          s2              1     home
#> 6          s2              2 category
#> 7          s2              3  product
#> 8          s2              4     home

Current data-contract API

The initial public API provides three related functions:

• audit_sequence_data() reports structured data-quality issues;
• validate_sequence_data() returns a compact validity contract;
• prepare_sequence_data() applies explicit preprocessing policies and creates deterministic canonical sequence data.

audit <- audit_sequence_data(
  example_sequences,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state"
)

validation <- validate_sequence_data(
  example_sequences,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state"
)

prepared <- prepare_sequence_data(
  example_sequences,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  repeated_state_policy = "preserve"
)

Encoding and structural summaries

Related functions support deterministic encoding and descriptive sequence summaries without assigning substantive meaning to states:

• encode_sequence_data() creates a transparent state dictionary;
• summarise_sequence_states() reports state frequencies and durations;
• summarise_sequence_transitions() reports adjacent transition counts;
• format_sequence_paths() creates compact ordered path strings.

encoded <- encode_sequence_data(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state"
)

state_summary <- summarise_sequence_states(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state"
)

transition_summary <- summarise_sequence_transitions(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state"
)

paths <- format_sequence_paths(
  prepared$data,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state"
)

Contiguous motif analysis

The motif workflow enumerates contiguous state windows only and retains explicit structural definitions:

• extract_sequence_ngrams() extracts auditable motif occurrences;
• summarise_sequence_motifs() reports counts and sequence prevalence;
• filter_sequence_motifs() applies explicit transparent thresholds;
• format_sequence_motifs() creates stable report-ready tables.

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

motif_summary <- summarise_sequence_motifs(motif_occurrences)

motif_filter <- filter_sequence_motifs(
  motif_summary,
  min_sequences = 2,
  min_prevalence = 0.10,
  top_n = 20,
  ties = "include"
)

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

Motif positions and visualisation

Motif occurrences can be summarised and plotted without adding analytical dependencies:

• summarise_sequence_motif_positions() reports structural locations;
• format_sequence_motif_positions() produces explicit report tables;
• plot_sequence_motifs() plots prevalence or occurrence metrics;
• plot_sequence_motif_positions() plots occurrence locations.

position_summary <- summarise_sequence_motif_positions(
  motif_occurrences,
  position = "centre",
  scale = "relative"
)

position_table <- format_sequence_motif_positions(
  position_summary,
  position_units = "percent",
  digits = 1
)

plot_sequence_motifs(
  motif_summary,
  metric = "sequence_prevalence",
  top_n = 10
)

plot_sequence_motif_positions(
  motif_occurrences,
  position = "centre",
  scale = "relative",
  top_n = 5
)

Interpretation boundary

Sequence outputs describe behavioural or structural patterns only. They do not independently establish emotion, cognition, comprehension, personality, intention, diagnosis, deception, or other psychological attributes. Substantive interpretation requires an appropriate study design and external evidence.

Author

Stefanos Balaskas

ORCID · Personal website · LinkedIn

Licence

gp3sequences is released under the MIT License.