🔎 The Glass Box Function
Our glassbox function – in contrast to a “black box”
function where you run it and obtain a result with little-to-no idea as
to how you got from raw input to cleaned output – provides a highly
opinionated prescription of steps and starting parameters we
(computational neuroscientists and signal processing experts at the
Stanford Memory Lab) strongly believe any pupillometry researcher should
use as their default starting point when preprocessing any set of
pupillometry data.
We recommend starting out with the glassbox
function to (ideally) reduce the probability of
accidental mishaps when “reimplementing” the individual steps
that make up the preprocessing pipeline both within and
across projects.
Moreover, the glassbox function provides an
“interactive” framework where you can evaluate the consequences of the
parameters used within each step on your data in real time, therefore
facilitating a fairly easy-to-use workflow for parameter optimization on
your particular dataset.
In essence, this interactive process takes each opinionated step and allows you to see both pre and post timeseries plots so you can adjust parameters stepwise until you are satisfied with your choices (and their consequences on your pupil timeseries data).
Installing eyeris
If you haven’t already installed the eyeris package:
Loading Your Raw Data
For this demo, we’ll use our built in demo dataset, which contains a handful of trials from an associative memory task recorded in our lab.
Running the Fully-Automated Pipeline
Here, we use the example data along with the default prescribed parameters and pipeline recipe:
# Run an automated pipeline with no real-time inspection of parameters
output <- eyeris::glassbox(demo_data)
#> âś” [ OK ] - Running eyeris::load_asc()
#> âś” [ OK ] - Running eyeris::deblink()
#> âś” [ OK ] - Running eyeris::detransient()
#> âś” [ OK ] - Running eyeris::interpolate()
#> âś” [ OK ] - Running eyeris::lpfilt()
#> ! [ SKIP ] - Skipping eyeris::detrend()
#> âś” [ OK ] - Running eyeris::zscore()
# Preview first and last steps of the pipeline
plot(
output,
steps = c(1, 5),
preview_window = c(0, max(output$timeseries$block_1$time_secs)),
seed = 0
)
#> ! Plotting block 1 from possible blocks: 1
Running the Pipeline Interactively
Overriding the Default Parameters
To override the default glassbox parameters directly
within the glassbox() function call, you need to pass in
the appropriate parameter(s) for each pipeline step to
glassbox().
Example
output <- eyeris::glassbox(
demo_data,
interactive_preview = FALSE, # TRUE to visualize each step in real-time
deblink = list(extend = 40),
lpfilt = list(plot_freqz = FALSE)
)
#> âś” [ OK ] - Running eyeris::load_asc()
#> âś” [ OK ] - Running eyeris::deblink()
#> âś” [ OK ] - Running eyeris::detransient()
#> âś” [ OK ] - Running eyeris::interpolate()
#> âś” [ OK ] - Running eyeris::lpfilt()
#> ! [ SKIP ] - Skipping eyeris::detrend()
#> âś” [ OK ] - Running eyeris::zscore()Pipeline Steps with Overridable Parameters
eyeris::load_asc(): >blockeyeris::deblink(): >extendeyeris::detransient(): >n,mad_thresheyeris::lpfilt(): >wp,ws,rp,rs,plot_freqz
