---
title: "Bayesian dynamic pupillometry: governed foundation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Bayesian dynamic pupillometry: governed foundation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4.5
)
library(gp3bayes)
```

## Scope

Development version 0.4.0.9000 adds a restricted Gaussian hierarchical
pupil-timecourse family. The family is designed for pupil series that have
already been produced by a documented preprocessing workflow. It does not
detect blinks, interpolate samples, correct pupil foreshortening error (PFE),
or infer psychological constructs from pupil change.

The workflow is deliberately staged:

1. declare a pupil contract;
2. prepare data only through explicit deterministic transformations;
3. inspect readiness and measurement-context audits;
4. create a closed model specification;
5. fit through an approved `rstan` or `cmdstanr` backend;
6. estimate declared pupil trajectories and window estimands;
7. inspect posterior predictive and temporal diagnostics;
8. validate against an explicit prediction target; and
9. compare prespecified sensitivity scenarios.

## Deterministic synthetic example

```{r overview-sim}
sim <- simulate_pupil_timecourse(
  n_participants = 6,
  trials_per_participant = 4,
  sampling_frequency = 20,
  time_window = c(-0.5, 1.5),
  seed = 20260814
)
str(sim$truth, max.level = 1)
```

The simulator uses one convenient smooth response waveform for software
testing. It is not a claim that all biological pupil responses have this
shape.

```{r overview-contract}
contract <- create_pupil_contract(
  outcome_col = "pupil_mm",
  participant_col = "participant_id",
  trial_col = "trial_id",
  item_col = "item_id",
  condition_col = "condition",
  time_col = "event_time",
  pupil_unit = "millimetres",
  sampling_frequency = 20,
  eye = "combined",
  source_vendor = "synthetic",
  blink_col = "blink",
  interpolation_col = "interpolated",
  gaze_x_col = "gaze_x",
  gaze_y_col = "gaze_y",
  luminance_col = "luminance",
  baseline_window = c(-0.5, 0),
  baseline_method = "none"
)
prepared <- prepare_pupil_timecourse(sim$data, contract)
audit <- audit_pupil_readiness(prepared)
pupil_readiness_table(audit)
```

Readiness output is evidence about the observed series. A warning is not an
automatic exclusion rule, and a pass is not evidence that the measurement or
scientific interpretation is valid.

## Restricted specification

```{r overview-spec}
spec <- specify_pupil_timecourse_model(
  prepared,
  temporal_structure = "smooth",
  condition_trajectory = TRUE,
  smooth_basis_dimension = 6,
  autocorrelation = "ar1",
  participant_trajectory = "none",
  item_effects = TRUE
)
pupil_specification_table(spec)
```

The specification constructs the approved formula internally. There is no
user-facing arbitrary formula or arbitrary family argument.

## Interpretation boundary

Reported quantities are pupil diameter, pupil change, trajectories, and
posterior contrasts in those measurements. They are not automatically
cognitive load, attention, arousal, stress, emotion, surprise, or effort.
Those interpretations require a separate scientific argument and appropriate
experimental design.