Save out pupil timeseries data in a BIDS-like structure

This method provides a structured way to save out pupil data in a BIDS-like structure. The method saves out epoched data as well as the raw pupil timeseries, and formats the directory and filename structures based on the metadata you provide.

Usage

bidsify(
  eyeris,
  save_all = TRUE,
  epochs_list = NULL,
  merge_epochs = FALSE,
  bids_dir = NULL,
  participant_id = NULL,
  session_num = NULL,
  task_name = NULL,
  run_num = NULL,
  save_raw = TRUE,
  html_report = TRUE,
  pdf_report = FALSE,
  report_seed = 0,
  report_epoch_grouping_var_col = "matched_event"
)

Arguments

eyeris

An object of class eyeris dervived from load().

save_all

Logical flag indicating whether all epochs are to be saved or only a subset of them. Defaults to TRUE.

epochs_list

List of epochs to be saved. Defaults to NULL.

merge_epochs

Logical flag indicating whether epochs should be saved as one file or as separate files. Defaults to FLASE (no merge).

bids_dir

Base bids_directory.

participant_id

BIDS subject ID.

session_num

BIDS session ID.

task_name

BIDS task ID.

run_num

BIDS run ID.

save_raw

Logical flag indicating whether to save_raw pupil data in addition to epoched data. Defaults to TRUE.

html_report

Logical flag indicating whether to save out the eyeris preprocessing summary report as an HTML file. Defaults to TRUE.

pdf_report

Logical flag indicating whether to save out the eyeris preprocessing summary report as a PDF file. Note, a valid TeX distribution must already be installed. Defaults to FALSE.

report_seed

Random seed for the plots that will appear in the report. Defaults to 0. See plot() for a more detailed description.

report_epoch_grouping_var_col

String name of grouping column to use for epoch-by-epoch diagnostic plots in an interactive rendered HTML report. Column name must exist (i.e., be a custom grouping variable name set within the metadata template of your epoch() call). Defaults to "matched_event", which all epoched dataframes have as a valid column name. To disable these epoch-level diagnostic plots, set to NULL.

Details

In the future, we intend for this function to save out the data in an official BIDS format for eyetracking data (see the proposal currently under review here). At this time, however, this function instead takes a more BIDS-inspired approach to organizing the output files for preprocessed pupil data.

Examples

# Bleed around blink periods just long enough to remove majority of
#  deflections due to eyelid movements
if (FALSE) { # \dontrun{
system.file("extdata", "memory.asc", package = "eyeris") |>
  eyeris::load_asc() |>
  eyeris::deblink(extend = 50) |>
  eyeris::detransient() |>
  eyeris::interpolate() |>
  eyeris::lpfilt(plot_freqz = TRUE) |>
  eyeris::zscore() |>
  eyeris::epoch(
    events = "PROBE_{type}_{trial}",
    limits = c(-1, 1), # grab 1 second prior to and 1 second post event
    label = "prePostProbe" # custom epoch label name
  ) |>
  eyeris::bidsify(
    bids_dir = ".", # make bids dir in current directory
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    run_num = "01"
  )
} # }