Built for the Age of AI Coding Agents

🎯 One obvious, correct entry point

eyeris exposes one front door: glassbox(). A coding agent doesn’t have to know — or guess — the right order of operations, which artifacts to remove before filtering, or where baseline correction belongs. It calls glassbox(file) and gets the full, expert-vetted recipe (deblink → detransient → interpolate → lowpass filter → z-score, with per-step confound summaries) applied in the one order the field agrees on. Reducing a preprocessing pipeline to a single, prescribed call is exactly the shape an agent handles best: one function, one obviously-correct default path, nothing to assemble from scratch.

🧭 An interface that resists hallucination

Every step glassbox() runs is a real, exported, namespaced function — eyeris::deblink(), eyeris::lpfilt(), and so on — and you tune it by passing a named list keyed by that exact function name:

glassbox(
  file,
  deblink = list(extend = 40),       # -> eyeris::deblink(extend = 40)
  lpfilt  = list(plot_freqz = FALSE) # -> eyeris::lpfilt(plot_freqz = FALSE)
)

There is no non-standard evaluation to reason about, no positional argument order to memorize, and no ambiguity about which package a symbol came from. The agent names a step and names a parameter; misspelled step/argument names simply won’t be applied. To confirm what actually ran, check the recorded eyeris$params on the output object (and the summaries from summarize_confounds()). Fewer degrees of freedom means fewer places to be confidently wrong.

🔧 Expert defaults mean fewer iterations

The defaults are not placeholders — they are the opinionated starting parameters that computational neuroscientists and signal-processing experts in the Stanford Memory Lab recommend as the right default for any new pupillometry dataset (an approach inspired by fMRIPrep and Nipype). Detrending is deliberately off by default because it can distort a pupil trace; blink padding, transient thresholds, and the low-pass filter ship at values that work out of the box. The first pipeline an agent writes is usually the pipeline you wanted, so it doesn’t burn turns nudging parameters or re-deriving a sensible order of operations. Faster convergence means fewer tokens and fewer round-trips.

🔒 Output an agent can trust

eyeris is a glass box, not a black box, and that transparency is machine-readable:

• Deterministic. Given the same input, parameters, and seed, a pipeline produces the same output every run — so a figure or report an agent generates is reproducible.
• Self-recording. Every step records its own call stack and parameters into eyeris$params, and summarize_confounds() tabulates per-step data-quality metrics. The object knows what was done to it.
• Self-documenting. boilerplate() reads eyeris$params and emits an fMRIPrep-style methods paragraph — in plain prose, with the actual parameter values that ran — from the same source of truth as the code. The code that ran and the sentence that describes it cannot drift apart.
• Predictable on disk. bidsify() writes a BIDS-like derivative tree with spec-driven file names and a per-run machine-readable .json metadata sidecar, so an agent can predict output paths instead of scraping them.
• Tested. The pipeline is covered by hundreds of unit-test assertions, so the behavior an agent relies on is pinned.

An agent generating a preprocessing run for a manuscript can rely on the result being the same every time — and on being able to describe, exactly, what it did.

🧩 Composable with grammars an agent already knows

Under the hood, glassbox() is just a chain of exported functions joined by the base R pipe — a grammar every model has seen thousands of times:

system.file("extdata", "memory.asc", package = "eyeris") |>
  eyeris::load_asc(block = "auto") |>
  eyeris::deblink(extend = 50) |>
  eyeris::detransient(n = 16) |>
  eyeris::interpolate() |>
  eyeris::lpfilt(wp = 4, ws = 8, rp = 1, rs = 35) |>
  eyeris::zscore()

So when a request goes past the prescribed recipe — reorder a step, swap one out, test a parameter — the agent reaches for the same |> it already speaks and rearranges building blocks, no new framework required. And because an eyeris object is just a list of tidy data frames with a documented structure (see the Anatomy of an eyeris Object vignette), everything downstream is dplyr, tidyr, and ggplot2 — grammars deep in every model’s training data. Need a step that doesn’t exist yet? pipeline_handler() lets an agent register a custom step that plugs into the same pipeline following a documented protocol.

🤖 Agent quickstart

library(eyeris)

# 1. One opinionated call runs the full, expert-default pipeline:
output <- glassbox(eyelink_asc_demo_dataset())

# 2. Override any step by name with a named list -- no positional guessing:
output <- glassbox(
  "sub-001_task-memory.asc",
  deblink = list(extend = 40),        # args for eyeris::deblink()
  lpfilt  = list(plot_freqz = FALSE)  # args for eyeris::lpfilt()
)

# 3. Extract time-locked epochs around each event of interest:
output <- epoch(
  output,
  events = "PROBE_START_{trial}",
  limits = c(-1, 2),                  # seconds around each event
  label  = "probe"
)

# 4. Write BIDS-like derivatives + an interactive QC report (predictable paths):
bidsify(
  output,
  bids_dir       = "~/study",
  participant_id = "001",
  session_num    = "01",
  task_name      = "memory"
)

# 5. Auto-generate a methods paragraph from the exact parameters that ran:
boilerplate(output)

🗂 For LLM indexers

A machine-readable summary is published at /llms.txt. In short:

📚 Citing eyeris

citation("eyeris")
#> To cite package 'eyeris' in publications use:
#> 
#>   Schwartz ST, Yang H, Xue AM, He M (2025). "eyeris: A flexible,
#>   extensible, and reproducible pupillometry preprocessing framework in
#>   R." _bioRxiv_, 1-37. doi:10.1101/2025.06.01.657312
#>   <https://doi.org/10.1101/2025.06.01.657312>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Article{,
#>     title = {eyeris: A flexible, extensible, and reproducible pupillometry preprocessing framework in R},
#>     author = {Shawn T Schwartz and Haopei Yang and Alice M Xue and Mingjian He},
#>     journal = {bioRxiv},
#>     year = {2025},
#>     pages = {1--37},
#>     doi = {10.1101/2025.06.01.657312},
#>   }