gp3sequencespy 0.1.0__tar.gz

gp3sequencespy-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Report a reproducible defect or parity regression
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for reporting a reproducible problem.
+  - type: input
+    id: version
+    attributes:
+      label: gp3sequencespy version or commit
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproducible example
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: observed
+    attributes:
+      label: Observed behavior
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python, pandas/numpy/scipy versions, and optional extras.

gp3sequencespy-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://stefanosbalaskas.github.io/gp3sequencespy/
+    about: Check the documentation and parity notes before filing an issue.

gp3sequencespy-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Propose a parity-preserving or Python-native extension
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Scientific or software problem
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed API or behavior
+    validations:
+      required: true
+  - type: dropdown
+    id: relationship
+    attributes:
+      label: Relationship to frozen R 0.3.0
+      options:
+        - Direct parity counterpart
+        - Parity clarification or bug fix
+        - Python-native extension after frozen parity
+        - Unsure
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Methodological references or examples

gp3sequencespy-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Summary
+
+Describe the change and the scientific/software contract it affects.
+
+## Parity impact
+
+- [ ] No frozen R contract is changed.
+- [ ] Frozen parity behavior is intentionally changed/clarified and tests were updated.
+- [ ] `PARITY_EXCEPTIONS.md` was updated if an R → Python translation is involved.
+
+## Validation
+
+- [ ] Ruff lint and format checks pass.
+- [ ] mypy passes.
+- [ ] Full pytest suite passes.
+- [ ] Documentation builds with `mkdocs build --strict` when applicable.
+- [ ] Built-artifact behavior was checked when packaging metadata changed.

