fit_multimodal_m4: Fit the M4 latent response-process state model

In eyeprocess: Harmonize Eye-Tracking, Pupillometry, Biometrics, and Psychometric Process Data

Fit the M4 latent response-process state model

Description

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.

eyeprocess documentation built on Sept. 28, 2026, 5:08 p.m.