Simulation-based calibration and measurement-resolution guards

Bayesian/process estimators can be computationally wrong even when they return plausible-looking results. sbc_rank_diagnostics() provides a lightweight diagnostic layer for rank-based simulation-based calibration (SBC). The function deliberately does not fit a Bayesian model itself: users provide the ranks generated by a correctly specified simulation/inference loop. This keeps the diagnostic separate from the estimator and avoids pretending that SBC establishes substantive model validity.

ranks <- read.csv(system.file("extdata", "sbc_rank_demo.csv", package = "eyeprocess"))
sbc <- sbc_rank_diagnostics(ranks$rank, n_draws = unique(ranks$n_draws), bins = 10)
print(sbc)
plot(sbc)
sbc_ecdf_deviation(sbc)

SBC asks whether posterior computation is calibrated under the declared generative model; it does not establish that the generative model is scientifically correct for real participants or tasks. The architecture follows the rank-calibration logic described by Talts et al. (2018) and current Stan documentation.

Measurement resolution poses a separate problem. An analysis may request temporal or spatial distinctions finer than the empirical recording quality can credibly support. analysis_resolution_guard() combines an observed/declared event duration and effective sampling frequency with optional spatial feature size and radial error. The thresholds are researcher-declared compatibility rules, not universal eye-tracking quality cutoffs.

analysis_resolution_guard(
  event_duration_ms = 100,
  effective_hz = 60,
  spatial_feature_size = .20,
  radial_error = .04,
  min_samples = 3,
  max_error_fraction = .5
)

For pupil analyses, audit_pupil_preprocessing_order() and pupil_baseline_sensitivity() make the preprocessing sequence and baseline-window dependence inspectable. They report consequences of declared choices rather than automatically selecting a preferred baseline.

pupil <- read.csv(system.file("extdata", "pupil_baseline_demo.csv", package = "eyeprocess"))
pupil_baseline_sensitivity(
  pupil,
  time = "time_ms",
  pupil = "pupil",
  by = c("person_id", "trial_id"),
  windows = list(W500 = c(-500, 0), W300 = c(-300, 0), W200 = c(-200, 0))
)