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: 0.12.0 · 1.0 release candidate under qualification: 1.0.0rc1 · Python: 3.11–3.13

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

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

Current stable release: 0.12.0
0.12.0 adds the qualified native sparse multivariate FPCA / joint-PACE workflow for jointly observed planar gaze. Release qualification, immutable hashes, OIDC/attestation evidence, and publication chronology are retained in the 0.12.0 release notes and validation records rather than repeated on this landing page.

1.0 release candidate under qualification: 1.0.0rc1
The candidate freezes the evidence-backed 1.0 API boundary without adding a new estimator or changing scientific behavior. Publication readiness remains disarmed until fresh exact-RC performance and the complete PR plus protected-main qualification matrices pass.

What can it model?

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
• 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. Published tags and distributions remain immutable historical records.

• 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
• Validation ledger
• 0.12.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.