eyetrajectoriespy

Functional analysis of continuous and sparse eye-tracking trajectories in Python.

Instead of immediately reducing gaze to fixation counts, dwell summaries, or symbolic scanpaths, eyetrajectoriespy treats gaze as a time-indexed functional process

$$ \mathbf G_i(t)= \begin{bmatrix} x_i(t)\ y_i(t) \end{bmatrix}. $$

Stable: 1.0.0 · 1.1 release candidate under qualification: 1.1.0rc1 · Python: 3.11–3.13

pip install eyetrajectoriespy
# exact reproducible stable release
pip install eyetrajectoriespy==1.0.0

Documentation · Quick start · Choose a workflow · Mathematics · Visual gallery · Validation

Current stable release: 1.0.0
1.0.0 freezes the evidence-backed 1.0 compatibility boundary over the production-observed 1.0.0rc1 scientific/API surface without adding a new estimator or changing scientific behavior. Release qualification, immutable hashes, OIDC/attestation evidence, and publication chronology are retained in the 1.0.0 release notes and validation records rather than repeated on this landing page.

1.1 release candidate under qualification: 1.1.0rc1
The post-1.0 sparse/irregular scientific programme (#158) and integration/readiness tranches R1–R4 (#183) are complete. R4 recorded eligible_for_rc_decision=true, so R5 is qualifying the same supported module-scoped 1.1 APIs under the literal 1.1.0rc1 identity. The frozen 1.0.0 root compatibility boundary is unchanged, fresh RC evidence is kept separate from historical 1.0/R4 records, and publication readiness remains jointly disarmed.

What can it model?

The post-1.0 module-scoped APIs are documented in the 1.1 module API and integration audit. They are intentionally not root re-exports and should not be interpreted as already-published 1.1.0 functionality.

Which workflow do I need?

Minimal dense/common-grid example

from eyetrajectoriespy import fit_mfpca, simulate_planar_trajectories

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(fit.explained_variance_ratio)

Minimal sparse paired-planar example

import numpy as np
from eyetrajectoriespy import fit_sparse_mfpca

fit = fit_sparse_mfpca(
    irregular,
    dimensions=("x", "y"),
    n_components=2,
    evaluation_grid=np.linspace(0.0, 1.0, 41),
    mean_bandwidth=0.20,
    covariance_bandwidth=0.30,
    measurement_error="diagonal",
    measurement_error_variance=(0.0025, 0.0025),
    psd_action="project",
    score_failure_action="retain_nan",
)

The sparse estimator uses native paired observations to estimate a joint population mean/covariance model. Evaluating fitted population functions at native times for PACE is not raw-trajectory interpolation.

What eyetrajectoriespy refuses to hide

Consequential choices stay explicit: missingness, interpolation, smoothing, registration, time/coordinate normalization, analysis support, measurement-error assumptions, PSD policy, family/model selection, resampling unit, denominator/exposure semantics, and failure/status codes.

Scope

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 package deliberately separates stable public methods, advanced diagnostics, external-backend interoperability, and experimental methods. Scientific product qualification matters more than estimator count.

Where is the full advanced API?

The README is intentionally a compact entry point rather than the exhaustive function catalogue.

• Capability inventory
• Public API
• 1.1 module-scoped API
• 1.1 integration audit
• API stability and hierarchy
• Mathematical reference
• Capability status and roadmap
• Reference validation & performance envelope

Release lineage and reproducibility

The stable pre-1.0 sequence remains explicit: 0.10.0 introduced the native sparse univariate FPCA/PACE line, the immutable 0.11.0rc1 prerelease preceded final 0.11 known-truth recovery infrastructure, and 0.12.0 added the native sparse planar MFPCA/joint-PACE line. 1.0.0 closes that stabilization programme as the frozen stable compatibility baseline. Published tags and distributions remain immutable historical records. The completed A1–C1 and R1–R4 work is now being qualified under the non-published 1.1.0rc1 identity; a green RC still does not authorize publication.

• Portable scientific results
• Reproducibility bundle checklist
• Release process

Documentation and reproducibility

• Sparse planar MFPCA / joint PACE guide
• Implementation-matched mathematical reference
• Function → equation index
• Mathematical contracts
• Workflow atlas
• Current validation ledger
• 1.0.0 release notes

Development checks:

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/generate_sparse_mfpca_docs_figure.py
python scripts/validate_docs_contracts.py
mkdocs build --strict

Citation and license

See CITATION.cff for citation metadata. MIT © 2026 Stefanos Balaskas.