eyeris

This minor release changes how missing pupil data is handled, broadens the range of eye trackers eyeris can ingest, and refreshes every diagnostic figure. The headline **breaking change** is that interpolate() no longer interpolates across arbitrarily long gaps: stretches of consecutive missing samples longer than the new max_gap_ms limit (default 250 ms, following Kret & Sjak-Shie, 2018) are now left as NA, and the downstream steps that cannot operate on missing data (lpfilt(), downsample(), bin(), detrend()) now work *around* those gaps and restore them, rather than being skipped. New features include load_generic(), a tracker-agnostic loader that lets non-EyeLink data enter the pipeline (with glassbox() now accepting a pre-loaded eyeris object); a sampling-uniformity guardrail plus an automatic resample() step for hardware that silently *drops* samples instead of zero-filling them; spline detrending via detrend(method = "spline"); and simulate_eyeris()/sim_params() for generating seeded, synthetic, pipeline-compatible pupil data with known ground truth. Bug fixes restore the fitted detrend coefficients on the glassbox() output, repair per-run epoch CSV writing in bidsify() for both multi-run objects and run_num overrides, and resolve a multi-block crash on R >= 4.2. Under the hood, all diagnostic plotting migrated from base graphics to reaborn/ggplot2.

🚨 **Breaking changes & deprecations**

