bidsify: Save out pupil timeseries data in a BIDS-like structure

In eyeris: Flexible, Extensible, & Reproducible Processing of Pupil Data

Save out pupil timeseries data in a BIDS-like structure

Description

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,
  merge_runs = FALSE,
  save_raw = TRUE,
  html_report = FALSE,
  pdf_report = FALSE,
  report_seed = 0,
  report_epoch_grouping_var_col = "matched_event",
  verbose = TRUE
)

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. For single files without blocks (i.e., runs), run_num specifies which run this file represents. However, for files with multiple recording blocks embedded within the same .asc file, this parameter is ignored and blocks are automatically numbered as runs (block 1 = run-01, block 2 = run-02, etc.) in the order they appeared/were recorded.
merge_runs	Logical flag indicating whether multiple runs (either from multiple recording blocks existing within the same .asc file (see above), or manually specified) should be combined into a single output file. When TRUE, adds a 'run' column to identify the source run. Defaults to FALSE (i.e., separate files per block/run – the standard BIDS-like-behavior).
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 FALSE.
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.
verbose	A flag to indicate whether to print detailed logging messages. Defaults to TRUE. Set to False to suppress messages about the current processing step and run silently.

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.

Value

Invisibly returns NULL. Called for its side effects.

Examples

# Bleed around blink periods just long enough to remove majority of
#  deflections due to eyelid movements

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 = tempdir(),
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    run_num = "01",
    save_raw = TRUE, # save out raw timeseries
    html_report = TRUE, # generate interactive report document
    report_seed = 0 # make randomly selected plot epochs reproducible
  )

eyeris documentation built on April 12, 2025, 2:05 a.m.