eyetrajectoriespy

Functional and continuous trajectory analysis for eye-tracking data in Python.

eyetrajectoriespy treats gaze as a function of trial time rather than immediately reducing it to fixation counts, dwell summaries, or symbolic scanpaths. It supports continuous planar paths

G_i(t) = [x_i(t), y_i(t)]^T

derived univariate functions, compositional AOI-probability trajectories, repeated-trial multilevel decompositions, explicit registration, and optional elastic phase–amplitude analysis.

Final 0.11.0 qualification: 0.11.0 promotes the publicly qualified 0.11.0rc1 scientific surface without adding an estimator, numerical method, generalized family, API expansion, or hidden analytical default. The exact final version is being requalified before publication; release readiness is deliberately disarmed until the final pull-request and protected-main matrices pass.

Current stable release: 0.10.0 remains the public stable pre-1.0 release during final 0.11 qualification. Published 0.11.0rc1 remains an immutable prerelease record.

RC observation evidence: the exact production-PyPI 0.11.0rc1 artifact was independently exercised outside the source checkout on Python 3.11–3.13. Exact protected-main observation commit a37214653c2f72839e356d603c4f87a514f01056 passed deterministic simulation replay, recovery qualification, threshold-free stress retention, mixed-effects and registration recovery, portable export/load, reporting, and plotting.

What scientific problem does this solve?

eyetrajectoriespy is for analyses where the trajectory itself is a scientific object. It keeps temporal structure visible instead of immediately collapsing gaze into scalar summaries, while making repeated-measures hierarchy, uncertainty and analytical provenance explicit.

The central design rule is that consequential choices stay visible: no silent interpolation, missing-to-zero conversion, smoothing, registration, time or coordinate normalization, family/model selection, denominator inference or exposure inference.

Which workflow do I need?

The canonical workflow index is the recommended entry point for new analyses. It separates default routes from advanced, diagnostic and experimental branches.

What assumptions does the workflow make?

Every canonical route documents its observation unit, hierarchy, estimand, uncertainty/resampling unit and major failure conditions. Before interpreting a result, use the package's assumptions and diagnostics and limitations alongside the workflow-specific page.

The package prefers explicit failure or review over silently manufacturing a convenient answer.

Where is the full advanced API?

The README is intentionally no longer the exhaustive function catalogue.

• Capability inventory
• Public API
• API stability and hierarchy
• Mathematical reference
• Capability status and roadmap
• Reference validation & performance envelope

Install

Current stable release while final 0.11.0 qualification is in progress:

pip install eyetrajectoriespy==0.10.0

Published qualified release candidate:

pip install --pre eyetrajectoriespy==0.11.0rc1

After final 0.11.0 publication, the normal stable install becomes:

pip install eyetrajectoriespy==0.11.0
# or: pip install eyetrajectoriespy

The final 0.11.0 package identity is qualified independently before publication; the published rc1 artifacts are not relabeled.

Development checkout:

pip install -e .

Development and documentation:

pip install -e ".[dev,docs]"

Optional interoperability:

pip install -e ".[fda]"       # scikit-fda
pip install -e ".[sparse]"    # transitional FDApy sparse/PACE compatibility backend
pip install -e ".[elastic]"   # fdasrsf

The core package remains Python 3.11–3.13. The native fit_sparse_fpca() path is backend-independent. The optional FDApy 1.0.3 compatibility/reference backend is qualified separately on Python 3.11–3.12 because FDApy pins NumPy <2.0, while NumPy 1.26.x does not support Python 3.13.

Quick start

from eyetrajectoriespy import fit_mfpca, simulate_planar_trajectories, summarise_fpca

gaze = simulate_planar_trajectories(
    n_participants=20,
    trials_per_participant=6,
    random_state=7,
)

fit = fit_mfpca(
    gaze,
    n_components=0.95,
    scaling="dimension_sd",
)

print(summarise_fpca(fit))

Documentation

The repository-level mathematical contracts, generated function → equation index, and workflow atlas render directly on GitHub. The site expands them with assumptions, API mappings, worked examples, and a Visual gallery.

The methods site is configured for GitHub Pages:

https://stefanosbalaskas.github.io/eyetrajectoriespy/

Use the site for the five canonical workflows, advanced method guides, worked examples, assumptions/limitations, validation ledger, implementation-matched mathematical reference, API documentation and reproducible SVG plot gallery.

Scope boundary

eyetrajectoriespy starts once gaze has a scientifically interpretable time and coordinate representation. Event detection, general gaze QC, survival analysis, AOI perturbation robustness and symbolic sequence models belong upstream or in specialist packages.

The generalized observation-family line is intentionally closed at Bernoulli / grouped-binomial logit and Poisson expected-count/rate GEE. Negative binomial, zero-inflated, hurdle and Tweedie families are not automatic next features. Classical Floquet/monodromy and bifurcation analysis remain outside the raw-gaze API without an explicitly identified dynamical model.

Version 0.55 began the stabilization line; version 0.56 added evidence-typed independent/reference validation, an explicit numerical-tolerance policy, and a repeated runtime/peak-memory reference envelope. Version 0.57 adds portable scientific-result snapshots, explicit environment capture, five qualified canonical end-to-end examples, and coordinated GitHub/PyPI release machinery. Version 0.9.0 is the first stable pre-1.0 release. The 0.10 line adds the native sparse/irregular FPCA + PACE tranche; rc2 corrects the diagonal-difference measurement-noise estimator, and final 0.10.0 promotes that corrected candidate after exact-version requalification. The 0.11 line adds the known-truth simulation/recovery laboratory. Published 0.11.0rc1 completed production-installed observation, and final 0.11.0 is being requalified under its own exact version without scientific/API expansion. Scientific product qualification remains more important than estimator count. See the release-readiness checklist.

• Portable scientific results
• Reproducibility bundle checklist
• Release process

Validation

Current qualification, release, and public-artifact evidence are maintained in VALIDATION.md.

python -m pytest --cov=eyetrajectoriespy
python -m compileall -q src
python scripts/generate_function_equation_index.py --check
python scripts/generate_docs_gallery.py
python scripts/validate_docs_contracts.py
mkdocs build --strict

License

MIT © 2026 Stefanos Balaskas.