---
title: "M2 Three-Way Reference Model: Response, RT, and Gaze"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{M2 Three-Way Reference Model: Response, RT, and Gaze}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Scope

The M2 milestone implements a likelihood-faithful three-way response-process model motivated by Man, Harring, and Zhan (2022), DOI `10.1177/01466216221089344`. The measurement layer combines a Rasch response model, a lognormal response-time model, and a negative-binomial fixation-count model. Person-side ability, speed, and gaze-process effects are correlated; item difficulty, time intensity, and gaze intensity are also correlated.

The implementation deliberately separates **likelihood fidelity** from **prior fidelity**. `prior_profile = "regularized"` uses regularizing Stan priors. `"paper_centered"` centers priors near values described in the source literature but is not claimed to reproduce every published hyperprior exactly.

No process channel is automatically interpreted as attention, cognitive load, guessing, strategy, or difficulty.

## Canonical specification

```{r}
library(eyeprocess)

spec <- multimodal_m2_spec()
spec
```

The object is not a new specification ecosystem. It inherits the existing `eye_multimodal_irt_spec` and `eye_irt_model_spec` architecture and composes the established `irt_*_channel()` constructors.

## Simulation

```{r}
sim <- simulate_multimodal_m2(
  n_person = 80,
  n_item = 10,
  seed = 20260814
)

head(sim$data)
sim
```

The complete generating data and all latent truth are retained separately in `sim$complete_data` and `sim$truth`.

## Structural audit

```{r}
audit <- audit_multimodal_m2_identifiability(sim$data)
audit
```

The audit is a conservative pre-fit screen. Passing it does not prove global identifiability, empirical adequacy, or construct validity.

## CmdStan fit

The estimator is gated. It fails explicitly if CmdStanR/CmdStan are unavailable and does not substitute another engine.

```{r, eval=FALSE}
fit <- fit_multimodal_m2(
  sim,
  chains = 4,
  parallel_chains = 4,
  iter_warmup = 1000,
  iter_sampling = 1000,
  seed = 9001
)

summary(fit)
plot(fit, type = "person_correlations")
plot(fit, type = "item_correlations")
plot(fit, type = "item_parameters")
```

## Identification

The reference implementation fixes the person latent means to zero, fixes the response discrimination to one, uses a fixed `-1` speed loading in the log-time mean, and a fixed `+1` gaze-process loading in the negative-binomial log mean. These constraints define the channel scales. The structural covariance parameters remain estimated.

## Missingness

Channel-specific missing observations are omitted from that channel likelihood under an explicit **ignorable missingness** assumption. This does not validate MAR/MNAR assumptions. Informative channel dropout belongs to a separate missingness model and sensitivity analysis.

## Interpretation boundary

The M2 estimator answers a measurement question: whether a joint probabilistic model can use response, RT, and gaze-count observations coherently. Psychological labels require external design and validation evidence.