Skip to content

eyetrajectoriespy 0.10.0rc1

Release candidate — 28 September 2026

eyetrajectoriespy 0.10.0rc1 is the release candidate for the native sparse/irregular FPCA + PACE tranche. It is based on the protected-main integration of the 0.10 development work and does not add a new estimator beyond that already-qualified tranche.

Main addition

The release candidate introduces a canonical native univariate sparse FPCA workflow:

fit_sparse_fpca(...)

for IrregularTrajectorySet input. The implementation keeps consequential choices explicit:

  • pooled irregular mean smoothing;
  • off-diagonal covariance-pair construction;
  • two-dimensional covariance smoothing;
  • analyst-declared evaluation/analysis support;
  • explicit measurement-error variance handling;
  • analyst-declared noise-estimation support for diagonal-difference estimation;
  • quadrature-weighted positive-semidefinite covariance diagnostics;
  • explicit component count;
  • full-covariance PACE conditional scoring;
  • explicit score ridge and conditioning threshold;
  • per-curve score-system diagnostics and fail-closed status codes.

Raw sparse trajectories are not silently projected to a dense common grid by the native estimator. Fitted population objects are evaluated at native observation times for PACE scoring.

PACE scoring contract

For curve (i),

[ \widehat\Sigma_i = \widehat G(T_i,T_i) + \widehat\sigma_\epsilon^2 I + \gamma I, ]

and

[ \widehat\xi_{ik} = \widehat\lambda_k \widehat\phi_k(T_i)^\top \widehat\Sigma_i^{-1} {Y_i-\widehat\mu(T_i)}. ]

The conditional covariance uses the full fitted covariance surface. n_components controls which eigenfunctions/scores are returned; it does not truncate the covariance used inside the conditional score system.

Validation

Release-candidate qualification retains multiple evidence classes rather than collapsing them into a generic “validated” label:

  • analytical weighted-operator truth;
  • known-truth sparse simulation recovery;
  • evaluation-grid refinement at 21/41/81 points;
  • difficult sparse/noisy/near-tied sampling regimes;
  • fail-closed support/bandwidth probes;
  • FDApy local-linear primitive equivalence;
  • whole-estimator FDApy cross-implementation sensitivity;
  • sparse-specific runtime and peak-memory characterization.

The current validation does not claim exact full-estimator equivalence with FDApy or an R package where smoothing/discretization/PACE contracts differ.

Important interpretation boundary

Extreme sparsity can preserve a useful population functional subspace while still yielding weak individual PACE scores. The documented stress matrix therefore reports score recovery and score-system failure separately from population-subspace recovery.

FDApy compatibility

fit_sparse_fpca_fdapy() remains available as an optional compatibility and reference backend. FDApy is not a core runtime dependency and is not called by the native estimator.

The optional FDApy path is qualified on Python 3.11–3.12. The native core remains qualified on Python 3.11–3.13.

Diagnostics and documentation

The release candidate includes:

  • plot_sparse_fpca_component();
  • plot_sparse_fpca_covariance();
  • plot_sparse_fpca_score_diagnostics();
  • backend-aware manuscript reporting;
  • native worked examples;
  • mathematical contracts and function-equation indexes;
  • a sparse validation guide and deterministic documentation gallery.

Explicit exclusions

0.10 does not add:

  • sparse multivariate PACE/MFPCA;
  • automatic CV/GCV bandwidth selection;
  • sparse functional mixed effects;
  • hidden covariance-pair thinning;
  • automatic analysis-support trimming;
  • automatic component-count selection.

Separate sparse fits for (x(t)) and (y(t)) remain separate univariate decompositions and do not model cross-channel covariance.

Installation

After publication, install the release candidate explicitly with:

pip install --pre eyetrajectoriespy==0.10.0rc1

Until publication is deliberately dispatched, 0.9.0 remains the current stable PyPI release.

Release-candidate purpose

The RC phase is for packaging, installation, documentation, compatibility, and scientific-contract feedback. It is not a signal to expand the 0.10 estimator surface. The full release should promote the same qualified API unless a release-candidate defect requires correction.