Bayesian functional analysis — B5–B10 experimental programme¶

The historical B4 feasibility decision justified further native Bayesian investigation, but did not select a Bayesian architecture as replacement for native covariance/PACE. The GPL bayesFPCA code remains an external benchmark, not a dependency or a source-code port.

Scientific definitions and limitations¶

B6. A future sparse Bayesian model must learn population mean, a joint eigenfunction basis, score and observation covariance, along with their uncertainty. The currently implemented B6 baseline instead conditions on known fixed population functions and calculates a Gaussian score posterior per subject. It explicitly evaluates those supplied basis functions at actual irregular observation times; it does not resample the observed data or estimate eigenfunctions. Sign/rotation ambiguity, near-tied eigenspaces and full population uncertainty remain open.

B8. The provisional function-on-scalar model expands each time-varying coefficient in a cubic B-spline basis and applies a declared zero-mean Gaussian coefficient prior. With analyst-fixed independent Gaussian observation-noise SD, the coefficient posterior is conjugate. It cannot silently treat repeated observations from the same participant as independent; those are rejected. The independent-curve model can provide draw-based coefficient credible intervals but not scientifically calibrated coverage under misspecified noise or unmodelled autocorrelation. A second, opt-in fit_bayesian_functional_mixed_effects() fits participant functional random intercepts with conjugate partial pooling and explicitly fixed hyperparameters; it does not learn participant variance, fit random functional slopes, accommodate nested trial random effects or model serially correlated residuals.

Pointwise versus joint posterior bands. bayesian_credible_band() produces equal-tailed pointwise intervals or posterior content for a finite sampled grid using a maximum standardized-deviation reference across all times and dimensions. Neither construction implies repeated-sampling 95% confidence coverage or simultaneous validity between observed grid points.

Posterior probability versus hypothesis testing. bayesian_functional_probability() computes probabilities for predeclared posterior events such as an entire channel exceeding a meaningful threshold; it is not a frequentist p-value or Bayes factor.

Algorithm diagnostics. Optional ArviZ summarizes R-hat, bulk/tail ESS, Monte Carlo error and divergences when available. Convergence diagnostics are computational evidence, not evidence of valid likelihoods or priors.

Calibration and predictive evidence. Rank-based SBC requires actual prior-generated truth, likelihood simulation, and posterior refits across replicates. The B5 helper records ranks and uncertainties but cannot independently verify that the supplied draws satisfy these assumptions. Its held-out Gaussian pointwise log scores require participant/unit disjointness; they are not full joint longitudinal density without modelling the residual covariance.

Portable evidence. Posterior values export to a non-executable NumPy NPZ file plus a JSON manifest with explicit priors, diagnostics, provenance, SHA256 and unqualified-status marker.

Dependencies and research phases¶

The package root and native FPCA estimators are unchanged. The bayesian extra installs ArviZ diagnostics; bayesian-pymc additionally installs optional PyMC for future sampler-based models. None is required for standard users, and the current B8 conjugate fitter does not claim to have run MCMC.

B6 learned-eigensystem modelling, B7 learned-population paired/asynchronous planar inference, B8 full participant/trial hierarchical variance inference, B9 learned-population calibrated partial prediction and B10 AOI/change-point/registration/observation models need independent scientific and engineering gates.

Bayesian synthetic figures · Historical B4 evidence · Research evidence matrix

Exact-model B5 simulation-based calibration pilot¶

The research CI executes scripts/run_bayesian_conjugate_sbc_pilot.py, drawing score truth or spline coefficients from each implemented conjugate model prior, constructing observations from its known Gaussian likelihood, then independently refitting each posterior. This creates rank histograms, observed 90% interval inclusion and exact binomial uncertainty for two restricted baselines (B6 fixed population and B8 known noise). The default small pilot of 30 replicates per baseline is a pipeline check, not an adequate SBC study; it does not validate learned Bayesian eigenfunctions, participant covariance, asynchronous noise, posterior MCMC, model misspecification or population-level inferential calibration. Every fit failure is retained as its own record.

B10 boundary: The opt-in fit_bayesian_functional_changepoints() is a restricted one-break posterior on analyst-predeclared scalar projections of whole functional curves, using fixed scalar noise and Gaussian segment-mean priors. It compares an integrated no-break model against uniformly located one-break alternatives. It does not learn functional projections, support multiple breaks, serial correlations, posterior phase registration, simplex AOIs or informative observation processes. Its posterior change probability is not a frequentist p-value.

B6 genuinely learned finite-basis Gaussian factor research (still unqualified)¶

A further stacked draft PR #243 implements fit_bayesian_sparse_fpca() as a finite-basis Gaussian functional factor model. Unlike the earlier known-basis conditional score oracle, this Gibbs sampler learns a posterior over population mean and rank-K covariance from irregular native observations, as well as subject latent-score and curve reconstruction draws. The identified covariance object is B(t) L L.T B(u).T; individual loading columns cannot be interpreted as unique ordered FPCA eigenfunctions because latent rotations and signs are unidentified. Noise SD, spline dictionary, number of components and mean/loading prior scales are fixed rather than estimated. It cannot claim general Bayesian FPCA performance, correct autocorrelated gaze errors, learned hyperparameters, or nominal posterior coverage.

The B6 prior-generated pilot draws true population parameters from the implemented Gaussian priors, generates irregular observations with the model likelihood, and refits the Gibbs model per replicate. It retains failures and assesses 90% coverage at a predeclared grid location for the rotation-invariant population mean and covariance. Eight CI replicates are only an engineering smoke test. The separate optional ArviZ route inspects R-hat/ESS for integrated population moments, never claiming that running two chains by itself guarantees mixing.