• **BREAKING (#295)**: interpolate() now enforces a maximum gap duration for linear interpolation via a new max_gap_ms parameter. Gaps of consecutive missing (NA) samples that are **longer** than max_gap_ms are now left as NA rather than interpolated over. The default of 250 ms follows the recommendation of Kret & Sjak-Shie (2018), who advise against interpolating across long gaps where linear interpolation is unlikely to reflect the true underlying pupil signal. Previously (eyeris ≤ 3.2.0), **all** gaps were interpolated regardless of duration. This is a change in default behavior and may affect downstream results; eyeris now prints a console notice (at most once per glassbox() run) when the limit is in effect. To restore the previous behavior of interpolating across all gaps, set interpolate = list(max_gap_ms = Inf) in glassbox() (or max_gap_ms = Inf when calling interpolate() directly). The threshold can also be customized, e.g., glassbox(interpolate = list(max_gap_ms = 100)). The limit is specified in milliseconds and is internally converted to a number of samples using each recording's own sampling rate, so it behaves consistently across sampling frequencies, by @shawntz in #318.
• **ENH (#295)**: The downstream glassbox() steps that cannot operate on missing data — low-pass filtering (lpfilt()), downsampling (downsample()), binning (bin()), and detrending (detrend()) — now work *around* the gaps that interpolate(max_gap_ms) intentionally leaves as NA. They filter/resample/fit over the available data (filling temporarily where needed) and then restore the gaps as NA, so the long-gap NAs are preserved through to the final preprocessed output instead of causing these steps to be skipped. When interpolation has not been run upstream, the filter/resample steps still raise the usual "interpolate first" error, by @shawntz in #318.
• **ENH (#295)**: lpfilt() and downsample() now emit a warning when they filter over gaps longer than max_gap_ms (left as NA by interpolate()). Because a low-pass/anti-aliasing filter cannot run on missing data, these gaps are temporarily filled and then masked back to NA; the filter can therefore slightly bias the valid pupil samples immediately adjacent to each gap toward the (near-linear) interpolated values — analogous to the edge artifacts seen at the start/end of a filtered recording, but repeated at every long gap. The warning lets you decide whether to disable filtering and/or downsampling (lpfilt = FALSE and/or downsample = FALSE) to avoid introducing this systematic bias, at the cost of retaining more high-frequency content. The console warning fires at most once per glassbox() run, and the same information is recorded as a **"Data Quality Notes"** section in the HTML preprocessing report so it is captured as part of the data provenance, by @shawntz in #318.

🚀 New features

• **NF**: **detrend() now supports spline detrending via a new method argument.** Detrending previously only removed a straight-line (linear) trend, which cannot capture the slow, *nonlinear* drift often present in longer recordings. detrend() now accepts method = "linear" (the default, preserving the previous behavior of regressing pupil size on time) or method = "spline", which removes a smooth, potentially nonlinear trend by fitting a natural cubic spline basis of time (splines::ns(time, df = spline_df)). The flexibility of the fitted spline is controlled by the new spline_df argument (degrees of freedom; default 5). Both models return the fitted trend and the residuals exactly as before, so all downstream steps, plots, and reports are unchanged aside from the trend shape. Enable it in the pipeline with glassbox(detrend = list(method = "spline")) (optionally spline_df = ...), or call detrend(method = "spline") directly, by @shawntz in #349.
• **NF (#299)**: **Added load_generic(), a tracker-agnostic data loader for non-EyeLink eye trackers.** Until now, load_asc() (for SR Research EyeLink .asc files) was the only implemented loader, which prevented researchers using other eye trackers from running their data through eyeris. load_generic() accepts three standardized data frames — pupil (raw samples: timestamp + pupil size, optionally gaze eye_x/eye_y), events (timestamp + message text), and blinks (blink start/end intervals) — plus an optional fourth gaze data frame for the less common case where gaze is exported separately from pupil size (joined onto pupil by timestamp). These are assembled into the exact same eyeris S3 object that load_asc() produces, making the result a drop-in input to glassbox(), epoch(), bidsify(), and the plotting methods. Column names are configurable via the mapping argument; sampling rate is inferred from the timestamps when not supplied; timestamps may be provided in milliseconds (default) or seconds (time_unit = "s"); and block/eye/pupil_type/screen-dimension metadata mirror load_asc(). Native readers for specific tracker formats can now be layered on top of this function incrementally, by @shawntz in #311.
• **NF**: **glassbox() now accepts a pre-loaded eyeris object** (e.g., from load_generic()), automatically skipping the file-loading step and running the remaining pipeline on the object directly. This makes load_generic(...) |> glassbox() work as expected, and also means an already-loaded load_asc() object piped into glassbox() now processes correctly instead of raising an error, by @shawntz in #311.
• **ENH (#300)**: Added a hardware-quirk guardrail that detects non-uniform sampling intervals in the input timeseries. Different eye trackers behave differently when pupil data is missing: EyeLink zero-fills, but some hardware silently *drops* samples, leaving gaps in the otherwise evenly spaced time vector. Because downstream pipeline steps (e.g., detransient(), lpfilt(), downsample()) assume a fixed sampling rate, such gaps can silently distort results. The new internal check_uniform_sampling_intervals() helper infers the expected inter-sample interval from the data (robust to dropped samples and sub-millisecond timestamp rounding), checks each recording segment independently so that legitimate between-block gaps are not flagged, and emits an informative warning estimating the number of dropped samples when irregular intervals are detected. It also cross-checks the data-derived interval against the device's reported sampling rate to catch *systematic* dropout (e.g., every Nth sample missing), which leaves a uniform but coarser grid that gap detection alone cannot see. The check is wired into load_asc() so the quirk is surfaced early, before any preprocessing begins, by @shawntz in #308.
• **ENH (#320)**: Added an automatic resample() step that repairs the **time axis** of recordings whose hardware *drops* samples (instead of zero-filling) when pupil data is missing — the dropped-sample quirk surfaced by the #300 guardrail. When glassbox() detects irregular sampling intervals (gated on the robust check_uniform_sampling_intervals() detector from #300), it places each block onto the expected uniform sampling grid in two stages: (1) it anchors the grid on the first *reliable* regular interval (rather than the first timestamp), so early sub-period timing jitter doesn't offset the whole grid, and back-extends the grid to cover any earlier samples; then (2) it resamples the observed data onto that grid — linearly interpolating across short/jittered intervals, and inserting NA rows for any interval longer than the expected period (dropped samples), flagged in a new logical is_resampled column and left for the existing interpolate() step to fill. Because a gap is now represented as explicit missing data (never fabricated values), interpolate() decides how much of a missing span to fill according to its own policy (see the #295 max_gap_ms limit). This turns the "dropped-sample" problem into the ordinary "missing-value" problem the rest of the pipeline already handles. It runs **automatically and by default**, but only when needed: it is a guaranteed no-op for already-uniform data (e.g., EyeLink) and deliberately leaves high-rate recordings that report integer-millisecond timestamps untouched (so it never collapses genuine sub-millisecond samples). Opt out with glassbox(resample = FALSE). summarize_confounds() now also reports n_resampled/prop_resampled per block, by @shawntz in #320.
• **NF**: **Added simulate_eyeris() and sim_params(), a seeded synthetic pupil data generator with known ground truth.** eyeris previously had no way to produce synthetic pupil data, making it difficult to write self-contained tests, build reproducible documentation examples, or demonstrate how a preprocessing step behaves without shipping and loading a real recording. sim_params() builds the signal-model parameter list, with every component independently toggle-able and validated: tonic baseline, slow drift, hippus, Hoeks & Levelt phasic responses, blinks (missing cores plus occlusion flank spikes), transient spikes, broadband noise, and optional line noise. simulate_eyeris() then generates the signal under a confined RNG (withr::with_seed(), so the global .Random.seed is left untouched) and delegates to the same internal object constructor used by load_asc(), so the returned eyeris object is structurally identical to a real recording and flows through the entire pipeline unchanged (deblink() … zscore(), glassbox(), plot(), epoch(), summarize_confounds()). This addition is purely additive and changes no existing behavior, by @shawntz in #351.