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.

Status: stable pre-1.0 release (0.9.0). The scientific platform, reference-validation layer, reproducibility contracts, packaging checks, and five canonical workflows are qualified.

Release-candidate line: 0.10.0rc1 has completed protected-main qualification. It contains the native univariate sparse/irregular FPCA + PACE estimator, with explicit smoothing/support/noise/PSD/score contracts and FDApy retained only as an optional compatibility/reference backend. Release readiness is armed through a reviewed change; publication still requires a deliberate manual production dispatch.

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

Stable release:

pip install eyetrajectoriespy==0.9.0

Or install the current stable release:

pip install eyetrajectoriespy

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 after the qualified 0.9.0rc1 publication. Scientific product qualification remains more important than estimator count. See the release-readiness checklist.

• Portable scientific results
• Reproducibility bundle checklist
• Release process

Validation

Current local/CI qualification status and the exact pending re-check list 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.