---
title: "Gaussian-Process Pupil Trajectories"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Gaussian-Process Pupil Trajectories}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r}
library(gp3bayes)
sim <- simulate_advanced_pupil_timecourse(
  n_participants = 12,
  trials_per_participant = 4,
  time_points = 41,
  seed = 3020
)
```

# Approximate GP is the default

```{r}
gp32 <- create_pupil_gp_spec("matern32", "approximate", k = 30)
gp52 <- create_pupil_gp_spec("matern52", "approximate", k = 30)
gpeq <- create_pupil_gp_spec("exp_quad", "approximate", k = 30)

gp32
gp52
gpeq
```

```{r}
spec <- specify_advanced_pupil_timecourse_model(
  sim$data,
  temporal_structure = "gaussian_process",
  gp_spec = gp32,
  family = "gaussian",
  autocorrelation = "none",
  predictive_target = "future_segment"
)

spec
plot_pupil_model_complexity(spec)
```

Exact GP computation remains available, but the complexity audit requires explicit review when the unique time-by-condition grid becomes large.

# Hyperparameters are posterior estimands

```{r eval=FALSE}
fit <- fit_advanced_pupil_model_backend(spec, backend = "cmdstanr")
hyper <- pupil_gp_hyperparameters(fit)
pupil_gp_table(hyper)
plot_pupil_gp_hyperparameters(hyper)

trajectory <- predict_advanced_pupil_trajectory(fit)
plot_advanced_pupil_trajectory(trajectory)
```

Length scale and marginal GP standard deviation describe the fitted temporal function prior/posterior. They are not direct psychological constructs.