Skip to contents

Save out pupil timeseries data in a BIDS-like structure

Source: R/pipeline-bidsify.R
bidsify.Rd

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_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 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.

Value

Invisibly returns NULL. Called for its side effects.

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
# \donttest{
demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  eyeris::glassbox(deblink = list(extend = 50)) |>
  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
  )
#> ✔ [  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()
#> ℹ Epoching pupil data...
#> ℹ Block 1: found 10 matching events for PROBEtypetrial
#> ✔ Done!
#> ✔ Block 1: pupil data from 10 unique event messages extracted
#> ✔ Pupil epoching completed in 0.21 seconds
#> Warning: `run_num` is ignored when data contains multiple blocks.Blocks will be automatically numbered as runs.
#> ! '/tmp/RtmpToI0zH' already exists. Skipping creation...
#> ℹ '/tmp/RtmpToI0zH/derivatives' does not exist. Creating...
#> ✔ BIDS directory successfully created at: '/tmp/RtmpToI0zH/derivatives'
#> ℹ '/tmp/RtmpToI0zH/derivatives/sub-001' does not exist. Creating...
#> ✔ BIDS directory successfully created at: '/tmp/RtmpToI0zH/derivatives/sub-001'
#> ℹ '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01' does not exist. Creating...
#> ✔ BIDS directory successfully created at: '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01'
#> ℹ '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/eye' does not exist. Creating...
#> ✔ BIDS directory successfully created at: '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/eye'
#> ℹ Writing run 01 epoched data to '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/eye/sub-001_ses-01_task-assocret_run-01_epoch-prePostProbe_desc-preproc_pupil.csv'...
#> ✔ Run 01 epoched data written to: '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/eye/sub-001_ses-01_task-assocret_run-01_epoch-prePostProbe_desc-preproc_pupil.csv'
#> ℹ Writing run 01 raw pupil timeseries to '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/eye/sub-001_ses-01_task-assocret_run-01_desc-timeseries_pupil.csv'...
#> ✔ Run 01 raw pupil timeseries written to: '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/eye/sub-001_ses-01_task-assocret_run-01_desc-timeseries_pupil.csv'
#> ℹ '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/source/figures' does not exist. Creating...
#> ✔ BIDS directory successfully created at: '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/source/figures'
#> ℹ '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/source/figures/run-01' does not exist. Creating...
#> ✔ BIDS directory successfully created at: '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/source/figures/run-01'
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! Plotting block 1 from possible blocks: 1
#> ! '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/source/figures/run-01' already exists. Skipping creation...
#> ℹ '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/source/figures/run-01/epoch_prePostProbe' does not exist. Creating...
#> ✔ BIDS directory successfully created at: '/tmp/RtmpToI0zH/derivatives/sub-001/ses-01/source/figures/run-01/epoch_prePostProbe'
#> 
#> 
#> processing file: sub-001_epoch-prePostProbe_run-01.Rmd
#> 1/3           
#> 2/3 [citation]
#> 3/3           
#> output file: sub-001_epoch-prePostProbe_run-01.knit.md
#> /opt/hostedtoolcache/pandoc/3.1.11/x64/pandoc +RTS -K512m -RTS sub-001_epoch-prePostProbe_run-01.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --output sub-001_epoch-prePostProbe_run-01.html --lua-filter /home/runner/work/_temp/Library/rmarkdown/rmarkdown/lua/pagebreak.lua --lua-filter /home/runner/work/_temp/Library/rmarkdown/rmarkdown/lua/latex-div.lua --embed-resources --standalone --variable bs3=TRUE --section-divs --template /home/runner/work/_temp/Library/rmarkdown/rmd/h/default.html --no-highlight --variable highlightjs=1 --variable theme=bootstrap --css /home/runner/work/_temp/Library/eyeris/rmarkdown/css/report.css --mathjax --variable 'mathjax-url=https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --include-in-header /tmp/RtmpToI0zH/rmarkdown-str1d262440777d.html 
#> 
#> Output created: sub-001_epoch-prePostProbe_run-01.html
#> 
#> 
#> processing file: sub-001.Rmd
#> 1/3           
#> 2/3 [citation]
#> 3/3           
#> output file: sub-001.knit.md
#> /opt/hostedtoolcache/pandoc/3.1.11/x64/pandoc +RTS -K512m -RTS sub-001.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --output sub-001.html --lua-filter /home/runner/work/_temp/Library/rmarkdown/rmarkdown/lua/pagebreak.lua --lua-filter /home/runner/work/_temp/Library/rmarkdown/rmarkdown/lua/latex-div.lua --embed-resources --standalone --variable bs3=TRUE --section-divs --template /home/runner/work/_temp/Library/rmarkdown/rmd/h/default.html --no-highlight --variable highlightjs=1 --variable theme=bootstrap --css /home/runner/work/_temp/Library/eyeris/rmarkdown/css/report.css --mathjax --variable 'mathjax-url=https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --include-in-header /tmp/RtmpToI0zH/rmarkdown-str1d26251ad559.html 
#> 
#> Output created: sub-001.html
# }