Ordered categorical sequence analysis, built for transparent research.
Validate sequence data, describe paths and motifs, compare whole-sequence structure, cluster trajectories, model transitions and latent states, run design-aware inference, and communicate results with publication-ready plots.
gp3sequencespy is the Python implementation of the frozen gp3sequences 0.3.0
public contract. Version 0.1.2 is available from PyPI and preserves the
frozen scientific/API contracts while adding complete statement/branch coverage,
mutation-smoke protection, robustness repairs, and expanded documentation. The package is designed around explicit assumptions, auditable
transformations, reproducible parameter choices, and bounded interpretation.
Start with your research question¶
Prepare & validate
Audit order, missing states, durations, duplicated positions, metadata, and explicit preparation policies before analysis.
Describe sequence structure
Summarise state occupancy, transitions, complete paths, consensus structure, contiguous motifs, and non-contiguous subsequences.
Compare whole sequences
Compute edit-, LCS-, optimal-matching-, or transition-profile distances; cluster; validate; bootstrap; and identify representatives.
Model transitions
Build transition networks, inspect centrality and communities, fit higher-order transition models, and predict next-state structure.
Fit latent models
Use categorical, mixture, multichannel, and covariate-dependent HMM workflows with explicit convergence and interpretation boundaries.
Run design-aware inference
Declare the comparison design and use randomization-aware group testing rather than treating descriptive differences as causal evidence.
A complete structural workflow¶
import pandas as pd
import gp3sequencespy as g
data = pd.DataFrame(
{
"sequence_id": ["s1", "s1", "s1", "s2", "s2", "s2"],
"sequence_order": [1, 2, 3, 1, 2, 3],
"state": ["home", "search", "product", "home", "category", "product"],
}
)
validation = g.validate_sequence_data(
data,
"sequence_id",
"sequence_order",
"state",
)
prepared = g.prepare_sequence_data(
data,
"sequence_id",
"sequence_order",
"state",
)
states = g.summarise_sequence_states(prepared.data)
distance = g.compute_sequence_distance(prepared.data, method="lcs")
network = g.create_transition_network(prepared.data, normalise="from")
Visualise what changes across a sequence¶
The thumbnails are documentation illustrations of the supported plot families. Use the plot gallery for the exact package calls and interpretation notes.
What makes the package different¶
Parity-first
The frozen R 0.3.0 release remains the behavioral reference. Public signatures, deterministic oracles, and deliberate translation boundaries are documented rather than hidden.
Audit-first
Validation and preparation are explicit objects and policies, so preprocessing choices can be inspected and reported instead of being implicit.
Research-design aware
Descriptive sequence differences, randomization-based inference, and causal interpretation are kept conceptually separate.
Python-native
Outputs integrate with pandas, NumPy, SciPy, Matplotlib, and NetworkX while preserving the frozen scientific contracts.
Interpretation boundary¶
Sequence structure is not a psychological state
Sequence structure does not independently establish attention, cognition, emotion, comprehension, personality, intention, deception, diagnosis, or causality. Observational group contrasts remain associational unless a defensible randomized design supports causal interpretation.
Release and reproducibility status¶
Version 0.1.2 is published through GitHub Releases and PyPI. The frozen scientific/API contracts remain 81 / 81 public R counterparts, 81 / 81 audited signatures, and 130 / 130 translated frozen R test blocks; the Python quality suite now contains 292 tests with 100% statement and branch coverage. Cross-language boundaries that cannot be made bit-identical are listed in Parity & validation.