---
title: "Posterior pupil trajectories and declared estimands"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Posterior pupil trajectories and declared estimands}
  %\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)
```

## Lightweight posterior-draw contract

The estimand layer operates on posterior prediction draws. For documentation
and tests, a deterministic draw matrix can be used without compiling Stan.

```{r estimand-draws}
grid <- expand.grid(
  .event_time = seq(0, 1, length.out = 21),
  .condition = factor(c("control", "treatment")),
  KEEP.OUT.ATTRS = FALSE
)
set.seed(2026)
mu <- ifelse(grid$.condition == "treatment", 0.15, 0) +
  0.25 * sin(pi * grid$.event_time)
draws <- matrix(
  rnorm(300 * nrow(grid), rep(mu, each = 300), 0.06),
  nrow = 300
)
pred <- as_pupil_prediction_draws(draws, grid, "millimetres")
```

## Trajectory uncertainty

```{r trajectory}
trajectory <- estimate_pupil_trajectory(pred, probability = 0.95)
head(pupil_trajectory_table(trajectory))
```

Pointwise intervals describe uncertainty at each grid value. A finite-grid
simultaneous band can be requested explicitly; it is qualified as a grid-based
posterior band rather than a universal continuous-time guarantee.

## Declared contrasts and windows

```{r declared-estimands}
contrast <- pupil_condition_contrast(
  pred,
  contrast = c("treatment", "control"),
  threshold = 0.10
)
window <- estimate_pupil_window(pred, window = c(0.3, 0.8))
auc <- estimate_pupil_auc(pred, window = c(0.3, 0.8))
peak <- estimate_pupil_peak(pred, window = c(0.3, 0.8))
latency <- estimate_pupil_peak_latency(pred, window = c(0.3, 0.8))

head(as.data.frame(contrast))
as.data.frame(window)
as.data.frame(auc)
as.data.frame(peak)
as.data.frame(latency)
```

Windows are supplied by the analyst. The package does not search across time
for the most favourable interval and relabel it confirmatory. Peak and
peak-latency summaries propagate posterior-draw uncertainty within the
declared evaluation grid.