detrend: Detrend the pupil time series

In eyeris: Flexible, Extensible, & Reproducible Pupillometry Preprocessing

Detrend the pupil time series

Description

Detrend pupil data by fitting a model of pupil_data ~ time and returning the fitted values (the estimated trend) together with the residuals (pupil_data - fitted_values). Two trend models are supported via the method argument: "linear" (the default) removes a straight-line drift by fitting an ordinary linear model, while "spline" removes a smooth, potentially nonlinear drift by fitting a natural cubic spline basis of time (splines::ns(time, df = spline_df)).

Usage

detrend(
  eyeris,
  method = c("linear", "spline"),
  spline_df = 5,
  call_info = NULL
)

Arguments

eyeris	An object of class eyeris derived from load_asc()
method	A string indicating the detrending model to fit. Either "linear" (the default) to remove a straight-line trend by regressing pupil size on time, or "spline" to remove a smooth, potentially nonlinear trend by fitting a natural cubic spline basis of time (splines::ns(time, df = spline_df))
spline_df	The degrees of freedom for the natural cubic spline basis used when method = "spline". Higher values allow the fitted trend to follow more rapid, nonlinear drift; lower values enforce a smoother trend. Must be a single whole number ⁠>= 1⁠. Defaults to 5. Ignored when method = "linear"
call_info	A list of call information and parameters. If not provided, it will be generated from the function call. Defaults to NULL

Details

This function is automatically called by glassbox() if detrend = TRUE.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

Value

An eyeris object with two new columns in ⁠time series⁠: detrend_fitted_values, and ⁠pupil_raw_{...}_detrend⁠

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Use glassbox(detrend = TRUE) for linear detrending, or glassbox(detrend = list(method = "spline")) for spline detrending.

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline

For a complete, end-to-end reference pipeline that demonstrates how all eyeris preprocessing functions are chained together in practice, see the "Building Blocks Under the Hood" section of the Anatomy of an eyeris Object vignette — vignette("anatomy", package = "eyeris") — as well as the Complete Pupillometry Pipeline Walkthrough vignette: vignette("complete-pipeline", package = "eyeris").

Examples

demo_data <- eyelink_asc_demo_dataset()

# (a) linear detrending (the default)
demo_data |>
  eyeris::glassbox(detrend = TRUE) |>  # set to FALSE to skip step (default)
  # a wider `preview_window` makes the (slow) fitted trend easier to see
  plot(seed = 0, preview_window = c(5, 20))

# (b) spline detrending (removes a smooth, nonlinear trend)
demo_data |>
  eyeris::glassbox(detrend = list(method = "spline", spline_df = 5)) |>
  plot(seed = 0, preview_window = c(5, 20))

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