bidsify: 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 = TRUE,
  report_seed = 0,
  report_epoch_grouping_var_col = "matched_event",
  verbose = TRUE,
  pdf_report = deprecated()
)

Value

Invisibly returns NULL. Called for its side effects

Arguments

eyeris: An object of class eyeris derived from load_asc()
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 FALSE (no merge)
bids_dir: Base bids_directory. Defaults to NULL
participant_id: BIDS subject ID. Defaults to NULL
session_num: BIDS session ID. Defaults to NULL
task_name: BIDS task ID. Defaults to NULL
run_num: BIDS run ID. Optional override for the run number when there's only one block of data present in a given .asc file. This allows you to manually specify a run number (e.g., "03") instead of using the default block number in .asc files (1). This is especially useful if you have a single .asc file for a single run of a task and want your BIDSified derivatives to be labeled correctly. 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. Defaults to NULL (no override)
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 TRUE
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
pdf_report: (Deprecated) Use html_report = TRUE instead

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

Run this code

# Bleed around blink periods just long enough to remove majority of
#  deflections due to eyelid movements
# \donttest{
demo_data <- eyelink_asc_demo_dataset()

# example with unepoched data
demo_data |>
  eyeris::glassbox() |>
  eyeris::bidsify(
    bids_dir = tempdir(), # <- MAKE SURE TO UPDATE TO YOUR DESIRED LOCAL PATH
    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
  )

# example with epoched data
demo_data |>
  eyeris::glassbox() |>
  eyeris::epoch(
    events = "PROBE_{startstop}_{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(), # <- MAKE SURE TO UPDATE TO YOUR DESIRED LOCAL PATH
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    run_num = "01"
  )

# example with run_num for single block data
demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  eyeris::glassbox() |>
  eyeris::epoch(
    events = "PROBE_{startstop}_{trial}",
    limits = c(-1, 1),
    label = "prePostProbe"
  ) |>
  eyeris::bidsify(
    bids_dir = tempdir(),
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    run_num = "03" # override default run-01 (block_1) to use run-03 instead
  )
# }