simulate_eyeris: Generate a synthetic 'eyeris' object with realistic pupil...

In eyeris: Flexible, Extensible, & Reproducible Pupillometry Preprocessing

Generate a synthetic eyeris object with realistic pupil characteristics

Description

Simulates a pupil time series whose statistical and morphological characteristics resemble real EyeLink recordings — a tonic baseline with slow drift and hippus, canonical task-evoked phasic dilations, blinks with partial-occlusion flank spikes, isolated transient artifacts, measurement noise, and optional high-frequency line noise — and wraps it in a fully valid S3 eyeris object.

Because the returned object is byte-compatible with the output of load_asc(), it flows unchanged through the entire eyeris pipeline: deblink(), detransient(), interpolate(), lpfilt(), downsample(), detrend(), zscore(), plot.eyeris(), epoch(), and summarize_confounds().

Usage

simulate_eyeris(seed = 1L, params = sim_params(), block = 1L, verbose = TRUE)

Arguments

seed	Integer random seed for reproducible generation. Defaults to 1
params	A parameter list from sim_params(). Defaults to sim_params()
block	Numeric block label written into the time series. Defaults to 1
verbose	Logical; print a short status message. Defaults to TRUE

Details

The signal is generated deterministically given seed: the same seed and params always yield an identical object, and the global random number generator state is left untouched (generation is confined via withr::with_seed()). See sim_params() for the full generative model and every tunable component.

The clean latent signal (before artifacts and noise) and the indices of the injected artifacts are attached to the returned object as the attribute "sim_truth" for use as ground truth in quantitative demonstrations; note that this attribute does not survive the pipeline step functions (which rebuild the time series data frame), so downstream tooling recomputes ground truth from a retained copy rather than relying on the attribute.

Value

An object of S3 class eyeris (see the Anatomy of an eyeris Object vignette — vignette("anatomy", package = "eyeris")), with a "sim_truth" attribute describing the ground-truth signal.

See Also

sim_params() to configure the synthetic signal.

Examples

# generate a synthetic recording and run it through the pipeline
sim <- simulate_eyeris(seed = 1, params = sim_params(duration_secs = 20))


out <- sim |>
  eyeris::deblink() |>
  eyeris::detransient() |>
  eyeris::interpolate() |>
  eyeris::lpfilt() |>
  eyeris::zscore()

pdf(tempfile(fileext = ".pdf"))
plot(out, seed = 1)
dev.off()

eyeris documentation built on Aug. 1, 2026, 1:07 a.m.