Functional Dynamics and Predictive Calibration

Purpose

Version 0.5 treats the posterior trajectory itself as an object from which predeclared functional estimands can be derived. This avoids using a single peak or selected window as the only description of temporal change. The functions in this article remain descriptive: they do not infer a physiological onset, changepoint, attention state, or cognitive event.

Backend-free simulation

library(gp3bayes)

sim <- simulate_advanced_pupil_timecourse(
  n_participants = 18,
  trials_per_participant = 4,
  time_points = 41,
  time_range = c(-200, 1800),
  family = "student",
  residual_scale = 0.08,
  seed = 2050
)

plot_advanced_pupil_simulation(sim)

Fit declaration

spec <- specify_advanced_pupil_timecourse_model(
  sim$data,
  temporal_structure = "gaussian_process",
  family = "student",
  residual_scale = "condition_time",
  gp_spec = create_pupil_gp_spec("matern32", basis = "approximate", k = 25),
  autocorrelation = "none",
  predictive_target = "future_segment"
)

audit_advanced_pupil_identifiability(spec)
#> <gp3bayes_pupil_identifiability_audit>
#>   Overall: review 
#>   Certification: FALSE
#>        domain                      check          value status
#>        design                       rows           2952   pass
#>        design               participants             18   pass
#>        design     minimum_condition_rows           1476   pass
#>      temporal      minimum_series_length             41   pass
#>      temporal       median_series_length             41   pass
#>    trajectory         unique_time_points             41   pass
#>    trajectory              gp_basis_rank             25   pass
#>   missingness  response_missing_fraction        0.03117   pass
#>  distribution       distributional_sigma condition_time   pass
#>  distribution student_degrees_of_freedom      estimated review
pupil_model_card(spec)
#> <gp3bayes_pupil_model_card>
#>                   field            value
#>        gp3bayes_version       0.5.0.9000
#>           fit_performed            FALSE
#>                 backend             none
#>                    rows             2952
#>            participants               18
#>              conditions                2
#>                  family          student
#>      temporal_structure gaussian_process
#>          residual_scale   condition_time
#>         autocorrelation             none
#>  participant_trajectory             none
#>       measurement_model            FALSE
#>       missingness_model            FALSE
#>       predictive_target   future_segment
#>       complexity_status               ok
#> Governance:
#>   - No automatic preprocessing, interpolation, exclusion, or model selection.
#>   - No automatic cognitive-state, causal, or adequacy interpretation.
#>   - Measurement and missingness models remain assumption-conditional.
#>   - Predictive comparison is tied to an explicitly declared target.

The Student-t and ARMA layers are deliberately not combined by the governed 0.5 interface. Robust observation tails and residual serial dependence should first be assessed as separately declared candidate explanations.

Posterior derivatives

The following fit is intentionally not executed while building the vignette.

fit <- fit_advanced_pupil_model_cmdstanr(spec)
traj <- predict_advanced_pupil_trajectory(fit, ndraws = 1000)

d1 <- estimate_pupil_trajectory_derivative(traj, order = 1)
plot_pupil_trajectory_derivative(d1)

contrast <- estimate_pupil_dynamic_contrast(
  traj,
  contrast = c("treatment", "control"),
  threshold = 0.05
)
plot_pupil_dynamic_contrast(contrast)

estimate_pupil_threshold_duration(
  contrast,
  direction = "absolute",
  threshold = 0.05
)

A derivative summarizes rate of posterior trajectory change. It is not an automatic response-onset detector. Likewise, duration above a threshold is only meaningful when that threshold was scientifically prespecified.

Predictive calibration on held-out data

cal <- audit_pupil_predictive_calibration(
  fit,
  newdata = held_out_trials,
  ndraws = 1000,
  probability = 0.90,
  allow_new_levels = FALSE
)

as.data.frame(cal)
plot_pupil_predictive_calibration(cal)

The reported RMSE, MAE, bias, interval coverage, interval width, and draw-based CRPS describe the supplied prediction task. They become out-of-sample evidence only when newdata was genuinely withheld from fitting.