Skip to content

Bayesian sparse FPCA/MFPCA comparator

This validation programme is the first scientific tranche after the stable 1.1.0 release. It asks whether an independent Bayesian latent-basis approach adds useful recovery or uncertainty evidence for sparse and irregular eye tracking.

It does not add a Bayesian estimator to the package.

External reference

The comparator is hruffieux/bayesFPCA, pinned in CI to commit:

f05b0615632cffe5c63838858d9a956af6588a73

The comparator reports package version 0.1.0 and is licensed GPL >= 3. It is therefore treated only as an external development/validation reference.

The package is not:

  • copied or translated into eyetrajectoriespy;
  • vendored;
  • imported by the Python package;
  • added to the Python dependency graph; or
  • exposed as a runtime backend.

The CI job installs the exact upstream commit in an isolated R environment and passes it neutral CSV fixtures generated independently by eyetrajectoriespy.

Scientific contrast

The native sparse route estimates population mean/covariance objects and then recovers subject scores using PACE or joint PACE. The comparator estimates a latent Karhunen--Loève representation through variational Bayesian inference.

Those architectures are scientifically related but not numerically identical. Accordingly, B1 evaluates invariant targets rather than requiring matching component signs, labels, spline coefficients, or fitted covariance parameterizations.

Frozen B1 scenario matrix

Five deterministic known-truth scenarios are generated by scripts/run_bayesian_fpca_comparator.py.

Scenario Design Purpose
univariate_moderate sparse irregular univariate ordinary sparse recovery
univariate_extreme_sparse sparse irregular univariate low within-curve observation count
univariate_low_n_near_tied sparse irregular univariate low participant count plus near-tied spectrum
planar_paired sparse paired planar joint x/y recovery with common native timestamps
planar_async sparse asynchronous planar coordinate-specific x/y timestamps without synchronization or interpolation

Every fixture retains exact native observations, known mean/eigenvalues/ eigenfunctions/scores/latent trajectories, declared native bandwidths, the measurement-noise scale, and a fail-closed contract forbidding equivalence, automatic winner selection, runtime-backend interpretation, or automatic API promotion.

The asynchronous case exports x and y observations on their own native time grids. The R comparator consumes those coordinate-specific grids directly. No raw trajectory is interpolated, nearest-neighbour synchronized, or binned.

Primary evidence

For each scenario, scripts/evaluate_bayesian_fpca_comparator.py reports:

  • integrated mean error;
  • invariant functional-subspace principal cosines against truth;
  • invariant score-subspace principal cosines against truth;
  • latent-trajectory reconstruction error;
  • normalized retained-spectrum/PVE error;
  • score failure rate; and
  • native-versus-comparator functional and score subspace agreement.

Runtime, iteration count, final ELBO and exported score-covariance diagnostics are retained descriptively for the external comparator.

No architecture winner is selected automatically and no qualification threshold is introduced after seeing the comparison.

Uncertainty boundary

bayesFPCA exports subject-specific variational score covariance. That output is retained because uncertainty is one of the principal reasons for studying a Bayesian reference implementation.

It is not treated as interchangeable with native conditional PACE or joint-PACE score uncertainty. The native functions currently quantify conditional score uncertainty while treating the fitted population objects as fixed. The Bayesian covariance arises from a different fitted hierarchical model and variational approximation.

B1 therefore records:

bayesFPCA score covariance available
        !=
full population-level Bayesian uncertainty validated
        !=
native conditional PACE covariance

Population-level posterior uncertainty for means, eigenfunctions and eigenvalues remains a later feasibility question.

Evidence artifact

The dedicated bayesian-fpca-comparator workflow retains the full evidence directory for 90 days, including neutral source fixtures, native fitted outputs, external Bayesian fitted outputs, comparator provenance, score covariance, the invariant sensitivity summary, and SHA256 checksums.

The workflow verifies the exact upstream commit before running the comparator.

Decision gate

B1 is evidence collection, not feature approval. After the retained results are inspected, issue #205 should record exactly one conclusion:

  • external_comparator_only;
  • native_feasibility_warranted; or
  • not_actionable.

Only native_feasibility_warranted would justify a new, separate native Bayesian design tranche. Such a tranche would require an independent mathematical specification, known-truth validation, performance evidence and public-surface review. It would not port GPL source code.