Fit the M4 latent response-process state model — fit_multimodal

Fits the marginalized M4 state model using CmdStanR. Sequence order is validated but never silently changed. The latent state contributes only to selected process channels in the reference implementation; the scored-response Rasch equation remains exactly state-independent.

Usage

fit_multimodal_m4(
  x,
  spec = NULL,
  person = "person_id",
  item = "item_id",
  response = "response",
  rt = "rt",
  gaze = "gaze",
  pupil = "pupil",
  sequence = "sequence_id",
  order = "trial_index",
  baseline = "pupil_baseline",
  luminance = "luminance",
  gaze_x = "gaze_x",
  gaze_y = "gaze_y",
  quality = "pupil_quality",
  time_on_task = "time_on_task",
  blink = "pupil_blink",
  interpolated = "pupil_interpolated",
  device = "device",
  session = "session",
  sampling_rate = "sampling_rate_hz",
  pupil_scale = c("z", "raw"),
  n_states = 2L,
  state_channels = c("rt", "gaze", "pupil"),
  transition_structure = c("markov", "iid"),
  trait_conditioning = c("theta", "tau"),
  initial_trait_conditioning = TRUE,
  min_sequence_length = 2L,
  prior_profile = c("regularized", "paper_centered"),
  nuisance = stats::setNames(rep(TRUE, 8L), .ep10_m3_nuisance_names),
  chains = 4L,
  parallel_chains = chains,
  iter_warmup = 1000L,
  iter_sampling = 1000L,
  seed = 20260820L,
  adapt_delta = 0.97,
  max_treedepth = 13L,
  refresh = 100L,
  quiet_compile = TRUE,
  init = 0
)

Arguments

x: Data frame, M4 simulation, or compatible eyeprocess object.
spec: Optional `multimodal_m4_spec()`. When omitted, a conservative two-state specification is created from the explicit arguments.
person, item, response, rt, gaze, pupil: Column names.
sequence, order: Sequence identifier and within-sequence order columns.
baseline, luminance, gaze_x, gaze_y, quality, time_on_task, blink, interpolated: Optional M3 pupil nuisance columns.
device, session, sampling_rate: Optional measurement-context columns.
pupil_scale: `"z"` or `"raw"`.
n_states, state_channels, transition_structure, trait_conditioning: Used only when `spec` is null.
initial_trait_conditioning, min_sequence_length: Used only when `spec` is null.
prior_profile, nuisance: Used only when `spec` is null.
chains, parallel_chains, iter_warmup, iter_sampling: Sampling controls.
seed, adapt_delta, max_treedepth, refresh, quiet_compile, init: CmdStan controls.

Value

An `eye_multimodal_m4_fit` retaining data, sequence audit, specification, Stan data, sampling controls, and provenance.