Skip to content

custom extensions

Jump to bottom
GitHub Actions edited this page Aug 4, 2025 · 1 revision

Building Your Own Custom Pipeline Extensions

One key strength of the preprocessing framework within eyeris is its modularity.

While we encourage most users to use the glassbox() function for simplicity and reproducibility, advanced users can create custom preprocessing steps that seamlessly integrate into the pipeline.

This vignette walks you through the structure required to write your own eyeris-compatible preprocessing functions.

🧩 How the Pipeline Works

Under the hood, each preprocessing function in eyeris is a wrapper around a core operation that gets tracked, versioned, and stored using the pipeline_handler().

Custom pipeline steps must conform to the eyeris protocol for maximum compatibility with the downstream functions we provide.

Following the eyeris protocol also ensures: - all operations follow a predictable structure, and - that new pupil data columns based on previous operations in the chain are able to be dynamically constructed within the core timeseries data frame.

For instance: pupil_raw -> pupil_raw_deblink -> pupil_raw_deblink_detransient -> ...

If you’re unfamiliar with how these columns are structured and tracked, first check out the companion vignette: 📦 Anatomy of an eyeris Object.

🛠 Creating a Custom Extension for eyeris

Let’s say you want to write a new eyeris extension function called winsorize() to apply winsorization to extreme pupil values.

1) Write the core operation function

This function should accept a data frame x, a string prev_op (i.e., the name of the previous pupil column), and any custom parameters.

To illustrate:

winsorize_pupil <- function(x, prev_op, lower = 0.01, upper = 0.99) {
  vec <- x[[prev_op]]
  q <- quantile(vec, probs = c(lower, upper), na.rm = TRUE)
  vec[vec < q[1]] <- q[1]
  vec[vec > q[2]] <- q[2]
  vec
}

2) Create the wrapper using the eyeris::pipeline_handler()

The pipeline_handler() enables your function to automatically:

  • track your function within the eyeris list object’s params field,
  • append a new column to each block within the timeseries list of data frames, and
  • update the object’s latest pointer.

To illustrate:

#' Winsorize pupil values
#'
#' Applies winsorization to extreme pupil values within each block.
#'
#' @param eyeris An `eyeris` object created by [load_asc()].
#' @param lower Lower quantile threshold. Default is 0.01.
#' @param upper Upper quantile threshold. Default is 0.99.
#' @param call_info A list of call information and parameters. If not provided,
#'   it will be generated from the function call.
#'
#' @return Updated `eyeris` object with new winsorized pupil column.
winsorize <- function(eyeris, lower = 0.01, upper = 0.99, call_info = NULL) {
  # create call_info if not provided
  call_info <- if (is.null(call_info)) {
    list(
      call_stack = match.call(),
      parameters = list(lower = lower, upper = upper)
    )
  } else {
    call_info
  }

  # handle binocular objects
  if (is_binocular_object(eyeris)) {
    # process left and right eyes independently
    left_result <- eyeris$left |>
      pipeline_handler(
        winsorize_pupil,
        "winsorize",
        lower = lower,
        upper = upper,
        call_info = call_info
      )
    
    right_result <- eyeris$right |>
      pipeline_handler(
        winsorize_pupil,
        "winsorize",
        lower = lower,
        upper = upper,
        call_info = call_info
      )
    
    # return combined structure
    list_out <- list(
      left = left_result,
      right = right_result,
      original_file = eyeris$original_file,
      raw_binocular_object = eyeris$raw_binocular_object
    )

    class(list_out) <- "eyeris"

    return(list_out)
  } else {
    # regular eyeris object, process normally
    eyeris |>
      pipeline_handler(
        winsorize_pupil,
        "winsorize",
        lower = lower,
        upper = upper,
        call_info = call_info
      )
  }
}

3) Understanding Call Stack Tracking

The call_info parameter is crucial for maintaining reproducibility and debugging in eyeris. It captures:

  • call_stack: The exact function call that was made (using match.call())
  • parameters: A list of all parameters passed to your function

This information is automatically stored in eyeris$params[[new_suffix]] and can be used for: - Generating reproducible reports - Debugging pipeline issues - Tracking parameter changes across different runs

Important Notes: - Always include call_info = NULL as the last parameter in your function signature - Use match.call() to capture the function call - Pass all your function parameters in the parameters list - Always pass call_info = call_info as the last argument to pipeline_handler()

4) Function Structure Breakdown

  1. Function signature: Always include call_info = NULL as the last parameter
  2. Call info creation: Create the call_info list if not provided
  3. Pipeline handler call: Pass all parameters including call_info
  4. Parameter order:
    • First: eyeris object
    • Second: your core operation function name
    • Third: the suffix for column naming
    • Fourth+: your function parameters
    • Last: call_info = call_info

🎉 And that’s it!

You should now be able to use your new function extension as a component within a new custom eyeris pipeline declaration. To illustrate:

system.file("extdata", "memory.asc", package = "eyeris") |>
  eyeris::load_asc(block = "auto") |>
  eyeris::deblink(extend = 50) |>
  winsorize()

💪 Best Practices

  • Use consistent naming: i.e., match your suffix (e.g. "winsorize") to the column and log structure:
    • If you call pipeline_handler(..., "winsorize")
    • Then, your function names should reflect that:
      • the public facing winsorize() wrapper function, and
      • the private winsorize_pupil() logic implementation function.
    • You will then see pupil_raw_*_winsorize as the new output column!
  • Respect previous steps: Your custom function should rely only on prev_op, not on any hardcoded column names!
  • Return the expected data type: Be sure that you private function always returns a modified vector type, as the underlying pipeline_handler() is looking out for a vector it can transpose into the new column that will be added to the timeseries data frame within the resulting eyeris object.
  • Test on individual blocks: Always try your private function logic on a single data block (e.g., eyeris$timeseries[[1]]) to debug before integrating it with the eyeris pipeline protocol.
  • Include call stack tracking: Always implement proper call_info handling for reproducibility and debugging capabilities.

🔍 Advanced: Custom Call Info Handling

For more complex functions, you might want to customize the call_info structure:

custom_function <- function(eyeris, param1, param2, call_info = NULL) {
  # custom call_info with additional metadata
  call_info <- if (is.null(call_info)) {
    list(
      call_stack = match.call(),
      parameters = list(param1 = param1, param2 = param2),
      metadata = list(
        timestamp = Sys.time(),
        version = "1.0.0",
        description = "Custom processing step"
      )
    )
  } else {
    call_info
  }

  pipeline_handler(
    eyeris,
    custom_pupil_function,
    "custom",
    param1 = param1,
    param2 = param2,
    call_info = call_info
  )
}

✨ Summary

We hope you are now convinced at the power and extensibility the eyeris protocol enables! As we demonstrated here, with just a little bit of structure, you can create custom extension steps tailored to your specific analysis needs – all while preserving the reproducibility and organizational core principles eyeris was designed and built around.

If you’d like to contribute new steps to eyeris, feel free to open a pull request or discussion on GitHub!

📚 Citing eyeris

If you use the eyeris package in your research, please cite it!

Run the following in R to get the citation:

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},
#>   }

Clone this wiki locally