eyeris (version 2.0.0)

load_asc: Load and parse SR Research EyeLink .asc files

Description

This function builds upon the eyelinker::read.asc() function to parse the messages and metadata within the EyeLink .asc file. After loading and additional processing, this function returns an S3 eyeris class for use in all subsequent eyeris pipeline steps and functions.

Usage

load_asc(file, block = "auto")

Value

An object of S3 class eyeris with the following attributes:

1. file: Path to the original .asc file.

2. timeseries: Dataframe of all raw timeseries data from the tracker.

3. events: Dataframe of all event messages and their timestamps.

4. blinks: Dataframe of all blink events.

5. info: Dataframe of various metadata parsed from the file header.

6. latest: eyeris variable for tracking pipeline run history.

Arguments

file

An SR Research EyeLink .asc file generated by the official EyeLink edf2asc command

block

Optional block number specification. The following are valid options:

• "auto" (default): Automatically handles multiple recording segments embedded within the same .asc file. We recommend using this default as this is likely the safer choice then assuming a single-block recording (unless you know what you're doing).

• NULL: Omits block column. Suitable for single-block recordings.

• Numeric value: Manually sets block number based on the value provided here.

Details

This function is automatically called by glassbox() by default. If needed, customize the parameters for load_asc by providing a parameter list.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

See Also

eyelinker::read.asc() which this function wraps.

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline.

Examples

demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  eyeris::glassbox(load_asc = list(block = 1))

# Other useful parameter configurations
## (1) Basic usage (no block column specified)
demo_data |>
  eyeris::load_asc()

## (2) Manual specification of block number
demo_data |>
  eyeris::load_asc(block = 3)

## (3) Auto-detect multiple recording segments embedded within the same file
##  (i.e., the default behavior)
demo_data |>
  eyeris::load_asc(block = "auto")

## (4) Omit block column
demo_data |>
  eyeris::load_asc(block = NULL)