gp3sequencespy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Static quality / Python 3.11
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+          enable-cache: true
+      - name: Sync environment
+        run: uv sync --extra dev --extra time
+      - name: Ruff lint
+        run: uv run ruff check src tests parity
+      - name: Ruff format
+        run: uv run ruff format --check src tests parity
+      - name: mypy
+        run: uv run mypy src/gp3sequencespy
+      - name: Frozen API contract
+        run: >-
+          uv run python -c "import json,pathlib,gp3sequencespy as g;
+          names=[x['name'] for x in json.loads(pathlib.Path('reference/api_manifest.json').read_text())];
+          missing=[x for x in names if not hasattr(g,x)];
+          hidden=[x for x in names if x not in g.__all__];
+          print('reference:',len(names),'present:',len(names)-len(missing),'missing:',missing,'not_in___all__:',hidden);
+          assert len(names)==81 and not missing and not hidden"
+      - name: Frozen R block ledger
+        run: >-
+          uv run python -c "import json,pathlib;
+          m=json.loads(pathlib.Path('reference/test_parity_matrix.json').read_text());
+          pairs={(r['r_test_file'],r['r_block_index']) for r in m};
+          py={r['python_test'] for r in m};
+          print('mapped blocks:',len(m),'unique R blocks:',len(pairs),'unique Python translations:',len(py));
+          assert len(m)==130 and len(pairs)==130 and len(py)==130"
+
+      - name: Frozen signature parity
+        run: uv run python parity/signature_audit.py --check reference/signature_parity_matrix.json
+
+  test:
+    name: Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Sync environment
+        run: uv sync --extra dev --extra time
+      - name: Run tests
+        run: uv run pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Build distributions
+        run: uv build
+      - name: Fresh wheel smoke test
+        shell: bash
+        run: |
+          python -m venv /tmp/gp3seq-wheel-test
+          /tmp/gp3seq-wheel-test/bin/pip install dist/*.whl
+          /tmp/gp3seq-wheel-test/bin/python -c "import gp3sequencespy; print(gp3sequencespy.__version__)"

gp3sequencespy-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - name: Sync docs environment
+        run: uv sync --extra docs --extra dev --extra time
+      - name: Validate documentation contracts
+        run: uv run pytest -q tests/test_docs_contract.py
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+      - name: Deploy gh-pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: uv run mkdocs gh-deploy --force

gp3sequencespy-0.1.0/.github/workflows/release-check.yml

@@ -0,0 +1,57 @@
+name: Release checks
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  release-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - name: Sync release environment
+        run: uv sync --extra dev --extra time --extra docs --extra release
+      - name: Validate project metadata
+        run: uv run validate-pyproject pyproject.toml
+      - name: Static quality
+        run: |
+          uv run ruff check src tests parity
+          uv run ruff format --check src tests parity
+          uv run mypy src/gp3sequencespy
+      - name: Tests and frozen contracts
+        run: |
+          uv run pytest -q
+          uv run python -c "import json,pathlib,gp3sequencespy as g; assert g.__version__ == '0.1.0'; n=[x['name'] for x in json.loads(pathlib.Path('reference/api_manifest.json').read_text())]; assert len(n)==81 and all(hasattr(g,x) and x in g.__all__ for x in n)"
+          uv run python -c "import json,pathlib; m=json.loads(pathlib.Path('reference/test_parity_matrix.json').read_text()); assert len(m)==130 and len({(r['r_test_file'],r['r_block_index']) for r in m})==130"
+      - name: Verify frozen signature matrix
+        run: uv run python parity/signature_audit.py --check reference/signature_parity_matrix.json
+      - name: Strict documentation build
+        run: uv run mkdocs build --strict
+      - name: Build distributions
+        run: uv build
+      - name: Validate distributions
+        run: uv run twine check --strict dist/*
+      - name: Verify wheel contents and metadata
+        run: >-
+          uv run python -c "import glob,zipfile; w=glob.glob('dist/*.whl'); assert len(w)==1; z=zipfile.ZipFile(w[0]); n=z.namelist(); assert any(x.endswith('.dist-info/licenses/LICENSE') for x in n); assert any(x=='gp3sequencespy/__init__.py' for x in n); print(w[0]); print('wheel files:',len(n))"
+      - name: Fresh wheel smoke test
+        shell: bash
+        run: |
+          python -m venv /tmp/gp3seq-release-wheel
+          wheel="$(echo dist/*.whl)"
+          /tmp/gp3seq-release-wheel/bin/pip install "${wheel}[time]"
+          /tmp/gp3seq-release-wheel/bin/python -c "import gp3sequencespy as g; assert g.__version__ == '0.1.0'; print(g.__version__); print(len(g.__all__))"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: gp3sequencespy-release-candidate
+          path: dist/*
+          if-no-files-found: error

gp3sequencespy-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python environments and caches
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local secrets
+.env
+.env.*
+
+# Generated parity outputs
+parity/actual/*
+!parity/actual/.gitkeep
+parity/reports/*.txt

gp3sequencespy-0.1.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to `gp3sequencespy` are documented here. The project is
+currently alpha software and follows parity-first development against the frozen
+R package `gp3sequences` 0.3.0.
+
+## [Unreleased]
+
+No changes yet.
+
+## [0.1.0] - 2026-08-30
+
+### Added
+
+- First non-prerelease Python release preserving all **81 / 81** frozen
+  `gp3sequences 0.3.0` public function counterparts.
+- **130 / 130** dedicated translations of the frozen R `test_that()` blocks.
+- Fifteen Python-native article/vignette counterparts, MkDocs documentation,
+  release governance, and multi-platform CI across Python 3.11–3.14.
+- Machine-readable frozen API, test-block, signature, and oracle records.
+
+### Changed
+
+- Replaced the early statsmodels/Patsy time-model approximation with a validated
+  `mssm` binomial GAMM backend using penalized by-group smooths and genuine
+  participant random intercepts.
+- Restored frozen plotting defaults and retained Matplotlib `ax=` only as a
+  keyword-only Python extension.
+- Aligned hierarchical clustering and medoid semantics with R `hclust()`/PAM,
+  including `members=` behavior and tie-sensitive medoid scoring.
+
+### Validation
+
+- **182** Python tests pass locally before the release-candidate artifact freeze.
+- Frozen API: **81 / 81**.
+- Frozen R block ledger: **130 / 130**.
+- Frozen public signatures: **81 / 81**, with **0 unexplained drift**.
+- Deterministic six-contract R↔Python oracle: **PASS**.
+- Extended clustering oracle: **3915 / 3915** partition rows and **108 / 108**
+  medoid rows matched, plus fresh `members=` oracle **PASS**.
+- Time-model calibration: **12 / 12** `k=3/4/5 × state/transition × random-effect`
+  scenarios fit successfully within the validated R-error envelope; frozen-R
+  transition extrapolation matched to an absolute difference of approximately
+  `8.29e-06`.
+- Exact final-version wheel and sdist must pass clean-environment artifact tests
+  before this commit can be pushed by the RC transaction.
+
+### Deliberate parity boundaries
+
+The stable release retains the explicitly reviewed boundaries in
+`PARITY_EXCEPTIONS.md`: ecosystem-specific R object identity, plotting-engine
+identity, cross-language RNG stream identity, and bit-for-bit `mgcv` identity /
+non-default smoothing criteria are not claimed.
+
+## [0.1.0a1] - 2026-08-29
+
+### Added
+
+- 81 / 81 frozen R 0.3.0 public API counterparts.
+- 130 / 130 frozen R `test_that()` block translations.
+- Data validation, preparation, summaries, sequence distances, clustering,
+  consensus, motifs, transition networks, higher-order models, HMM families,
+  panel workflows, subsequence mining, inference, time-varying models, adapters,
+  audits, and visualisations.
+- Cross-language parity harness with deterministic oracle fixtures.
+- Ruff and mypy release-quality gates.
+- Linux, macOS, and Windows CI on Python 3.11–3.14.
+- Fifteen Python-native ports of the frozen R vignette set.
+- MkDocs documentation and GitHub Pages deployment.
+
+### Validation
+
+- 162 tests passing before the release-readiness tranche.
+- 81 / 81 public API contract.
+- 130 / 130 frozen R test-block ledger.
+- Wheel and source distribution build smoke tests.
+
+### Known parity boundaries
+
+See `PARITY_EXCEPTIONS.md`. API and behavioral-contract coverage do not by
+themselves establish exact numerical parity for R RNG streams, cross-language RNG streams, ecosystem-specific adapter objects, or explicitly documented backend boundaries.

gp3sequencespy-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: >-
+  If you use gp3sequencespy in research, please cite the software and record
+  the exact version used.
+title: gp3sequencespy
+type: software
+authors:
+  - family-names: Balaskas
+    given-names: Stefanos
+version: 0.1.0
+date-released: 2026-08-30
+license: MIT
+repository-code: https://github.com/stefanosbalaskas/gp3sequencespy
+url: https://stefanosbalaskas.github.io/gp3sequencespy/
+keywords:
+  - sequence analysis
+  - scanpaths
+  - eye tracking
+  - categorical sequences
+  - reproducible research

gp3sequencespy-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our standard
+
+Participation in the `gp3sequencespy` community should be professional,
+respectful, constructive, and focused on improving scientific software.
+Harassment, discriminatory conduct, personal attacks, intimidation, deliberate
+disruption, and disclosure of private information are not acceptable.
+
+## Scientific disagreement
+
+Technical and methodological disagreement is welcome. Critique ideas, evidence,
+implementations, and assumptions rather than people. When a parity or statistical
+claim is disputed, prefer a reproducible example, test, benchmark, or primary
+source over rhetoric.
+
+## Enforcement
+
+Maintainers may edit, reject, lock, or remove contributions that violate these
+standards and may restrict participation for repeated or severe violations.
+
+## Scope
+
+This policy applies to project repositories, issue trackers, pull requests,
+documentation spaces, and other project-managed communication channels.

gp3sequencespy-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to gp3sequencespy
+
+`gp3sequencespy` is developed parity-first against the frozen R package
+`gp3sequences` 0.3.0. Contributions are welcome when they preserve the frozen
+scientific contracts and make deviations explicit.
+
+## Development setup
+
+```bash
+uv sync --extra dev --extra time --extra docs --extra release
+```
+
+Run the local quality gates before opening a pull request:
+
+```bash
+uv run ruff check src tests parity
+uv run ruff format --check src tests parity
+uv run mypy src/gp3sequencespy
+uv run pytest -q
+uv run mkdocs build --strict
+uv build
+uv run twine check dist/*
+```
+
+## Parity rules
+
+1. Do not change an R-corresponding public contract silently.
+2. Add or update a parity test whenever a frozen behavior changes or is clarified.
+3. Record deliberate R → Python ecosystem translations in `PARITY_EXCEPTIONS.md`.
+4. Keep stochastic behavior reproducible without mutating the caller's global RNG.
+5. Do not infer psychological, medical, biometric, or causal meaning from sequence
+   structure unless the study design and method explicitly support that inference.
+
+## Pull requests
+
+Keep changes focused. Describe the scientific contract affected, tests added,
+backward-compatibility implications, and whether exact R numerical parity is
+expected, translated, or still oracle-pending.

gp3sequencespy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefanos Balaskas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gp3sequencespy-0.1.0/PARITY_EXCEPTIONS.md

@@ -0,0 +1,67 @@
+# Parity exceptions and validation status
+
+The frozen behavioral reference is **gp3sequences 0.3.0**. Python functions retain the frozen R public names, but R-specific runtime objects cannot always be represented identically in Python.
+
+## Validated deterministic cross-language parity
+
+The deterministic oracle was executed on Windows with **R 4.6.1** against a locally rebuilt final `gp3sequences 0.3.0` tarball from release commit `4ebf0bebea2955c5f98f8ddf0fe03e81d0b7ac3a`.
+
+The local final tarball has archive SHA-256:
+
+```text
+4024a6657d4567e44615cdf87419654bd097822016c8b84bd929aa3db4dcd3a8
+```
+
+It was proven source-equivalent to the canonical frozen artifact after normalizing build-only `DESCRIPTION` fields and excluding generated build artifacts. The normalized 199-file source manifest has SHA-256:
+
+```text
+4dd1566e38cb20da1115fc466cc6db3b99f98413aa93876402f59221fc954e56
+```
+
+The core deterministic oracle matched all six canonical CSV contracts: state summaries, transition summaries, formatted paths, motif summaries, consensus sequences, and Levenshtein distances.
+
+The extended clustering oracle also validates R-compatible hierarchical partitions and medoids for `single`, `complete`, `average`, `mcquitty`, `median`, `centroid`, `ward.D`, and `ward.D2` across four tie-resistant fixtures and multiple `k` values, plus deterministic PAM behavior. Regression tests preserve the discovered R `hclust()` semantics.
+
+## Explicit backend-object translations
+
+- `as_traminer_sequences()` returns a structured wide-sequence Python adapter rather than a TraMineR `stslist` S3 object.
+- `as_seqhmm_sequences()` returns the same structured observations tagged for the seqHMM handoff rather than an R `stslist`.
+- `as_arules_sequences()` returns itemsets plus cSPADE-compatible `sequenceID`/`eventID` metadata rather than an R `transactions` S4 object.
+- `as_igraph_transition_network()` returns a NetworkX graph with the corresponding edge attributes rather than an R igraph object.
+
+These are deliberate semantic translations. Their data contracts are tested; object identity with the R backend is not claimed.
+
+## Remaining deliberate/non-exact numerical boundaries
+
+- **Plotting backend:** frozen plotting formals/default labels are preserved, while Python uses Matplotlib rather than base R graphics. Plot functions expose a keyword-only `ax=` target as a Python-native extension. R palette labels are mapped to Matplotlib renderers (`Viridis` → `viridis`, `Dark 3` → `tab10`). Plot-data contracts are tested; pixel-identical R graphics are not claimed.
+- **Randomised algorithms:** NumPy and R use different random-number generators and streams. The parity target is deterministic behavior for a declared Python seed, global-RNG isolation, and equivalent statistical/algorithmic contracts—not bit-for-bit identity of cross-language random draws.
+- **Time-varying sequence models:** the statsmodels/Patsy approximation has been replaced by `mssm` 1.2.5, using a binomial GAMM with a group main effect, separate penalized time smooths by group, and a genuine participant random intercept when requested. The documented `mgcv k -> mssm nk=k-1` mapping is used, with an adaptive spline degree at the frozen public minimum `k=3`. Population prediction excludes the participant random effect, as frozen R `predict.gam(..., exclude='s(.participant)')` does. Cross-language calibration covered state/transition outcomes, random effect on/off, `k=3/4/5`, and out-of-support transition prediction. This is a validated close semantic translation, not a claim of bit-for-bit `mgcv` identity. The Python backend intentionally supports the verified frozen default `method='REML'`; other `mgcv::gam()` smoothing criteria remain an explicit unsupported non-default boundary.
+
+## Stable 0.1.0 exception review — 2026-08-30
+
+Every remaining entry was reviewed before the 0.1.0 release-candidate freeze.
+All are **retained deliberately**; none is an unexplained implementation gap:
+
+1. **R ecosystem objects → Python-native adapters:** TraMineR/seqHMM/arules/igraph
+   object identity is runtime-specific. The Python adapters preserve the tested data
+   contract and expose native Python/NetworkX structures.
+2. **Base-R graphics → Matplotlib:** plot-data contracts, public defaults, and call
+   semantics are tested. Pixel-level identity across rendering engines is neither
+   meaningful nor claimed.
+3. **R RNG streams → NumPy RNG streams:** declared Python seeds are deterministic and
+   global-RNG isolation/algorithmic contracts are tested; cross-language random draws
+   are not expected to be bit-for-bit identical.
+4. **`mgcv::gam()` → `mssm` GAMM:** the frozen default REML contract is calibrated
+   cross-language, including `k=3/4/5`, state/transition outcomes, participant random
+   effects, and extrapolation. Exact penalty/coefficient identity and non-default mgcv
+   smoothing criteria are outside the validated Python contract.
+
+These retained boundaries are compatible with a stable Python API because they are
+explicit, tested, and arise from language/backend differences rather than silent
+behavioral drift.
+
+## Frozen-test translation status
+
+All **130 / 130** frozen R `test_that()` blocks have one dedicated Python translation test. The mapping is machine-readable in `reference/test_parity_matrix.json` and human-readable in `PARITY_TEST_MATRIX.md`.
+
+Behavioral-contract coverage, deterministic oracle coverage, and deliberate backend translations are reported separately so that one does not overstate the other.