Skip to content

Capability status and roadmap

Current stable scientific surface — 1.2.0

The current stable production release is 1.2.0. It was published on GitHub and PyPI on 24 October 2026 by successful production run #40128358042 from protected main. It preserves the frozen 1.0 root compatibility boundary, includes the stable 1.1 sparse/irregular module additions, and delivers ten supported module-scoped W1–W4 orchestration routes.

Stable 1.1.0 and published prerelease 1.2.0rc2 remain available as historical distributions. E1–E4 helpers remain experimental; issues #289 and #296 remain open and outside release guarantees. The subsequent detailed qualification chronology is historical, not a current publication status.

The protected main source at the start of literal-RC qualification is 1.2.0.dev0, with W1–W4 completed. PR #220 has merged the exact candidate identity 1.2.0rc1 onto protected main at 67c5947; it is not yet a published production version, and release readiness remains disarmed. Immutable 1.1.0 qualification evidence stays attributed to 1.1.0.

The frozen 1.0 public boundary contains 455 stable public exports and three explicitly experimental APIs. No deprecations or removals were authorized by the 1.0 stabilization programme, and 1.1 did not mechanically expand that package-root namespace.

The post-1.0 sparse/irregular scientific programme (#158), integration/readiness programme (#183), 1.1.0rc1 qualification/publication/installed observation, literal final 1.1.0 qualification, governance-only arming, production publication, and post-publication closeout are all complete.

The completed release sequence was:

  1. R1 — integrated API/public-surface audit: complete; module-scoped 1.1 surface documented and machine-checked.
  2. R2 — documentation/release narrative: complete.
  3. R3 — end-to-end product analyses: complete with zero release-blocking friction.
  4. R4 — consolidated evidence/performance audit: complete; eligible_for_rc_decision=true.
  5. R5 — RC/final decision and literal-version qualification: complete through RC publication/observation and fresh final-version qualification.
  6. Final publication governance: complete; 1.1.0 was armed separately, published from exact protected main, promoted to stable/default, and publication readiness was disarmed again after closeout.

The post-1.1 Bayesian comparator programme (issue #205, B1–B4) and the transparent workflow programme (issue #209, W1–W4) have both completed their evidence/development gates. B4 warrants only a separate native Bayesian feasibility/design programme: native_bayesian_feasibility_warranted=true, architecture_winner_selected=false, automatic_promotion_decision=false. W1–W4 qualified ten module-scoped orchestration workflows; the current work is literal 1.2.0rc1 release engineering, not a new scientific-estimator tranche.

Future methodology remains evidence-driven rather than version-number-driven. eyetrajectoriespy is intentionally an eye-tracking functional-analysis layer, not a reimplementation of every general FDA estimator.

Stable core scientific routes

Scientific object Status Primary API
Common-grid functional gaze stable 1.0 TrajectorySet, fit_fpca(), fit_mfpca()
Native curve-specific time grids stable 1.0 IrregularTrajectorySet
Sparse univariate covariance FPCA + PACE stable 1.0; natively qualified since 0.10 fit_sparse_fpca()
Sparse paired planar MFPCA + joint PACE stable 1.0; qualified in 0.12 fit_sparse_mfpca()
Functional simulation / known-truth recovery stable validation infrastructure simulation and recovery APIs
Function-on-scalar regression stable 1.0 fit_function_on_scalar_regression()
Generalized Bernoulli / grouped-binomial / Poisson functional responses stable guarded marginal GEE line fit_generalized_function_on_scalar_regression()
Repeated-trial Gaussian functional mixed effects stable 1.0 fit_functional_mixed_effects_regression()
Multilevel participant/trial FPCA stable 1.0 fit_multilevel_fpca()
Registration / phase decomposition stable 1.0 register_to_landmarks(), fit_phase_fpca()
Continuous trajectory geometry and distance stable 1.0 geometry, L2, Fréchet, DTW APIs
Recurrence / nonlinear diagnostics implemented; experimental status remains explicit where applicable RQA, LLE, surrogate, TE APIs

Completed 1.1 scientific surface — A1–C1

The completed post-1.0 programme is additive and module-scoped. These APIs were developed on 1.1.0.dev0, qualified through immutable 1.1.0rc1, observed from production artifacts, requalified under literal final 1.1.0, and are now stable functionality in the published 1.1.0 release.

Tranche Scientific capability Supported module/API Qualified boundary
A1 conditional sparse-PACE score uncertainty sparse_score_uncertainty conditional on fitted population objects; not full estimation uncertainty
A2 audited sparse-FPCA bandwidth selection sparse_bandwidth_selection opt-in curve/group CV; no hidden fitter selection
A3 candidate-sample observation-process diagnostics observation_process descriptive diagnostics only; no MAR/MNAR identification or inverse-intensity correction
A4 conditional joint-PACE score uncertainty sparse_multivariate_score_uncertainty full fitted joint score system; not full population-estimation uncertainty
A5 audited sparse-MFPCA bandwidth selection sparse_multivariate_bandwidth_selection mean/covariance bandwidths only; measurement-error specification remains fixed
B1 native sparse participant/trial multilevel FPCA sparse_multilevel univariate two-level hierarchy with explicit identifiability/PSD/BLUP diagnostics
B2 asynchronous coordinate-specific sparse planar MFPCA sparse_multivariate_async exact native x/y grids; no hidden synchronization/interpolation
C1 future/partially observed sparse trajectory prediction sparse_partial_prediction Gaussian conditional moments using the full fitted covariance
C1 participant-aware split-conformal future bands sparse_partial_conformal finite-grid future-observation coverage under the declared grouping/exchangeability contract

See the 1.1 module API and 1.1 integration audit. The frozen 1.0 package-root API remains separately documented and machine-checked as the 1.x compatibility boundary.

What 0.12 added

The defining 0.12 addition was native sparse multivariate FPCA / joint PACE for jointly observed planar gaze. Its scientific object is

\[ \mathbf X_i(t)= \begin{bmatrix}X_i(t)\\Y_i(t)\end{bmatrix}, \]

with full block covariance

\[ \mathbf C(s,t)= \begin{bmatrix} C_{xx}(s,t) & C_{xy}(s,t)\\ C_{yx}(s,t) & C_{yy}(s,t) \end{bmatrix}. \]

The canonical estimator directly estimates the directional cross-channel covariance, performs PSD handling on the joint weighted operator, retains the declared measurement-error covariance, and uses the full fitted joint covariance in the joint PACE conditional system. n_components controls the returned eigensystem/scores rather than reconstructing the conditional covariance at rank K.

See the stable sparse planar guide, mathematical reference, recovery evidence, comparator sensitivity, and 0.12.0 release notes.

Optional specialist interoperability

Capability Backend Package role
B-spline/Fourier basis representation scikit-fda preserve provenance while delegating basis mathematics
Functional boxplot / magnitude-shape review scikit-fda optional sensitivity/review diagnostics
Sparse covariance UFPCA + PACE FDApy optional compatibility/reference backend for the univariate route
Elastic SRVF trajectory alignment fdasrsf specialist phase/amplitude backend
Sparse multivariate external comparison mGSFPCA qualification/sensitivity comparator, not the canonical estimator

Optional backends are never imported until the corresponding feature is requested.

Not silently approximated

The package does not replace scientifically distinct targets with convenient substitutes. Examples include:

  • separate univariate sparse x/y fits are not labelled joint sparse MFPCA;
  • review flags are not automatic inferential exclusions;
  • covariance-sensitivity outputs do not rank or select a preferred model automatically;
  • generalized marginal GEE coefficients are not labelled conditional generalized functional random effects;
  • recurrence or transfer-entropy sensitivity grids are not automatic parameter selectors;
  • raw sparse samples are not silently interpolated to make them compatible with dense-grid estimators;
  • asynchronous x/y observations are not synchronized by interpolation before B2 fitting;
  • conditional PACE or prediction covariance is not labelled full population-estimation uncertainty;
  • conformal finite-grid future-observation coverage is not labelled continuous latent-function coverage.

Validation and qualification model

Scientific qualification remains separated into:

  1. exact or analytical truth where available;
  2. independent implementation/reference comparisons where scientifically appropriate;
  3. known-truth finite-sample recovery;
  4. descriptive stress evidence for difficult observation regimes; and
  5. runtime / peak-memory evidence that does not weaken scientific gates.

The 0.11 recovery laboratory remains the standing infrastructure for later methodology. The 0.12 sparse-MFPCA line was promoted only after native recovery, observation-process stress, direct/two-stage sensitivity, external mGSFPCA comparison, performance qualification, exact-version package qualification, production-installed observation, and the complete release matrix were closed.

Final 1.0.0 preserves that frozen scientific/API surface. The RC was observed outside the checkout on Python 3.11–3.13, final 1.0.0 received fresh exact-version performance and complete PR/exact-main qualification, and production workflow #18 published the final version from exact arming commit d90fbbeea390054019e7689badedf5011ee09c22. Post-publication readiness is disarmed again.

The R4 1.1.0.dev0 development-readiness ledger, published 1.1.0rc1 qualification/observation evidence, fresh literal-final 1.1.0 qualification, arming, publication, and post-publication closeout remain immutable historical records. Later evidence is additive and does not relabel frozen 1.0, R4, RC, or final-release records.

Published release sequence

0.10.0 — native sparse univariate FPCA / PACE

Introduced the backend-independent native sparse univariate estimator operating directly on IrregularTrajectorySet, with explicit pooled mean/covariance smoothing, measurement-error handling, weighted covariance eigendecomposition, PSD policy, and conditional PACE scoring.

0.11.0 — known-truth recovery laboratory

Added explicit latent truth, declared finite-sample scenarios, recovery metrics, deterministic qualification scenarios, descriptive stress regimes, failure retention, Monte Carlo aggregation, portable evidence, and reporting helpers. This was a validation-infrastructure tranche rather than another estimator catalogue.

0.12.0 — native sparse planar MFPCA / joint PACE

Added the direct joint sparse planar estimator, block-aware recovery, tied-eigenspace/Procrustes-aware score recovery, two-stage sensitivity comparison, external mGSFPCA sensitivity, observation-process stress, and dedicated runtime/RSS qualification.

1.0.0rc1 — frozen 1.0 API release candidate

Published 4 October 2026 as the evidence-backed 1.0 API candidate after exact-version qualification. Post-publication installed-artifact observation closed without identifying a result-changing or frozen-public-API defect.

1.0.0 — stable compatibility baseline

Published 4 October 2026 after literal final-version qualification and a separate governance-only arming step. The release changed package identity and compatibility status rather than adding scientific functionality. The stable 1.0 boundary is the compatibility contract for the 1.x line.

1.1.0rc1 — sparse/irregular 1.1 release candidate

Published 6 October 2026 after exact-version qualification. It retained the frozen 1.0 root compatibility boundary while exposing the completed A1–C1 additions as supported module-scoped APIs. Production-installed observation on Python 3.11–3.13 completed before final promotion.

1.1.0 — previous stable/default release

Published 7 October 2026 after fresh literal-final qualification, a separate governance-only publication-arming step, exact protected-main verification, production GitHub/PyPI publication with attestations, fresh exact-version installation smoke, and a post-publication disarming/closeout cycle. The scientific/API surface is the frozen, production-observed RC surface rather than a feature expansion during promotion.

1.2.0 — current stable/default release

Published 24 October 2026 after exact final-version evidence, 33/33 source PR workflows, owner-authorized production workflow, protected-main governance and fresh PyPI-installed smoke. The ten typed W1–W4 routes are stable module APIs; E1–E4 helpers remain experimental. No new simultaneous-band or MNAR identification guarantee was promoted.

Published tags and release artifacts remain immutable historical records. New documentation or later APIs do not retroactively alter the scientific identity of earlier releases.

Completed post-1.0 sparse/irregular inference programme

Issue #158 closed after the following evidence-driven sequence completed:

  1. conditional PACE and joint-PACE score uncertainty with full-refit uncertainty kept distinct;
  2. audited opt-in univariate and planar bandwidth selection with declared resampling units and retained failures;
  3. candidate-sample observation-process diagnostics before any correction estimator;
  4. sparse participant/trial multilevel FPCA;
  5. asynchronous/coordinate-specific sparse planar MFPCA without hidden interpolation; and
  6. future/partially observed trajectory prediction with participant-aware conformal calibration.

R1–R5 under issue #183 subsequently qualified the integrated product surface through RC and final publication. The 1.1 scientific/release programme is therefore closed and is no longer the active roadmap.

Completed post-1.1 programmes and active release gate

Bayesian external comparator — B1–B4 completed

Issue #205 records the completed feasibility decision; PR #215 retains definitive B2/B3 evidence. In the primary K=7 comparison, the external Bayesian comparator completed 128/128 fits and achieved lower mean reconstruction error in all eight frozen scenarios. Its repeated-dataset conditional fitted-score covariance nevertheless did not provide generally nominal 95% uncertainty coverage. No native implementation, new dependency or product API was promoted.

Transparent 1.2 orchestration — W1–W4 completed

Issue #209 is closed. W1 infrastructure, W2 sparse, W3 dense/regression and W4 recurrence, plotting and installed-wheel product qualification are complete on exact protected main. The surface has ten entry points and retained versioned contracts, with 49 module-scoped exports under the frozen 1.2 candidate workflow API audit. Root promotion remains disabled.

Next gate — literal 1.2.0rc1

PR #220 merged after a 29/29 PR-head matrix. Exact protected-main qualification is mandatory before any separate publication-arming decision. Documentation updates do not constitute a release or change the scientific qualification record.

Later or conditional methodology

Irregular functional mixed effects, shape/manifold analysis, genuinely functional clustering/classification, and additional nonlinear/state-space methods remain later or conditional work. Bayesian sparse modelling remains a feasibility/design research direction under the completed issue #205, not an approved native estimator/API. Device/clock synchronization remains outside the package except for narrow audit interfaces.

For versioning, the intended posture is:

  • 1.0.x — compatible bug fixes, documentation, portability, validation and performance improvements;
  • 1.x — additive capabilities or deliberately governed compatible extensions;
  • 2.0 — breaking stable API/scientific-contract changes after explicit deprecation, except when an exceptional correction is necessary to prevent demonstrably wrong scientific results.

No version number by itself commits the project to a scientific capability or release. Promotion remains contingent on product evidence, method-specific validation, integrated qualification and the package's release-governance gates.