---
title: "Validation for temporally dependent pupil data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Validation for temporally dependent pupil data}
  %\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)
```

## Start with the prediction target

Temporally dependent samples should not automatically be treated as
exchangeable observation-level units. `create_pupil_validation_plan()` makes
the intended target explicit before computing validation.

```{r validation-plan}
sim <- simulate_pupil_timecourse(
  n_participants = 6,
  trials_per_participant = 4,
  sampling_frequency = 10,
  time_window = c(-0.3, 1),
  baseline_window = c(-0.3, 0),
  seed = 21
)
contract <- create_pupil_contract(
  outcome_col = "pupil_mm",
  participant_col = "participant_id",
  trial_col = "trial_id",
  condition_col = "condition",
  time_col = "event_time",
  pupil_unit = "millimetres",
  sampling_frequency = 10
)
prepared <- prepare_pupil_timecourse(sim$data, contract)

trial_plan <- create_pupil_validation_plan(
  prepared,
  target = "new_trial_known_participant",
  K = 4,
  seed = 21
)
trial_plan
```

Other supported targets distinguish a new participant and a future time
segment.

```{r validation-targets}
participant_plan <- create_pupil_validation_plan(
  prepared,
  target = "new_participant",
  K = 3,
  seed = 21
)
future_plan <- create_pupil_validation_plan(
  prepared,
  target = "future_segment",
  future_fraction = 0.2
)
participant_plan
future_plan
```

## Execution

```{r validation-execute, eval=FALSE}
trial_cv <- validate_pupil_model(
  pupil_fit,
  trial_plan,
  execute = TRUE
)
pupil_validation_table(trial_cv)
plot_pupil_validation(trial_cv)
```

Grouped K-fold uses complete validation groups. The future-segment target uses
a chronological holdout and explicit refitting rather than presenting
ordinary observation-wise PSIS-LOO as a universal time-series solution.
Validation answers only the declared predictive question.