gp3sequencespy

Transparent, reproducible sequence analysis in Python.
Audit ordered categorical data, discover recurring structure, compare trajectories, model transitions and latent states, test group differences, and report every analytical choice.

Documentation · Quickstart · Method map · Plot gallery · API reference · v0.1.4

gp3sequencespy is the Python implementation of gp3sequences 0.3.0 for ordered categorical sequences and scanpaths. The frozen R 0.3.0 tarball is the behavioral reference: scientific contracts are preserved and tested explicitly, while deliberate R→Python translations are documented rather than hidden.

The package is designed for research workflows where data preparation, method choice, reproducibility, and interpretation need to remain visible from input to report.

Install

pip install gp3sequencespy==0.1.4

With uv:

uv add gp3sequencespy==0.1.4

Python 3.11–3.14 is supported. Optional extras are available for HMM backends, Arrow/Polars data interoperability, performance helpers, time-varying models, documentation, and development.

pip install "gp3sequencespy[hmm]"
pip install "gp3sequencespy[data]"
pip install "gp3sequencespy[time]"

A 60-second workflow

import pandas as pd
import gp3sequencespy as g

# One row per observed state occurrence.
data = pd.DataFrame(
    {
        "sequence_id": ["s1", "s1", "s1", "s2", "s2", "s2"],
        "sequence_order": [1, 2, 3, 1, 2, 3],
        "state": ["home", "search", "checkout", "home", "product", "checkout"],
    }
)

# Audit and prepare explicitly.
validation = g.validate_sequence_data(
    data,
    "sequence_id",
    "sequence_order",
    "state",
)
prepared = g.prepare_sequence_data(
    data,
    "sequence_id",
    "sequence_order",
    "state",
)

# Compare complete trajectories.
distance = g.compute_sequence_distance(
    prepared.data,
    method="lcs",
    normalise="max_length",
)

# Inspect transition structure.
network = g.create_transition_network(
    prepared.data,
    normalise="from",
)

# Visualise complete paths.
ax = g.plot_sequence_index(prepared.data)

For the complete path from raw long-format data to summaries, motifs, clustering, networks, plots, and analysis auditing, see the Quickstart.

What you can do

Not sure which family fits your question? Use the method map to move from research question → assumptions → method family.

Parity and validation

Version 0.1.4 is a maintenance release preserving the 0.1.2 scientific contracts while strengthening release automation and public documentation.

The deterministic core, hierarchical/PAM, and time-varying-model cross-language oracle tranches have been executed against frozen R 0.3.0. Remaining deliberate boundaries are recorded in PARITY_EXCEPTIONS.md, with broader parity evidence in PARITY_TEST_MATRIX.md and the online parity guide.

Documentation routes

Reproducibility and release governance

The package treats release and parity evidence as part of the scientific software contract.

• REPRODUCIBILITY.md — frozen-reference and reproducibility policy
• PARITY_EXCEPTIONS.md — deliberate R→Python boundaries
• SIGNATURE_PARITY.md — frozen public-signature audit
• QUALITY_COMPLETION.md — 100% coverage and mutation-hardening evidence
• RELEASE_CHECKLIST.md — stable-release gates
• PYPI_PUBLISHING.md — Trusted Publishing and artifact verification
• CHANGELOG.md — release history

Stable releases publish the exact validated GitHub Release wheel and source distribution to PyPI through GitHub OIDC Trusted Publishing. Each publication is subsequently checked against the GitHub Release SHA-256 hashes and with a clean PyPI installation.

Development

uv sync --all-extras --python 3.12
uv run pytest -q

Full quality gate:

uv run pytest -q \
  --cov=gp3sequencespy \
  --cov-branch \
  --cov-report=term-missing \
  --cov-fail-under=100

uv run python scripts/run_mutation_smoke.py

See CONTRIBUTING.md for contribution guidance and SECURITY.md for the security policy.

Citation

If gp3sequencespy contributes to your research, use the repository citation metadata in CITATION.cff and the archived Zenodo record:

DOI: 10.5281/zenodo.22166449

Scientific interpretation guardrail

Sequence structure does not independently establish emotion, cognition, comprehension, personality, intention, deception, diagnosis, or causality. Observational group contrasts are associational unless a valid randomized design supports a causal interpretation.

Documentation · PyPI · Releases · Zenodo