Questions on arguments to the glassbox() function

[mh105]

In preparation for the preprint of the eyeris package, I have gone through the key glassbox() function . I have a few questions that may or may not lead to changes, so I'll just write them down here for @shawntz to review and consider.

1. I see that there seem to be the following two ways to use the eyeris package: [RESOLVED: SHAWN 4/24/2025] ✅

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

versus

output <- glassbox(
  rawdata,
  confirm = FALSE,
  deblink = list(extend = 40),
  lpfilt = list(plot_freqz = FALSE)
)

My understanding is that the primary difference between these two routes is that we don't get interactive preview plots and there are no verbose logging if we choose the first. Is this correct, or is there more to it?

If this is indeed the case, I think there might be programmatic elegance to have an "almost" one-to-one mapping between the declarative calls of eyeris functions (load_asc(), deblink(), etc.) to arguments to the glassbox() function.

The design I'm thinking is that your glassbox() function would have the header something very simple like this:

glassbox <- function(file,
                     interactive_preview = TRUE
                     preview_n = 3, preview_duration = 5,
                     preview_windows = NULL,
                     verbose = TRUE, ...) {

  # the default parameters
  params <- list(
    load_asc = list(block = "auto"),
    deblink = list(extend = 50),
    detransient = list(n = 16, mad_thresh = NULL),
    interpolate = TRUE
    lpfilt = list(wp = 4, ws = 8, rp = 1, rs = 35, plot_freqz = TRUE)
    detrend = FALSE
    zscore = TRUE
  )

In other words, everything you would have manually passed in a |> chain can be used as an argument to glassbox(). This should replace the needs for one-off flags like detrend_data or skip_detransient. Users will use arguments like glassbox(rawdata, detransient = FALSE, detrend = TRUE, ...) if they want the glassbox() to skip or do some of these steps.

I believe this design has the added benefit of having to learn the pipeline only once. Then users really only need to understand the individual steps and know that the glassbox() function is a nice wrapper that ties everything together, logs things, generates interactive previews, and so on. But they don't need to learn a new way to specifying settings.

In addition, overriding default parameters becomes intuitive as well: users will simply pass the sub-step in a |> chain as an argument into glassbox() and that will very intuitively override the settings.

What do you think?

2. Some argument naming suggestions: [RESOLVED: SHAWN 4/23/2025] ✅

• confirm -> interactive_preview: given the way to talk about this as interactive processing, it felt like it needs to have the word "interactive" in the argument keyword. ✅
• num_previews -> preview_n: to match the preview_duration naming convention. ✅
• preview_window -> preview_windows: I assume this could be an array of start/stop times? Is so then it should use plural as hint. ❌

3. Could you help explain a bit more what verbose = TRUE does? I think we say there are detailed logging messages but it wasn't clear to me if it just meant those print out messages in

#> [OK] - Running eyeris::load_asc()
#> [OK] - Running eyeris::deblink()
#> [OK] - Running eyeris::detransient()
#> [OK] - Running eyeris::interpolate()
#> [OK] - Running eyeris::lpfilt()
#> [OK] - Skipping eyeris::detrend()
#> [OK] - Running eyeris::zscore()

or if there is more. [RESOLVED: SHAWN 4/23/2025] ✅

Perhaps more importantly, in the current preprint draft we call this "logging messages". Are they actually getting logged somewhere if verbose = TRUE? For example, is there going to be like a xxx.log file that gets generated only if we set verbose to be TRUE? Either way is fine, I'm just trying to understand its behavior from a user's perspective. ❌

4. I noticed that the plot_freqz flag defaults to true for lpfilt(). Does that mean it will always generate a plot of the frequency response even when verbose is FALSE? Or perhaps I misunderstood the code. [RESOLVED: SHAWN 4/23/2025] ✅

5. Is the"extdata" flag in the system.file() call necessary? Or could we omit it? I assume all .asc files will be external data so is R unhappy if we don't specify it this way? I'm just trying to reduce the cognitive load of new things for users to remember / understand. [RESOLVED: SHAWN 4/23/2025] ✅

Again, I think the package is in a fantastic shape. These questions / potential modifications to the glassbox() function are just to make the experience even better for users, if you think they are relevant or beneficial. Let me know if my questions above make sense, and I'm of course happy to Zoom / discuss in person.