# Usage

    library(eyelinkReader)

The main function is `read_edf()` that imports an EDF file (or throws an error, if EDF API is not installed). By default it will import all events and attempt to extract standard events: saccades, blinks, fixations, logged variables, etc.

    library(eyelinkReader)
    gaze <- read_edf('eyelink-recording.edf')

Events and individual event types are stored as tables inside the `eyelinkRecording` object with `trial` column identifying individual trials. Trial 0 correspond to events (e.g, `DISPLAY_COORDS` message, etc.) sent to the eye tracker before the first trial.

    View(gaze$saccades)

## Working with samples

To import samples, add `import_samples = TRUE` and, optionally, specify which sample attributes need to be imported, e.g., `sample_attributes = c('time', 'gx', 'gy')`. All attributes are imported if `sample_attributes` is not specified. See package and EDF API documentation for the full list of attribute names.

    # import samples with all attributes
    gaze <- read_edf('eyelink-recording.edf', import_samples = TRUE)

    # import samples with selected attributes
    gaze <- read_edf('eyelink-recording.edf',
                     import_samples = TRUE,
                     sample_attributes = c('time', 'gx', 'gy'))

You can convert makes samples cyclopean. In case of a binocular recording, a single column would represent an average between to eyes. E.g., \(gx = (gxL + gxR) / 2\). In case of a monocular recording, a single column will contain information for a recorded eye. This is particularly useful, if you have multiple monocular recordings but some for the right eye and some for the left.

    cyclopean_samples <- compute_cyclopean_samples(gaze$samples)

## Utility functions

The package includes various utility functions that need to be called separately. For example, to parse non-standard events: recorded areas of interest (`extract_AOIs`) and trigger events that help to time events (`extract_triggers`).

    gaze <- extract_AOIs(gaze)
    gaze <- extract_triggers(gaze)

or, tidyverse-style

    library(tidyverse)
    gaze <-
      read_edf('eyelink-recording.edf') %>%
      extract_AOIs() %>%
      extract_triggers()

Function `adjust_message_time()` alters time stamps of messages that are prefixed by a numeric offset that makes synchronization easier for e E-Prime / Presentation. I.e., a message `"-50 TARGET_ONSET"` that was sent at `105600` becomes a message `"TARGET_ONSET"` and its time stamp is `105550`.

    gaze <- adjust_message_time(gaze)