---
title: "Functional pupil-IRT modelling"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Functional pupil-IRT modelling}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

# Measurement stance

Pupil diameter is treated as a physiological time series. It is not automatically labelled cognitive load, effort, surprise, or arousal. The model preserves preprocessing choices and includes nuisance adjustment before any substantive interpretation.

# Specification

```{r, eval=FALSE}
spec <- functional_pupil_irt_spec(
  df = 6L,
  basis = "natural_spline",
  response = "score",
  engine = "stan",
  alignment = "event",
  latency_ms = 200,
  baseline_window = c(-500, 0),
  baseline_method = "subtract",
  time_window = c(-200, 2000),
  luminance_column = "luminance",
  gaze_x_column = "x",
  gaze_y_column = "y",
  blink_column = "blink",
  interpolated_column = "interpolated",
  max_interpolated_fraction = 0.20,
  ar1 = TRUE,
  participant_effect = TRUE,
  item_effect = TRUE
)

prepared <- prepare_functional_pupil_data(pupil_trials, spec)
basis <- functional_pupil_basis(prepared$data$time, df = 6)
fit <- fit_joint_functional_pupil_irt(pupil_trials, spec, seed = 42)
```

The Stan engine jointly models the binary item outcome and pupil trajectory using shared person/item effects, functional bases, luminance and gaze-position covariates, and optional AR(1) residual structure.

# Diagnostics and scalar comparisons

```{r, eval=FALSE}
extract_functional_pupil_parameters(fit)
functional_pupil_diagnostics(fit)
compare_functional_scalar_models(fit)
```

Scalar peak or area-under-the-curve summaries are retained as transparent baselines rather than assumed to be inferior.

# Preprocessing sensitivity

```{r, eval=FALSE}
grid <- pupil_preprocessing_grid(
  baseline_windows = list(c(-500, 0), c(-200, 0)),
  latency_ms = c(100, 200, 300),
  basis_df = c(4L, 6L, 8L),
  baseline_methods = c("subtract", "percent"),
  max_interpolated_fraction = c(0.10, 0.20)
)

sensitivity <- pupil_preprocessing_sensitivity(pupil_trials, grid, spec)
plot(sensitivity)
```

Promotion requires recovery under autocorrelation, luminance confounding, blink/interpolation variation, baseline uncertainty, and external experimental validation.