├── .Rbuildignore
├── .github
    ├── .gitignore
    └── workflows
    │   └── pkgdown.yaml
├── .gitignore
├── DESCRIPTION
├── NAMESPACE
├── NEWS.md
├── R
    ├── RcppExports.R
    ├── adjust_message_time.R
    ├── check_consistency_flag.R
    ├── check_logical_flag.R
    ├── check_string_parameter.R
    ├── check_that_compiled.R
    ├── compute_cyclopean_samples.R
    ├── convert_codes.R
    ├── data.R
    ├── extract_aois.R
    ├── extract_blinks.R
    ├── extract_display_coords.R
    ├── extract_fixations.R
    ├── extract_saccades.R
    ├── extract_triggers.R
    ├── extract_variables.R
    ├── eyelinkReader-classes.R
    ├── eyelinkReader-package.R
    ├── logical_index_for_sample_attributes.R
    ├── plot.R
    ├── print.R
    ├── read_edf.R
    ├── read_preamble.R
    └── zzz.R
├── README.md
├── _pkgdown.yml
├── data
    └── gaze.rda
├── eyelinkReader.Rproj
├── inst
    ├── WORDLIST
    ├── cpp
    │   └── edf_interface.cpp
    └── extdata
    │   └── example.edf
├── man
    ├── adjust_message_time.Rd
    ├── check_consistency_flag.Rd
    ├── check_logical_flag.Rd
    ├── check_string_parameter.Rd
    ├── check_that_compiled.Rd
    ├── compiled_library_status.Rd
    ├── compute_cyclopean_samples.Rd
    ├── convert_NAs.Rd
    ├── convert_header_codes.Rd
    ├── convert_recording_codes.Rd
    ├── dot-onAttach.Rd
    ├── dot-onLoad.Rd
    ├── extract_AOIs.Rd
    ├── extract_blinks.Rd
    ├── extract_display_coords.Rd
    ├── extract_fixations.Rd
    ├── extract_saccades.Rd
    ├── extract_triggers.Rd
    ├── extract_variables.Rd
    ├── eyelinkReader.Rd
    ├── eyelinkRecording-class.Rd
    ├── figures
    │   └── logo.svg
    ├── gaze.Rd
    ├── logical_index_for_sample_attributes.Rd
    ├── plot.eyelinkRecording.Rd
    ├── print.eyelinkRecording.Rd
    ├── read_edf.Rd
    ├── read_edf_file.Rd
    ├── read_preamble.Rd
    └── read_preamble_str.Rd
├── pkgdown
    └── favicon
    │   ├── apple-touch-icon.png
    │   ├── favicon-96x96.png
    │   ├── favicon.ico
    │   ├── favicon.svg
    │   ├── site.webmanifest
    │   ├── web-app-manifest-192x192.png
    │   └── web-app-manifest-512x512.png
├── src
    ├── .gitignore
    ├── Makevars
    ├── Makevars.win
    ├── RcppExports.cpp
    ├── compiled_library_status.cpp
    ├── convert_NAs.cpp
    ├── read_edf_file.cpp
    └── read_preamble_str.cpp
├── tests
    ├── testthat.R
    └── testthat
    │   ├── test-safety_checks.R
    │   └── test-sample-attributes.R
└── vignettes
    ├── .gitignore
    ├── installation.Rmd
    ├── plotting.Rmd
    └── usage.Rmd


/.Rbuildignore:
--------------------------------------------------------------------------------
1 | ^.*\.Rproj$
2 | ^\.Rproj\.user$
3 | ^_pkgdown\.yml$
4 | ^docs$
5 | ^pkgdown$
6 | ^\.github$
7 | eyelinkReader.svg
8 | 


--------------------------------------------------------------------------------
/.github/.gitignore:
--------------------------------------------------------------------------------
1 | *.html
2 | 


--------------------------------------------------------------------------------
/.github/workflows/pkgdown.yaml:
--------------------------------------------------------------------------------
 1 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
 2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 3 | on:
 4 |   push:
 5 |     branches: [main, master]
 6 |   pull_request:
 7 |   release:
 8 |     types: [published]
 9 |   workflow_dispatch:
10 | 
11 | name: pkgdown.yaml
12 | 
13 | permissions: read-all
14 | 
15 | jobs:
16 |   pkgdown:
17 |     runs-on: ubuntu-latest
18 |     # Only restrict concurrency for non-PR jobs
19 |     concurrency:
20 |       group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
21 |     env:
22 |       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
23 |     permissions:
24 |       contents: write
25 |     steps:
26 |       - uses: actions/checkout@v4
27 | 
28 |       - uses: r-lib/actions/setup-pandoc@v2
29 | 
30 |       - uses: r-lib/actions/setup-r@v2
31 |         with:
32 |           use-public-rspm: true
33 | 
34 |       - uses: r-lib/actions/setup-r-dependencies@v2
35 |         with:
36 |           extra-packages: any::pkgdown, local::.
37 |           needs: website
38 | 
39 |       - name: Build site
40 |         run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
41 |         shell: Rscript {0}
42 | 
43 |       - name: Deploy to GitHub pages 🚀
44 |         if: github.event_name != 'pull_request'
45 |         uses: JamesIves/github-pages-deploy-action@v4.5.0
46 |         with:
47 |           clean: false
48 |           branch: gh-pages
49 |           folder: docs
50 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .Rproj.user
2 | .Rhistory
3 | .RData
4 | .Ruserdata
5 | docs
6 | inst/doc
7 | 


--------------------------------------------------------------------------------
/DESCRIPTION:
--------------------------------------------------------------------------------
 1 | Package: eyelinkReader
 2 | Title: Import Gaze Data for EyeLink Eye Tracker
 3 | Version: 1.0.3
 4 | Date: 2024-10-08
 5 | Authors@R:
 6 |   person(given = "Alexander",
 7 |          family = "Pastukhov",
 8 |          role = c("aut", "cre"),
 9 |          email ="pastukhov.alexander@gmail.com",
10 |          comment = c(ORCID = "0000-0002-8738-8591"))
11 | Description: Import gaze data from  edf files generated by 
12 |   the SR Research <https://www.sr-research.com/> EyeLink eye tracker. Gaze data,
13 |   both recorded events and samples, is imported per trial. The package allows to extract
14 |   events of interest, such as saccades, blinks, etc. as well as
15 |   recorded variables and custom events (areas of interest, triggers) into separate tables.
16 |   The package requires EDF API library that can be obtained at <https://www.sr-research.com/support/>.
17 | License: GPL (>= 3)
18 | URL: https://github.com/alexander-pastukhov/eyelinkReader/,
19 |     https://alexander-pastukhov.github.io/eyelinkReader/
20 | BugReports: https://github.com/alexander-pastukhov/eyelinkReader/issues
21 | Depends:
22 |   R (>= 4.1.0),
23 |   RcppProgress,
24 |   rlang
25 | Encoding: UTF-8
26 | NeedsCompilation: yes
27 | VignetteBuilder:
28 |     knitr
29 | LazyData: true
30 | LinkingTo: Rcpp, RcppProgress
31 | Imports:
32 |   dplyr,
33 |   fs,
34 |   purrr,
35 |   Rcpp,
36 |   stringr,
37 |   tidyr,
38 |   methods,
39 |   ggplot2
40 | RoxygenNote: 7.3.2
41 | Roxygen: list(markdown = TRUE)
42 | SystemRequirements: GNU make
43 | Suggests: 
44 |     rmarkdown,
45 |     knitr,
46 |     testthat (>= 3.0.0)
47 | Config/testthat/edition: 3
48 | 


--------------------------------------------------------------------------------
/NAMESPACE:
--------------------------------------------------------------------------------
 1 | # Generated by roxygen2: do not edit by hand
 2 | 
 3 | S3method(adjust_message_time,data.frame)
 4 | S3method(adjust_message_time,eyelinkRecording)
 5 | S3method(compute_cyclopean_samples,data.frame)
 6 | S3method(compute_cyclopean_samples,eyelinkRecording)
 7 | S3method(extract_AOIs,data.frame)
 8 | S3method(extract_AOIs,eyelinkRecording)
 9 | S3method(extract_blinks,data.frame)
10 | S3method(extract_blinks,eyelinkRecording)
11 | S3method(extract_display_coords,data.frame)
12 | S3method(extract_display_coords,eyelinkRecording)
13 | S3method(extract_fixations,data.frame)
14 | S3method(extract_fixations,eyelinkRecording)
15 | S3method(extract_saccades,data.frame)
16 | S3method(extract_saccades,eyelinkRecording)
17 | S3method(extract_triggers,data.frame)
18 | S3method(extract_triggers,eyelinkRecording)
19 | S3method(extract_variables,data.frame)
20 | S3method(extract_variables,eyelinkRecording)
21 | S3method(plot,eyelinkRecording)
22 | S3method(print,eyelinkPreamble)
23 | S3method(print,eyelinkRecording)
24 | export(.onAttach)
25 | export(.onLoad)
26 | export(adjust_message_time)
27 | export(check_consistency_flag)
28 | export(check_logical_flag)
29 | export(check_string_parameter)
30 | export(check_that_compiled)
31 | export(compiled_library_status)
32 | export(compute_cyclopean_samples)
33 | export(convert_NAs)
34 | export(convert_header_codes)
35 | export(convert_recording_codes)
36 | export(extract_AOIs)
37 | export(extract_blinks)
38 | export(extract_display_coords)
39 | export(extract_fixations)
40 | export(extract_saccades)
41 | export(extract_triggers)
42 | export(extract_variables)
43 | export(logical_index_for_sample_attributes)
44 | export(read_edf)
45 | export(read_edf_file)
46 | export(read_preamble)
47 | export(read_preamble_str)
48 | import(Rcpp)
49 | import(RcppProgress)
50 | importFrom(Rcpp,evalCpp)
51 | importFrom(dplyr,"%>%")
52 | importFrom(dplyr,all_of)
53 | importFrom(dplyr,arrange)
54 | importFrom(dplyr,filter)
55 | importFrom(dplyr,mutate)
56 | importFrom(dplyr,mutate_if)
57 | importFrom(dplyr,select)
58 | importFrom(fs,file_exists)
59 | importFrom(ggplot2,aes_string)
60 | importFrom(ggplot2,coord_equal)
61 | importFrom(ggplot2,geom_point)
62 | importFrom(ggplot2,geom_segment)
63 | importFrom(ggplot2,ggplot)
64 | importFrom(ggplot2,labs)
65 | importFrom(ggplot2,scale_x_continuous)
66 | importFrom(ggplot2,scale_y_reverse)
67 | importFrom(methods,hasArg)
68 | importFrom(methods,is)
69 | importFrom(purrr,map_chr)
70 | importFrom(purrr,map_int)
71 | importFrom(rlang,.data)
72 | importFrom(stringr,str_detect)
73 | importFrom(stringr,str_extract)
74 | importFrom(stringr,str_remove)
75 | importFrom(stringr,str_remove_all)
76 | importFrom(stringr,str_replace)
77 | importFrom(stringr,str_split)
78 | importFrom(tidyr,separate)
79 | useDynLib(eyelinkReader)
80 | 


--------------------------------------------------------------------------------
/NEWS.md:
--------------------------------------------------------------------------------
 1 | # eyelinkReader 1.0.0
 2 | * Initial CRAN Release
 3 | 
 4 | # eyelinkReader 1.0.1
 5 | ## Enhancements
 6 | * Optional GRUB for plotting
 7 | 
 8 | ## Bug Fixes
 9 | * Internal documentation structure changes.
10 | 
11 | # eyelinkReader 1.0.2
12 | ## Bug Fixes
13 | * Correct path for compilation on Mac
14 | * Bug fix in plot function
15 | * UTF-8 encoding for event message strings
16 | * AOI parsing function now allows for labels with white spaces
17 | 
18 | # eyelinkReader 1.0.3
19 | ## Bug Fixes
20 | * Format string for the error message
21 | 


--------------------------------------------------------------------------------
/R/RcppExports.R:
--------------------------------------------------------------------------------
 1 | # Generated by using Rcpp::compileAttributes() -> do not edit by hand
 2 | # Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
 3 | 
 4 | #' @title Status of compiled library
 5 | #' @description Return status of compiled library
 6 | #' @return logical
 7 | #' @export
 8 | #' @examples
 9 | #' compiled_library_status()
10 | compiled_library_status <- function() {
11 |     .Call('_eyelinkReader_compiled_library_status', PACKAGE = 'eyelinkReader')
12 | }
13 | 
14 | #' @title Convert -32767 (missing info) to NA
15 | #' @description Converts all -32767 (smallest INT16  value indicating missing info) to NA.
16 | #' You don't need to call this function directly, as it is automatically evoked within
17 | #' \code{\link{read_edf}} function.
18 | #' @param original_frame data.frame to be processed
19 | #' @return processed data.frame
20 | #' @export
21 | #' @examples
22 | #' \donttest{
23 | #'   data(gaze)
24 | #'   gaze$samples <- convert_NAs(gaze$samples)
25 | #' }
26 | convert_NAs <- function(original_frame) {
27 |     .Call('_eyelinkReader_convert_NAs', PACKAGE = 'eyelinkReader', original_frame)
28 | }
29 | 
30 | #' @title Internal function that reads EDF file
31 | #' @description Reads EDF file into a list that contains events, samples, and recordings.
32 | #' DO NOT call this function directly. Instead, use read_edf function that implements
33 | #' parameter checks and additional postprocessing.
34 | #' @param filename full name of the EDF file
35 | #' @param consistency consistency check control (for the time stamps of the start
36 | #' and end events, etc). 0, no consistency check. 1, check consistency and report.
37 | #' 2, check consistency and fix.
38 | #' @param import_events load/skip loading events.
39 | #' @param import_recordings load/skip loading recordings.
40 | #' @param import_samples load/skip loading of samples.
41 | #' @param sample_attr_flag boolean vector that indicates which sample fields are to be stored
42 | #' @param start_marker_string event that marks trial start. Defaults to "TRIALID", if empty.
43 | #' @param end_marker_string event that marks trial end
44 | #' @param verbose whether to show progressbar and report number of trials
45 | #' @export
46 | #' @keywords internal
47 | #' @return contents of the EDF file. Please see read_edf for details.
48 | read_edf_file <- function(filename, consistency, import_events, import_recordings, import_samples, sample_attr_flag, start_marker_string, end_marker_string, verbose) {
49 |     .Call('_eyelinkReader_read_edf_file', PACKAGE = 'eyelinkReader', filename, consistency, import_events, import_recordings, import_samples, sample_attr_flag, start_marker_string, end_marker_string, verbose)
50 | }
51 | 
52 | #' @title Reads preamble of the EDF file as a single string.
53 | #' @description Reads preamble of the EDF file as a single string.
54 | #' Please, do not use this function directly. Instead, call \code{\link{read_preamble}} function
55 | #' that provides a more consistent interface.
56 | #' @return string with the preamble
57 | #' @export
58 | #' @keywords internal
59 | #' @examples
60 | #' \donttest{
61 | #' if (eyelinkReader::compiled_library_status()) {
62 | #'   read_preamble(system.file("extdata", "example.edf", package = "eyelinkReader"))
63 | #' }
64 | #' }
65 | read_preamble_str <- function(filename) {
66 |     .Call('_eyelinkReader_read_preamble_str', PACKAGE = 'eyelinkReader', filename)
67 | }
68 | 
69 | 


--------------------------------------------------------------------------------
/R/adjust_message_time.R:
--------------------------------------------------------------------------------
 1 | #' Adjusts message time based on embedded text offset
 2 | #'
 3 | #' Uses text in the message to adjust its time. E.g.,
 4 | #' for a message \code{"-50 TARGET_ONSET"} that was sent at \code{105600}
 5 | #' the actual onset occurred 50 milliseconds earlier (\code{-50}). The function
 6 | #' adjusts the event timing and removes the timing offset information from
 7 | #' the message. I.e., the example message becomes \code{"TARGET_ONSET"} and
 8 | #' its time become \code{105550}.
 9 | #'
10 | #' @param object An \code{\link{eyelinkRecording}} object or data.frame with events,
11 | #' i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.
12 | #' @param prefix String with a regular expression that defines the offset.
13 | #' Defaults to \code{"^[-+]?[:digit:]+[:space:]+"} (a string starts with a positive
14 | #' or negative integer offset followed by a white space and the rest of the message).
15 | #'
16 | #' @return Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
17 | #' with \emph{modified} \code{events} slot or a data.frame with offset-adjusted events.
18 | #' @export
19 | #'
20 | #' @examples
21 | #' data(gaze)
22 | #'
23 | #' # by passing events table
24 | #' adjusted_events <- adjust_message_time(gaze$events)
25 | #'
26 | #' # by passing the recording
27 | #' gaze <- adjust_message_time(gaze)
28 | 
29 | adjust_message_time <- function(object, prefix) { UseMethod("adjust_message_time") }
30 | 
31 | #' @rdname adjust_message_time
32 | #' @importFrom stringr str_detect str_extract str_replace
33 | #' @importFrom dplyr arrange
34 | #' @export
35 | adjust_message_time.data.frame <- function(object, prefix = "^[-+]?[:digit:]+[:space:]+"){
36 |   # find messages that need adjusting
37 |   need_adjusting <- which(stringr::str_detect(object$message, prefix))
38 | 
39 |   if (length(need_adjusting) > 0) {
40 |     # get temporal offset as a number
41 |     offset <- as.numeric(str_extract(object$message[need_adjusting], prefix))
42 | 
43 |     # remove offset from the message
44 |     object$message[need_adjusting] <- stringr::str_replace(object$message[need_adjusting], prefix, "")
45 | 
46 |     # adjust time
47 |     object$sttime[need_adjusting] <- object$sttime[need_adjusting] + offset
48 |     object$sttime_rel[need_adjusting] <- object$sttime_rel[need_adjusting] + offset
49 | 
50 |     # sort events based on adjusted time
51 |     object <- dplyr::arrange(object, .data$sttime)
52 |   }
53 | 
54 |   object
55 | }
56 | 
57 | #' @rdname adjust_message_time
58 | #' @export
59 | adjust_message_time.eyelinkRecording <-  function(object, prefix = "^[-+]?[:digit:]+[:space:]+"){
60 |   # check that events are in the recording at all
61 |   if (!("events" %in% names(object))) {
62 |     warning("No events in an eyelinkRecording object, nothing to do.")
63 |     return(object)
64 |   }
65 | 
66 |   # modify in place
67 |   object$events <- adjust_message_time(object$events, prefix)
68 |   object
69 | }
70 | 


--------------------------------------------------------------------------------
/R/check_consistency_flag.R:
--------------------------------------------------------------------------------
 1 | #' Checks consistency flag, stops if invalid, returns code if valid.
 2 | #'
 3 | #' @param consistency consistency check control for the time stamps of the start
 4 | #' and end events, etc. Could be \code{'no consistency check'} (0),
 5 | #' \code{'check consistency and report'} (1), \code{'check consistency and fix'} (2).
 6 | #'
 7 | #' @return integer index
 8 | #' @export
 9 | #' @keywords internal
10 | #'
11 | #' @examples
12 | #' check_consistency_flag('no consistency check')
13 | check_consistency_flag <- function(consistency) {
14 |   # converting consistency to integer constant that C-code understands
15 |   requested_consistency <-  factor(consistency,
16 |                                    levels= c('no consistency check', 'check consistency and report', 'check consistency and fix'))
17 |   if (length(requested_consistency) < 1) stop("Null value for consistency flag")
18 |   if (length(requested_consistency) > 1) stop("Multiple values for consistency flag")
19 |   if (is.na(requested_consistency)) stop(sprintf('Bad consistency check value "%s".', consistency))
20 | 
21 |   # zero-based index
22 |    as.numeric(requested_consistency) - 1
23 | }
24 | 


--------------------------------------------------------------------------------
/R/check_logical_flag.R:
--------------------------------------------------------------------------------
 1 | #' Checks for validity of a logical flag, stops if not valid
 2 | #'
 3 | #' @param logical_flag Logical scalar
 4 | #'
 5 | #' @return logical, value of the logical_flag
 6 | #' @export
 7 | #' @keywords internal
 8 | #'
 9 | #' @examples
10 | #' import_samples <- TRUE
11 | #' check_logical_flag(import_samples)
12 | check_logical_flag <- function(logical_flag){
13 |   param_name <- as.character(match.call()[[2]])
14 |   if (length(logical_flag) != 1) stop(sprintf("%s must be a scalar logical value", param_name))
15 |   if (is.null(logical_flag)) stop(sprintf("%s must be a scalar logical value, not NULL", param_name))
16 |   if (!is.logical(logical_flag)) stop(sprintf("%s must be a scalar logical value", param_name))
17 |   if (is.na(logical_flag)) stop(sprintf("%s must be a scalar logical value, NA not allowed", param_name))
18 | 
19 |   logical_flag
20 | }
21 | 


--------------------------------------------------------------------------------
/R/check_string_parameter.R:
--------------------------------------------------------------------------------
 1 | #' Checks for validity of a string parameter, stops if not valid
 2 | #'
 3 | #' @param string_parameter String scalar
 4 | #'
 5 | #' @return character, value of the string_parameter
 6 | #' @export
 7 | #' @keywords internal
 8 | #'
 9 | #' @examples
10 | #' start_marker <- "TRIALID"
11 | #' check_string_parameter(start_marker)
12 | check_string_parameter <- function(string_parameter){
13 |   param_name <- as.character(match.call()[[2]])
14 |   if (length(string_parameter) != 1) stop(sprintf("%s must be a scalar string value", param_name))
15 |   if (is.null(string_parameter)) stop(sprintf("%s must be a scalar logical value, not NULL", param_name))
16 |   if (!is.character(string_parameter)) stop(sprintf("%s must be a scalar string value", param_name))
17 |   if (nchar(string_parameter) == 0) warning(sprintf("Empty string for %s parameter", param_name))
18 |   if (is.na(string_parameter)) stop(sprintf("%s must be a scalar logical value, NA not allowed", param_name))
19 | 
20 |   string_parameter
21 | }
22 | 


--------------------------------------------------------------------------------
/R/check_that_compiled.R:
--------------------------------------------------------------------------------
 1 | #' Checks whether EDF API library was present and
 2 | #' interface was successfully be compiled
 3 | #'
 4 | #' @param fail_loudly logical, whether lack of compiled library means
 5 | #' error (\code{TRUE}), just warning (\code{FALSE}), or silent (\code{NA},
 6 | #' for test use only).
 7 | #'
 8 | #' @export
 9 | #' @return No return value. Stops the computation, if compiled interface to EDF API in missing.
10 | #' @keywords internal
11 | #'
12 | #' @examples
13 | #' check_that_compiled(fail_loudly = FALSE)
14 | check_that_compiled <- function(fail_loudly = TRUE){
15 |   # try to compile
16 |   if (!eyelinkReader::compiled_library_status() && !is.na(fail_loudly)) {
17 |     if (fail_loudly) {
18 |       stop("Failed to compile interface to EDF API, function will return NULL. Please read the manual for further details.")
19 |     } else {
20 |       warning("Failed to compile interface to EDF API, function will return NULL. Please read the manual for further details.")
21 |     }
22 |   }
23 | 
24 |   eyelinkReader::compiled_library_status()
25 | }
26 | 


--------------------------------------------------------------------------------
/R/compute_cyclopean_samples.R:
--------------------------------------------------------------------------------
 1 | #' Computes cyclopean samples by averaging over binocular data
 2 | #'
 3 | #' Computes cyclopean samples by averaging over binocular recorded properties
 4 | #' such as \code{pxL}/\code{pxR}, \code{pyL}/\code{pyR}, \code{hxL}/\code{hxR},
 5 | #' etc. Uses function specified via \code{fun}
 6 | #' parameter to compute the average with \code{na.rm = TRUE} option.
 7 | #' In case of a monocular recording or when the information from one eye missing,
 8 | #' uses information from one eye only, ignoring the other column.
 9 | #' In both binocular and monocular recording cases, simplifies column names
10 | #' so that \code{pxL} and/or \code{pxR} are replaced
11 | #' with a single column \code{px}, \code{pyL}/\code{pyR} with \code{py}, etc.
12 | #'
13 | #' @param object Either an \code{\link{eyelinkRecording}} object or data.frame with samples,
14 | #' i.e., \code{samples} slot of the \code{\link{eyelinkRecording}} object.
15 | #' @param fun Function used to average across eyes, defaults to \code{\link{mean}}.
16 | #'
17 | #' @return Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
18 | #' with \emph{modified} \code{samples} slot or a data.frame with cyclopean samples.
19 | 
20 | #' @export
21 | #'
22 | #' @examples
23 | #' data(gaze)
24 | #'
25 | #' # by passing samples table
26 | #' cyclopean_samples <- compute_cyclopean_samples(gaze$samples)
27 | #'
28 | #' # storing cyclopean samples as a separate table in recording
29 | #' gaze$cyclopean_samples <- compute_cyclopean_samples(gaze$samples)
30 | #'
31 | #' # by passing the recording, cyclopean samples replace original ones
32 | #' gaze <- compute_cyclopean_samples(gaze)
33 | compute_cyclopean_samples <- function(object, fun = mean) { UseMethod("compute_cyclopean_samples") }
34 | 
35 | 
36 | #' @rdname compute_cyclopean_samples
37 | #' @export
38 | #' @importFrom dplyr %>% select all_of mutate_if
39 | #' @importFrom tidyr separate
40 | #' @importFrom stringr str_detect str_remove
41 | #' @importFrom rlang .data
42 | compute_cyclopean_samples.data.frame <- function(object, fun = mean) {
43 |   # figuring out columns that we need to compute the mean over
44 |   i_eye_specific_column <- stringr::str_detect(names(object), "[L|R]$")
45 |   eye_specific_columns <- names(object)[i_eye_specific_column]
46 |   joint_eye_columns <- unique(stringr::str_remove(eye_specific_columns, "[L|R]$"))
47 |   resulting_columns <- unique(stringr::str_remove(names(object), "[L|R]$"))
48 | 
49 |   # averaging over eye-specific columns
50 |   for(current_column in joint_eye_columns){
51 |     eye_components <- eye_specific_columns[stringr::str_detect(eye_specific_columns, sprintf("^%s[L|R]$", current_column))]
52 |     if (identical(fun, mean)) {
53 |       # rowMeans are MUCH faster than applying mean to margin row
54 |       object[[current_column]] <- rowMeans(object[, eye_components], na.rm = TRUE)
55 |     } else {
56 |       # universal solution for everything else
57 |       object[[current_column]] <- apply(object[, eye_components], MARGIN = 1, FUN = fun, na.rm = TRUE)
58 |     }
59 |   }
60 | 
61 |   object %>%
62 |     # drop original eye-specific columns
63 |     select(all_of(resulting_columns)) %>%
64 | 
65 |     # convert NaN to NA because mean(c(NA, NA), na.rm = TRUE)) returns NaN, not NA
66 |     mutate_if(is.numeric, ~ifelse(is.nan(.x), NA, .x))
67 | }
68 | 
69 | 
70 | #' @rdname compute_cyclopean_samples
71 | #' @export
72 | compute_cyclopean_samples.eyelinkRecording <- function(object, fun = mean) {
73 |   # check that samples are in the recording at all
74 |   if (!("samples" %in% names(object))) {
75 |     stop("No samples in an eyelinkRecording object.")
76 |   }
77 | 
78 |   # modify in place
79 |   object$samples <- compute_cyclopean_samples(object$samples, fun)
80 |   object
81 | }
82 | 


--------------------------------------------------------------------------------
/R/convert_codes.R:
--------------------------------------------------------------------------------
 1 | #' Converts integer constants in trial headers to factor with explicit labels
 2 | #'
 3 | #' @description Converts integer constants in trial headers to factor with explicit labels.
 4 | #' Please refer to EDF API manual for further details.
 5 | #' @param trial_headers data.frame that contains trial headers.
 6 | #'
 7 | #' @return a modified trial_headers table
 8 | #' @keywords internal
 9 | #' @export
10 | convert_header_codes <- function(trial_headers){
11 |   trial_headers$rec_state <- factor(trial_headers$rec_state, levels = c(0, 1), labels= c('END', 'START'))
12 |   trial_headers$rec_record_type <- factor(trial_headers$rec_record_type, levels = c(1, 2, 3), labels= c('SAMPLES', 'EVENTS', 'SAMPLES and EVENTS'))
13 |   trial_headers$rec_pupil_type <- factor(trial_headers$rec_pupil_type, levels = c(0, 1), labels= c('AREA', 'DIAMETER'))
14 |   trial_headers$rec_recording_mode <- factor(trial_headers$rec_recording_mode, levels = c(0, 1), labels= c('PUPIL', 'CR'))
15 |   # trial_headers$rec_pos_type <- factor(trial_headers$rec_pos_type, levels = c(0, 1, 2), labels= c('GAZE', 'HREF', 'RAW'))
16 |   trial_headers$rec_eye <- factor(trial_headers$rec_eye, levels = c(1, 2, 3), labels= c('LEFT', 'RIGHT', 'LEFT and RIGHT'))
17 | 
18 |   return (trial_headers);
19 | }
20 | 
21 | #' Converts integer constants in recordings to factor with explicit labels
22 | #'
23 | #' @description Converts integer constants in trial recordings information to factor with explicit labels.
24 | #' Please refer to EDF API manual for further details.
25 | #' @param trial_recordings data.frame that contains trial recordings.
26 | #'
27 | #' @return a modified trial_recordings table
28 | #' @keywords internal
29 | #' @export
30 | convert_recording_codes <- function(trial_recordings){
31 |   trial_recordingsstate <- factor(trial_recordings$state, levels = c(0, 1), labels= c('END', 'START'))
32 |   trial_recordings$record_type <- factor(trial_recordings$record_type, levels = c(1, 2, 3), labels= c('SAMPLES', 'EVENTS', 'SAMPLES and EVENTS'))
33 |   trial_recordings$pupil_type <- factor(trial_recordings$pupil_type, levels = c(0, 1), labels= c('AREA', 'DIAMETER'))
34 |   trial_recordings$recording_mode <- factor(trial_recordings$recording_mode, levels = c(0, 1), labels= c('PUPIL', 'CR'))
35 |   # trial_recordings$pos_type <- factor(trial_recordings$pos_type, levels = c(0, 1, 2), labels= c('GAZE', 'HREF', 'RAW'))
36 |   trial_recordings$eye <- factor(trial_recordings$eye, levels = c(1, 2, 3), labels= c('LEFT', 'RIGHT', 'LEFT and RIGHT'))
37 | 
38 |   return (trial_recordings);
39 | }
40 | 


--------------------------------------------------------------------------------
/R/data.R:
--------------------------------------------------------------------------------
 1 | #' Imported example.edf, events and samples
 2 | #'
 3 | #' An \code{\link{eyelinkRecording}} for _example.edf_ via
 4 | #' \code{read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"), import_samples = TRUE)}).
 5 | #' Contains all extracted events including triggers, areas of interested, and display coordinates. The original
 6 | #' recording consist of ten trials with a participant fixating on a target that jumps to a new location after
 7 | #' one second and stays on the screen for another second. Includes all relevant events.
 8 | #'
 9 | #' See \code{\link{eyelinkRecording}} for details.
10 | #' @seealso \code{\link{eyelinkRecording}}, \code{\link{read_edf}}
11 | "gaze"
12 | 


--------------------------------------------------------------------------------
/R/extract_aois.R:
--------------------------------------------------------------------------------
 1 | #' Extracts rectangular areas of interest (AOI)
 2 | #'
 3 | #' @description Extracts rectangular areas of interest (AOI),
 4 | #' as defined by \code{"!V IAREA RECTANGLE"} command.
 5 | #' Specifically, we expect it to be in format
 6 | #' \code{!V IAREA RECTANGLE <index> <left> <top> <right> <bottom> <label>},
 7 | #' where \code{<label>} is a string label and all other variables are integer.
 8 | #' Please note that due to a non-standard nature of this function \strong{is not} called
 9 | #' during the \code{\link{read_edf}} call and you need to call it separately.
10 | #'
11 | #' @param object Either an \code{\link{eyelinkRecording}} object or data.frame with events,
12 | #' i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.
13 | #'
14 | #' @return Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
15 | #' with an additional \code{AOIs} slot or a data.frame with AOIs' information. See
16 | #' \code{\link{eyelinkRecording}} for details.
17 | #' @export
18 | #'
19 | #' @examples
20 | #' data(gaze)
21 | #'
22 | #' # by passing the recording
23 | #' gaze <- extract_AOIs(gaze)
24 | #'
25 | #' # by passing events table
26 | #' AOIs <- extract_AOIs(gaze$events)
27 | extract_AOIs <- function(object) { UseMethod("extract_AOIs") }
28 | 
29 | #' @rdname extract_AOIs
30 | #' @export
31 | #' @importFrom dplyr %>% filter select mutate
32 | #' @importFrom tidyr separate
33 | #' @importFrom stringr str_remove_all str_split
34 | #' @importFrom rlang .data
35 | #' @importFrom purrr map_chr map_int
36 | extract_AOIs.data.frame <- function(object){
37 |   object %>%
38 |     dplyr::filter(.data$type == "MESSAGEEVENT", stringr::str_starts(.data$message, "!V IAREA RECTANGLE")) |>
39 |     dplyr::select("trial", "sttime", "sttime_rel", "message") |>
40 |     dplyr::mutate(message = stringr::str_remove_all(.data$message, "!V IAREA RECTANGLE "),
41 |                   chunks = stringr::str_split(.data$message, " "),
42 |                   index = purrr::map_int(.data$chunks, ~as.integer(.[1])),
43 |                   label = purrr::map_chr(.data$chunks, ~paste0(.[6:length(.)], collapse = " ")),
44 |                   left = purrr::map_int(.data$chunks, ~as.integer(.[2])),
45 |                   top = purrr::map_int(.data$chunks, ~as.integer(.[3])),
46 |                   right = purrr::map_int(.data$chunks, ~as.integer(.[4])),
47 |                   bottom = purrr::map_int(.data$chunks, ~as.integer(.[5]))) |>
48 |     dplyr::select(-"chunks", -"message")
49 | }
50 | 
51 | #' @rdname extract_AOIs
52 | #' @export
53 | extract_AOIs.eyelinkRecording <- function(object){
54 |   object$AOIs <- extract_AOIs(object$events)
55 |   object
56 | }
57 | 
58 | 


--------------------------------------------------------------------------------
/R/extract_blinks.R:
--------------------------------------------------------------------------------
 1 | #' Extract blinks
 2 | #'
 3 | #' @description Extracts blinks from the \code{events} table of the \code{\link{eyelinkRecording}} object.. Normally,
 4 | #' you don't need to call this function yourself,
 5 | #' as it is called during the \code{\link{read_edf}} with default settings
 6 | #' (\emph{e.g.}, \code{import_blinks = TRUE}).
 7 | #'
 8 | #' @param object Either an \code{\link{eyelinkRecording}} object or data.frame with events,
 9 | #' i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.
10 | #'
11 | #' @return Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
12 | #' with an additional \code{blinks} slot or a data.frame with blinks' information. See
13 | #' \code{\link{eyelinkRecording}} for details.
14 | #'
15 | #' @seealso read_edf, eyelinkRecording
16 | #' @export
17 | #' @examples
18 | #' data(gaze)
19 | #'
20 | #' # by passing the recording
21 | #' gaze <- extract_blinks(gaze)
22 | #'
23 | #' # by passing events table
24 | #' blinks <- extract_blinks(gaze$events)
25 | extract_blinks <- function(object) { UseMethod("extract_blinks") }
26 | 
27 | 
28 | #' @rdname extract_blinks
29 | #' @export
30 | #' @importFrom rlang .data
31 | #' @importFrom dplyr %>% filter mutate select
32 | extract_blinks.data.frame <- function(object){
33 |   object %>%
34 |     dplyr::filter(.data$type == 'ENDBLINK') %>%
35 |     dplyr::mutate(duration = .data$entime - .data$sttime) %>%
36 |     dplyr::select(c("trial", "sttime", "entime", "sttime_rel", "entime_rel", "duration", "eye"))
37 | }
38 | 
39 | #' @rdname extract_blinks
40 | #' @export
41 | extract_blinks.eyelinkRecording <- function(object){
42 |   object$blinks <- extract_blinks(object$events)
43 |   object
44 | }
45 | 


--------------------------------------------------------------------------------
/R/extract_display_coords.R:
--------------------------------------------------------------------------------
 1 | #' Extract display coordinates from an event message
 2 | #'
 3 | #' @description Extracts display coordinates from a message that adheres to a
 4 | #' \code{<message_prefix> <label>} format. Please note that this function called
 5 | #' during the \code{\link{read_edf}} call with \code{silent = TRUE}. If \code{display_coords}
 6 | #' are missing from the \code{\link{eyelinkRecording}}, run this method to see the warnings.
 7 | #'
 8 | #' @param object Either an \code{\link{eyelinkRecording}} object or data.frame with events,
 9 | #' i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.
10 | #' @param message_prefix Beginning of the message string that identifies the DISPLAY_COORDS message.
11 | #' Defaults to \code{"DISPLAY_COORDS"}.
12 | #' @param silent Whether to suppress a warning when DISPLAY_COORDS message is missing. Default to \code{FALSE}.
13 | #'
14 | #' @return A \code{\link{eyelinkRecording}} object with an additional \code{display_coords} slot (if that was \code{object} type),
15 | #' Either a four element numeric vector with display coordinates, or \code{NULL} if \code{object} was an \code{events} table of
16 | #' \code{\link{eyelinkRecording}} object. See \code{\link{eyelinkRecording}} for details.
17 | #'
18 | #' @seealso read_edf, eyelinkRecording
19 | #' @export
20 | #'
21 | #' @examples
22 | #' data(gaze)
23 | #'
24 | #' # by passing the recording
25 | #' gaze <- extract_display_coords(gaze)
26 | #'
27 | #' # by passing events table
28 | #' display_coords <- extract_display_coords(gaze$events)
29 | extract_display_coords <- function(object, message_prefix = "DISPLAY_COORDS", silent = FALSE) { UseMethod("extract_display_coords") }
30 | 
31 | 
32 | #' @rdname extract_display_coords
33 | #' @export
34 | #' @importFrom dplyr %>% filter
35 | #' @importFrom rlang .data
36 | 
37 | extract_display_coords.data.frame <- function(object, message_prefix = "DISPLAY_COORDS", silent = FALSE) {
38 |   if (!is.null(object)){
39 |     display_coord_msg <- dplyr::filter(object, .data$trial == 0, startsWith(.data$message, message_prefix))
40 | 
41 |     if (nrow(display_coord_msg) == 0) {
42 |       if (!silent) warning("No DISPLAY_COORDS message found.")
43 |       return(NULL)
44 |     } else if (nrow(display_coord_msg) > 1) {
45 |       if (!silent) warning("Multiple DISPLAY_COORDS messages found. Using the first one.")
46 |       display_coord_msg <- display_coord_msg[1, ]
47 |     }
48 | 
49 |     # decomposing message into components
50 |     message_components <- unlist(strsplit(trimws(display_coord_msg$message[1]), split = " "))
51 |     if (length(message_components) != 5) {
52 |       if (!silent) warning("Invalid DISPLAY_COORDS.")
53 |       return(NULL)
54 |     }
55 |     as.numeric(message_components[-1])
56 |   }
57 | }
58 | 
59 | #' @rdname extract_display_coords
60 | #' @export
61 | extract_display_coords.eyelinkRecording <- function(object, message_prefix = "DISPLAY_COORDS", silent = FALSE){
62 |   object$display_coords <- extract_display_coords(object$events, message_prefix, silent)
63 |   object
64 | }
65 | 


--------------------------------------------------------------------------------
/R/extract_fixations.R:
--------------------------------------------------------------------------------
 1 | #' Extract fixations
 2 | #'
 3 | #' @description Extracts fixations from the \code{events} table of the \code{\link{eyelinkRecording}} object.
 4 | #' Normally, you don't need to call this function yourself,
 5 | #' as it is called during the \code{\link{read_edf}} with default settings
 6 | #' (\emph{e.g.}, \code{import_fixations = TRUE}).
 7 | #'
 8 | #' @param object Either an \code{\link{eyelinkRecording}} object or data.frame with events,
 9 | #' i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.
10 | #'
11 | #' @return Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
12 | #' with an additional \code{fixations} slot or a data.frame with fixations' information. See
13 | #' \code{\link{eyelinkRecording}} for details.
14 | #'
15 | #' @seealso read_edf, eyelinkRecording
16 | #' @export
17 | #'
18 | #' @examples
19 | #' data(gaze)
20 | #'
21 | #' # by passing the recording
22 | #' gaze <- extract_fixations(gaze)
23 | #'
24 | #' # by passing events table
25 | #' fixations <- extract_fixations(gaze$events)
26 | extract_fixations <- function(object) { UseMethod("extract_fixations") }
27 | 
28 | 
29 | #' @rdname extract_fixations
30 | #' @export
31 | #' @importFrom rlang .data
32 | #' @importFrom dplyr %>% filter mutate select
33 | extract_fixations.data.frame <- function(object){
34 |   object %>%
35 |     dplyr::filter(.data$type == 'ENDFIX') %>%
36 |     dplyr::mutate(duration = .data$entime - .data$sttime) %>%
37 |     dplyr::select(-c("time", "type", "read", "status", "flags", "input", "buttons", "parsedby", "message"))
38 | }
39 | 
40 | #' @rdname extract_fixations
41 | #' @export
42 | extract_fixations.eyelinkRecording <- function(object){
43 |   object$fixations <- extract_fixations(object$events)
44 |   object
45 | }
46 | 
47 | 


--------------------------------------------------------------------------------
/R/extract_saccades.R:
--------------------------------------------------------------------------------
 1 | #' Extract saccades from recorded events
 2 | #'
 3 | #' @description Extract saccades from the \code{events} table of the \code{\link{eyelinkRecording}} object.
 4 | #' Normally, you don't need to call this function yourself,
 5 | #' as it is called during the \code{\link{read_edf}} with default
 6 | #' settings (\emph{e.g.}, \code{import_saccades = TRUE}).
 7 | #'
 8 | #' @param object Either an \code{\link{eyelinkRecording}} object or data.frame with events,
 9 | #' i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.
10 | #'
11 | #' @return Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
12 | #' with an additional \code{saccades} slot or a data.frame with saccades' information. See
13 | #' \code{\link{eyelinkRecording}} for details.
14 | #' @seealso read_edf, eyelinkRecording
15 | #'
16 | #' @export
17 | #'
18 | #' @examples
19 | #' data(gaze)
20 | #'
21 | #' # by passing the recording
22 | #' gaze <- extract_saccades(gaze)
23 | #'
24 | #' # by passing events table
25 | #' saccades <- extract_saccades(gaze$events)
26 | extract_saccades <- function(object) { UseMethod("extract_saccades") }
27 | 
28 | #' @rdname extract_saccades
29 | #' @export
30 | #' @importFrom dplyr %>% filter mutate select
31 | #' @importFrom rlang .data
32 | extract_saccades.data.frame <- function(object){
33 |   object %>%
34 |     dplyr::filter(.data$type == 'ENDSACC') %>%
35 |     dplyr::mutate(duration = .data$entime - .data$sttime) %>%
36 |     dplyr::select(-c("time", "type", "read", "status", "flags", "input", "buttons", "parsedby", "message"))
37 | }
38 | 
39 | 
40 | #' @rdname extract_saccades
41 | #' @export
42 | extract_saccades.eyelinkRecording <- function(object){
43 |   object$saccades <- extract_saccades(object$events)
44 |   object
45 | }
46 | 
47 | 


--------------------------------------------------------------------------------
/R/extract_triggers.R:
--------------------------------------------------------------------------------
 1 | #' Extract triggers, a custom message type
 2 | #'
 3 | #' @description Extracts trigger events, messages that adhere to a
 4 | #' \code{<message_prefix> <label>} format. Their purpose is to identify the time
 5 | #' instance of specific interest.
 6 | #' Please note that due to a non-standard nature of this function \strong{is not} called
 7 | #' during the \code{\link{read_edf}} call and you need to call it separately.
 8 | #'
 9 | #' @param object Either an \code{\link{eyelinkRecording}} object or data.frame with events,
10 | #' i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.
11 | #' @param message_prefix Beginning of the message string that identifies trigger messages.
12 | #' Defaults to \code{"TRIGGER"}.
13 | #'
14 | #' @return Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
15 | #' with an additional \code{triggers} slot or a data.frame with triggers' information. See
16 | #' \code{\link{eyelinkRecording}} for details.
17 | #'
18 | #' @seealso read_edf, eyelinkRecording
19 | #' @export
20 | #'
21 | #' @examples
22 | #' data(gaze)
23 | #'
24 | #' # by passing the recording
25 | #' gaze <- extract_triggers(gaze)
26 | #'
27 | #' # by passing events table
28 | #' triggers <- extract_triggers(gaze$events)
29 | #'
30 | #' # with an explicit message prefix
31 | #' triggers <- extract_triggers(gaze$events, "TRIGGER")
32 | extract_triggers <- function(object, message_prefix = "TRIGGER") { UseMethod("extract_triggers") }
33 | 
34 | 
35 | #' @rdname extract_triggers
36 | #' @export
37 | #' @importFrom dplyr %>% filter mutate select
38 | #' @importFrom rlang .data
39 | extract_triggers.data.frame <- function(object, message_prefix = "TRIGGER"){
40 |   # Extracts key events: my own custom set of messages, not part of the EDF API!
41 |   # Looks for events coded as 'KEY_EVENT <message>'
42 |   # Returns trial, key event id (<message>), and timing information
43 | 
44 |   object %>%
45 |     dplyr::filter(grepl(paste0('^', message_prefix), message)) %>%
46 |     dplyr::mutate(label = trimws(gsub('TRIGGER', '', .data$message))) %>%
47 |     dplyr::select(c("trial", "sttime", "sttime_rel", "label"))
48 | }
49 | 
50 | #' @rdname extract_triggers
51 | #' @export
52 | extract_triggers.eyelinkRecording <- function(object, message_prefix = "TRIGGER"){
53 |   object$triggers <- extract_triggers(object$events, message_prefix)
54 |   object
55 | }
56 | 
57 | 


--------------------------------------------------------------------------------
/R/extract_variables.R:
--------------------------------------------------------------------------------
 1 | #' Extract variables
 2 | #'
 3 | #' @description Extracts variables from the \code{events} table of the \code{\link{eyelinkRecording}} object.
 4 | #' Normally, you don't need to call this function yourself,
 5 | #' as it is called during the \code{\link{read_edf}} with default settings
 6 | #' (\emph{e.g.}, \code{import_variables = TRUE}).
 7 | #'
 8 | #' @param object Either an \code{\link{eyelinkRecording}} object or data.frame with events,
 9 | #' i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.
10 | #'
11 | #' @return Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
12 | #' with an additional \code{variables} slot or a data.frame with variables' information. See
13 | #' \code{\link{eyelinkRecording}} for details.
14 | #' @seealso read_edf, eyelinkRecording
15 | #' @export
16 | #'
17 | #' @examples
18 | #' data(gaze)
19 | #'
20 | #' # by passing the recording
21 | #' gaze <- extract_variables(gaze)
22 | #'
23 | #' # by passing events table
24 | #' variables <- extract_variables(gaze$events)
25 | extract_variables <- function(object) { UseMethod("extract_variables") }
26 | 
27 | 
28 | #' @rdname extract_variables
29 | #' @export
30 | #' @importFrom dplyr %>% filter mutate select
31 | #' @importFrom tidyr separate
32 | extract_variables.data.frame <- function(object){
33 |   object %>%
34 |     dplyr::filter(grepl('TRIAL_VAR', message)) %>%
35 |     tidyr::separate(.data$message, c('header', 'assignment'), sep='TRIAL_VAR', remove=FALSE) %>%
36 |     dplyr::mutate(assignment = gsub('=', ' ', .data$assignment)) %>%
37 |     dplyr::mutate(assignment2 = sub(' ', "=", trimws(.data$assignment))) %>%
38 |     tidyr::separate(.data$assignment2, c('variable', 'value'), sep='=', remove=FALSE) %>%
39 |     dplyr::mutate(variable = trimws(.data$variable),
40 |                   value = trimws(.data$value)) %>%
41 |     dplyr::select(c("trial", "sttime", "sttime_rel", "variable", "value"))
42 | }
43 | 
44 | #' @rdname extract_variables
45 | #' @export
46 | extract_variables.eyelinkRecording <- function(object){
47 |   object$variables <- extract_variables(object$events)
48 |   object
49 | }
50 | 
51 | 


--------------------------------------------------------------------------------
/R/eyelinkReader-classes.R:
--------------------------------------------------------------------------------
  1 | #' Class \code{eyelinkRecording}.
  2 | #'
  3 | #' S3 class containing information imported from an edf-file.
  4 | #'
  5 | #' @name eyelinkRecording-class
  6 | #' @aliases eyelinkRecording
  7 | #' @docType class
  8 | #'
  9 | #' @details
 10 | #' See \code{methods(class = "eyelinkRecording")} for an overview of available methods.
 11 | #'
 12 | #' @slot preamble A preamble of the recording, see also \code{\link{read_preamble}}.
 13 | #' @slot events Events table which is a collection of all \code{FEVENT} imported from the EDF file. See description below.
 14 | #' @slot samples Samples table  which is a collection of all \code{FSAMPLE} imported from the EDF file. See description below.
 15 | #' @slot headers Headers of the individual trials, see description below.
 16 | #' @slot recordings Individual recording start/end information, see description below.
 17 | #' @slot display_coords Recorded screen coordinates (if recorded), see \code{\link{extract_display_coords}}.
 18 | #' @slot saccades Saccades extracted from \code{events}, see description below and \code{\link{extract_saccades}}.
 19 | #' @slot fixations Fixations extracted from \code{events}, see description below and \code{\link{extract_fixations}}.
 20 | #' @slot blinks Blinks extracted from \code{events}, see description below and \code{\link{extract_blinks}}.
 21 | #' @slot variables Recorded variables extracted from \code{events}, see description below and \code{\link{extract_variables}}.
 22 | #' @slot triggers Events messages that adhere to a \code{TRIGGER <label>} format.
 23 | #'   This is a \bold{non-standard message} that the package author uses to mark events like onsets or offsets,
 24 | #'   similar to how it is done in M/EEG. See description below and \code{\link{extract_triggers}}.
 25 | #' @slot AOIs Areas of interest events. See description below and \code{\link{extract_AOIs}}.
 26 | #'
 27 | #' @section Events:
 28 | #' Events table which is a collection of all \code{FEVENT} imported from the EDF file.
 29 | #' Column descriptions were copied directly  from the \emph{EDF access C API manual}.
 30 | #' Please refer to that manual for further details. Additional non-standard fields are marked in bold.
 31 | #'
 32 | #' * \strong{\code{trial}} Trial index, starts at 1.
 33 | #' * \code{time} Time of event.
 34 | #' * \code{type} Event type.
 35 | #' * \code{read} Flags which items were included.
 36 | #' * \code{sttime} Start time of the event.
 37 | #' * \code{entime} End time of the event.
 38 | #' * \strong{\code{sttime_rel}} Start time of the event, relative to the start time of the trial.
 39 | #' * \strong{\code{entime_rel}} End time of the event, relative to the start time of the trial.
 40 | #' * \code{hstx}, \code{hsty} Head reference starting points.
 41 | #' * \code{gstx}, \code{gsty} Gaze starting points.
 42 | #' * \code{sta} Pupil size at start.
 43 | #' * \code{henx}, \code{heny} Headref ending points.
 44 | #' * \code{genx}, \code{geny} Gaze ending points.
 45 | #' * \code{ena} Pupil size at end.
 46 | #' * \code{havx}, \code{havy} Headref averages.
 47 | #' * \code{gavx}, \code{gavy} Gaze averages.
 48 | #' * \code{ava} Average pupil size.
 49 | #' * \code{avel} Accumulated average velocity.
 50 | #' * \code{pvel} Accumulated peak velocity.
 51 | #' * \code{svel} Start velocity.
 52 | #' * \code{evel} End velocity.
 53 | #' * \code{supd_x}, \code{supd_y} Start units-per-degree.
 54 | #' * \code{eupd_x}, \code{eupd_y} End units-per-degree.
 55 | #' * \code{eye} Either \code{'LEFT'} (0) or \code{'RIGHT'} (1).
 56 | #' * \code{status} Error, warning flags.
 57 | #' * \code{flags} Flags to indicate contents.
 58 | #' * \code{input} Extra (input word).
 59 | #' * \code{buttons} Button state and changes.
 60 | #' * \code{parsedby} 7 bits of flags, PARSEDBY codes.
 61 | #' * \code{message} Any message string.
 62 | #'
 63 | #' @section Samples:
 64 | #' Samples table which is a collection of all \code{FSAMPLE} imported from the EDF file.
 65 | #' Please note that \code{\link{read_edf}} parameters determines which fields are imported.
 66 | #' Column descriptions were copied directly  from the \emph{EDF access C API manual}.
 67 | #' Please refer to that manual for further details. Suffixes \code{L} and \code{R} denote left and right eye.
 68 | #' Non-standard additional fields are marked in bold.
 69 | #' * \strong{\code{trial}} Trial index, starts at 1.
 70 | #' * \strong{\code{eye}} \code{'LEFT'} (0), \code{'RIGHT'} (1), or \code{'BINOCULAR'} (2).
 71 | #' * \code{time} Time of sample.
 72 | #' * \strong{\code{time_rel}} Time relative to the start of the trial.
 73 | #' * \code{pxL}, \code{pxR}, \code{pyL}, \code{pyR} Pupil coordinates.
 74 | #' * \code{hxL}, \code{hxR}, \code{hyL}, \code{hyR} Headref coordinates.
 75 | #' * \code{paL}, \code{paR} Pupil size or area.
 76 | #' * \code{gxL}, \code{gxR}, \code{gyL}, \code{gyR} Screen gaze coordinates.
 77 | #' * \code{rx}, \code{ry} Screen pixels per degree.
 78 | #' * \code{gxvelL}, \code{gxvelR}, \code{gyvelL}, \code{gyvelR} Gaze velocity.
 79 | #' * \code{hxvelL}, \code{hxvelR}, \code{hyvelL}, \code{hyvelR} Headref velocity.
 80 | #' * \code{rxvelL}, \code{rxvelR}, \code{ryvelL}, \code{ryvelR} Raw velocity.
 81 | #' * \code{fgxvelL}, \code{fgxvelR}, \code{fgyvelL}, \code{fgyvelR} Fast gaze velocity.
 82 | #' * \code{fhxvelL}, \code{fhxvelR}, \code{fhyvelL}, \code{fhyvelR} Fast headref velocity.
 83 | #' * \code{frxvelL}, \code{frxvelR}, \code{fryvelL}, \code{fryvelR} Fast raw velocity.
 84 | #' * \code{hdata_1} -\code{hdata_8} Head-tracker data (not pre-scaled). Each column correspond to a single element of the \code{INT16 FSAMPLE::hdata[8]}.
 85 | #' * \code{flags} Flags to indicate contents.
 86 | #' * \code{input} Extra (input word).
 87 | #' * \code{buttons} Button state & changes.
 88 | #' * \code{htype} Head-tracker data type (0=none).
 89 | #' * \code{errors} Process error flags.
 90 | #'
 91 | #' @section Headers:
 92 | #' Trial headers table which is a collection of all \code{TRIAL} structures imported from the EDF file.
 93 | #' Column descriptions were copied directly  from the \emph{EDF access C API manual}.
 94 | #' Please refer to that manual for further details.
 95 | #' All fields of the \code{RECORDINGS} structure are prefixed with \code{rec_}.
 96 | #' Non-standard additional fields are marked in bold.
 97 | #' * \strong{\code{trial}} Trial index.
 98 | #' * \code{duration} Duration of the trial.
 99 | #' * \code{starttime} Start time of the trial.
100 | #' * \code{endtime} End time of the trial.
101 | #' * \code{rec_time} Start time or end time.
102 | #' * \code{rec_sample rate} Sample rate in Hz: 250, 500, 1000 or 2000.
103 | #' * \code{rec_eflags} Extra information about events.
104 | #' * \code{rec_sflags} Extra information about samples.
105 | #' * \code{rec_state} \code{'START'} (2) or \code{'END'} (1).
106 | #' * \code{rec_record_type} \code{'SAMPLES'} (1), \code{'EVENTS'} (2), or \code{'SAMPLES and EVENTS'} (3).
107 | #' * \code{rec_pupil_type} \code{'AREA'} (0) or \code{'DIAMETER'} (1).
108 | #' * \code{rec_recording_mode} \code{'PUPIL'} (0) or \code{'CR'} (1).
109 | #' * \code{rec_filter_type} 1, 2, or 3.
110 | #' * \code{rec_pos_type} Should be \code{'GAZE'} (0), \code{'HREF'} (1) or \code{'RAW'}, but currently this column is kept as numeric, since observed values do not match the declared constants.
111 | #' * \code{rec_eye} \code{'LEFT'} (1), \code{'RIGHT'} (2) or \code{'LEFT and RIGHT'} (3).
112 | #'
113 | #' @section Recordings:
114 | #' Recordings table which is a collection of all \code{RECORDING} structures imported from the EDF file.
115 | #' Column descriptions were copied directly  from the \emph{EDF access C API manual}.
116 | #' Please refer to that manual for further details. Non-standard additional fields are marked in bold.
117 | #' * \strong{\code{trial}} Trial index.
118 | #' * \code{time} Start time or end time.
119 | #' * \code{sample rate} Sample rate in Hz: 250, 500, 1000 or 2000.
120 | #' * \code{eflags} Extra information about events.
121 | #' * \code{sflags} Extra information about samples.
122 | #' * \code{state} \code{'START'} (2) or \code{'END'} (1).
123 | #' * \code{record_type} \code{'SAMPLES'} (1), \code{'EVENTS'} (2), or \code{'SAMPLES and EVENTS'} (3).
124 | #' * \code{pupil_type} \code{'AREA'} (0) or \code{'DIAMETER'} (1).
125 | #' * \code{recording_mode} \code{'PUPIL'} (0) or \code{'CR'} (1).
126 | #' * \code{filter_type} 1, 2, or 3.
127 | #' * \code{pos_type} Should be \code{'GAZE'} (0), \code{'HREF'} (1) or \code{'RAW'}, but currently this column is kept as numeric, since observed values do not match the declared constants.
128 | #' * \code{eye} \code{'LEFT'} (1), \code{'RIGHT'} (2) or \code{'LEFT and RIGHT'} (3).
129 | #'
130 | #' @section Saccades and Fixations:
131 | #' Saccades and fixations extracted from the \code{events}, tables have the same structure.
132 | #' Column descriptions were copied directly  from the \emph{EDF access C API manual}.
133 | #' Please refer to that manual for further details. Non-standard additional fields are marked in bold.
134 | #' * \strong{\code{trial}} Trial index.
135 | #' * \code{sttime} Start time.
136 | #' * \code{entime} End time.
137 | #' * \strong{\code{sttime_rel}} Start time, relative to the start time of the trial.
138 | #' * \strong{\code{entime_rel}} End time, relative to the start time of the trial.
139 | #' * \strong{\code{duration}} Duration.
140 | #' * \code{hstx}, \code{hsty} Head reference starting points.
141 | #' * \code{gstx}, \code{gsty} Gaze starting points.
142 | #' * \code{sta} Pupil size at start.
143 | #' * \code{henx}, \code{heny} Headref ending points.
144 | #' * \code{genx}, \code{geny} Gaze ending points.
145 | #' * \code{ena} Pupil size at end.
146 | #' * \code{havx}, \code{havy} Headref averages.
147 | #' * \code{gavx}, \code{gavy} Gaze averages.
148 | #' * \code{ava} Average pupil size.
149 | #' * \code{avel} Accumulated average velocity.
150 | #' * \code{pvel} Accumulated peak velocity.
151 | #' * \code{svel} Start velocity.
152 | #' * \code{evel} End velocity.
153 | #' * \code{supd_x}, \code{supd_y} Start units-per-degree.
154 | #' * \code{eupd_x}, \code{eupd_y} End units-per-degree.
155 | #' * \code{eye} Either \code{'LEFT'} (1) or \code{'RIGHT'} (2).
156 | #'
157 | #' @section Blinks:
158 | #' Blinks extracted from the \code{events} table. Column descriptions were copied directly from the \emph{EDF access C API manual}.
159 | #' Please refer to that manual for further details. Non-standard additional fields are marked in bold.
160 | #' * \strong{\code{trial}} Trial index.
161 | #' * \code{sttime} Start time.
162 | #' * \code{entime} End time.
163 | #' * \strong{\code{sttime_rel}} Start time, relative to the start time of the trial.
164 | #' * \strong{\code{entime_rel}} End time, relative to the start time of the trial.
165 | #' * \strong{\code{duration}} Duration.
166 | #' * \code{eye} Either \code{'LEFT'} (1) or \code{'RIGHT'} (2).
167 | #'
168 | #' @section Variables:
169 | #' User recorded variables extracted from message events with a \code{'TRIAL_VAR'} prefix.
170 | #' Original format can be either \code{'TRIAL_VAR <name> <value>'} or \code{'TRIAL_VAR <name>=<value>'}.
171 | #' The \code{<name>} cannot contain spaces or \code{'='} sign.
172 | #' White spaces are trimmed for both \code{<name>} and \code{<value>}.
173 | #' * \code{trial} Trial index.
174 | #' * \code{sttime} Start time.
175 | #' * \code{sttime_rel} Start time, relative to the start time of the trial.
176 | #' * \code{variable} Variable name, the \code{<name>} part of the event message.
177 | #' * \code{value} Variable value, the \code{<value>} part of the event message.
178 | #'
179 | #' @section Trigger events:
180 | #' Events messages that adhere to a \code{TRIGGER <label>} format.
181 | #' This is a \strong{non-standard message} that the package author uses to mark events like onsets or offsets,
182 | #' similar to how it is done in M/EEG.
183 | #' * \code{trial} Trial index.
184 | #' * \code{sttime} Start time.
185 | #' * \code{sttime_rel} Start time, relative to the start time of the trial.
186 | #' * \code{label} \emph{label} part of the message, can contain white spaces.
187 | #'
188 | #' @section AOIs:
189 | #' Rectangular areas of interest (AOI), as defined by "!V IAREA RECTANGLE" command.
190 | #' Specifically, they are expected to be in format
191 | #' \code{!V IAREA RECTANGLE <index> <left> <top> <right> <bottom> <label>}.
192 | #' where \code{<label>} is a string label and all other variables are integer.
193 | #'
194 | #' * \code{trial} Trial index.
195 | #' * \code{sttime} Start time.
196 | #' * \code{sttime_rel} Start time, relative to the start time of the trial.
197 | #' * \code{index} AOI index.
198 | #' * \code{left}, \code{top}, \code{right}, \code{bottom} AOI coordinates.
199 | #' * \code{label} AOI label.
200 | #'
201 | #' @seealso
202 | #'   \code{\link{read_edf}}, \code{\link{extract_saccades}}, \code{\link{extract_fixations}}, \code{\link{extract_blinks}}, \code{\link{extract_triggers}}, \code{\link{extract_display_coords}}, \code{\link{extract_AOIs}}
203 | NULL
204 | 


--------------------------------------------------------------------------------
/R/eyelinkReader-package.R:
--------------------------------------------------------------------------------
 1 | ## usethis namespace: start
 2 | #' @description Imports gaze data recorded by a SR Research EyeLink eye tracker from an EDF file.
 3 | #' Includes options to import events and/or recorded samples and extract
 4 | #' individual events such as saccades, fixations, blinks, and recorded variables.
 5 | #'
 6 | #' @import Rcpp
 7 | #' @import RcppProgress
 8 | #' @importFrom Rcpp evalCpp
 9 | #' @useDynLib eyelinkReader
10 | #' @name eyelinkReader
11 | ## usethis namespace: end
12 | "_PACKAGE"
13 | 


--------------------------------------------------------------------------------
/R/logical_index_for_sample_attributes.R:
--------------------------------------------------------------------------------
 1 | #' Checks validity of sample attribute vector and returns logical indexes.
 2 | #'
 3 | #' @param import_samples logical, whether importing was requested.
 4 | #' @param sample_attributes character vector with names of attributes.
 5 | #'
 6 | #' @return logical vector
 7 | #' @export
 8 | #' @keywords internal
 9 | #'
10 | #' @examples
11 | #' logical_index_for_sample_attributes(TRUE, c('time', 'gx', 'gy'))
12 | logical_index_for_sample_attributes <- function(import_samples, sample_attributes){
13 |   sample_attr_labels <- c('time', 'px', 'py', 'hx', 'hy', 'pa',
14 |                           'gx', 'gy', 'rx', 'ry',
15 |                           'gxvel', 'gyvel', 'hxvel', 'hyvel', 'rxvel', 'ryvel',
16 |                           'fgxvel', 'fgyvel', 'fhxvel', 'fhyvel', 'frxvel', 'fryvel',
17 |                           'hdata', 'flags', 'input', 'buttons', 'htype', 'errors')
18 |   # checking for validity
19 |   check_logical_flag(import_samples)
20 | 
21 |   # definitely no import, neither a logical flag nor attribute names
22 |   if ((!import_samples) && is.null(sample_attributes)) {
23 |     return(rep(FALSE, times = length(sample_attr_labels)))
24 |   }
25 | 
26 |   # logical import flag but no specific attribute listed -> all of them
27 |   if (is.null(sample_attributes)){
28 |     return(rep(TRUE, times = length(sample_attr_labels)))
29 |   }
30 | 
31 |   # some attributes, check that all names are valid
32 |   if (!all(sample_attributes %in% sample_attr_labels)) stop("Invalid sample attribute names.")
33 |   if (length(sample_attributes %in% sample_attr_labels) == 0) stop("Empty sample attribute names vector.")
34 | 
35 |   # logical indexing
36 |   sample_attr_flag <- rep(FALSE, times = length(sample_attr_labels))
37 |   sample_attr_flag[match(sample_attributes, sample_attr_labels)] <- TRUE
38 |   return(sample_attr_flag)
39 | }
40 | 


--------------------------------------------------------------------------------
/R/plot.R:
--------------------------------------------------------------------------------
  1 | #' Plot fixations and saccades for a set of trials
  2 | #'
  3 | #' This is only a basic plotting utility intended primarily
  4 | #' for a quick visual check. Please refer to companion vignette on plotting
  5 | #' for details about geoms and implementing your own custom plotting routine.
  6 | #'
  7 | #' @param x \code{\link{eyelinkRecording}} object
  8 | #' @param trial Trials to be plotted, could be a scalar index,
  9 | #' a vector of indexes, or \code{NULL} (all trials). Defaults to \code{1}.
 10 | #' @param show_fixations logical, whether to draw fixation as circles. Defaults to \code{TRUE}.
 11 | #' @param fixation_size_property Which fixation property is used as circle aesthetics. Defaults to \code{"duration"}.
 12 | #' @param size_legend An optional legend title, defaults to \code{"Fixation duration [ms]"}
 13 | #' if \code{fixation_size_property} is \code{"duration"} and to \code{NA} otherwise. In the latter case, the legend
 14 | #' title is unmodified (i.e., determined by ggplot).
 15 | #' @param show_saccades logical, whether to draw saccades as line segments. Defaults to \code{TRUE}.
 16 | #' @param saccade_color_property Which saccade property is used as color aesthetics. Defaults to \code{"sttime_rel"}
 17 | #' (onset time relative to the trial start).
 18 | #' @param color_legend An optional legend title, defaults to \code{"Saccade onset [ms]"}
 19 | #' if \code{saccade_color_property} is \code{"sttime_rel"} and to \code{NA} otherwise. In the latter case, the legend
 20 | #' title is unmodified (i.e., determined by ggplot).
 21 | #' @param background_grobs ggplot2 graphic objects add to the plot \emph{before} plotting data.
 22 | #' @param ... Addition parameters (unused)
 23 | #'
 24 | #' @return ggplot object
 25 | #' @export
 26 | #' @importFrom ggplot2 ggplot coord_equal scale_x_continuous scale_y_reverse geom_point labs geom_segment aes_string
 27 | #' @importFrom methods hasArg
 28 | #'
 29 | #' @examples
 30 | #' data(gaze)
 31 | #'
 32 | #' # fixations and saccades for the first trial
 33 | #' plot(gaze)
 34 | #'
 35 | #' # fixations for the all trials
 36 | #' plot(gaze, trial = NULL, show_saccades = FALSE)
 37 | #'
 38 | #' # saccades for the first two trials
 39 | #' plot(gaze, trial = 1:2, show_fixations = FALSE)
 40 | #'
 41 | #' # color codes duration of a saccade
 42 | #' plot(gaze, saccade_color_property = "duration")
 43 | 
 44 | plot.eyelinkRecording <- function(x,
 45 |                                   trial = 1,
 46 |                                   show_fixations = TRUE,
 47 |                                   fixation_size_property = "duration",
 48 |                                   size_legend = ifelse(fixation_size_property == "duration", "Fixation duration [ms]", NA),
 49 |                                   show_saccades = TRUE,
 50 |                                   saccade_color_property = "sttime_rel",
 51 |                                   color_legend = ifelse(saccade_color_property == "sttime_rel", "Saccade onset [ms]", NA),
 52 |                                   background_grobs = NULL,
 53 |                                   ...){
 54 |   # empty plot with equally scaled x- and y-axes
 55 |   the_plot <-
 56 |     ggplot() +
 57 |     coord_equal(expand=FALSE) +
 58 |     background_grobs
 59 | 
 60 |   # setting limits based on display coordinated (if available)
 61 |   if ("display_coords" %in% names(x)) {
 62 |     the_plot <-
 63 |       the_plot +
 64 |       scale_x_continuous(name = "x", limits = x$display_coords[c(1, 3)]) +
 65 |       scale_y_reverse(name = "y", limits = x$display_coords[c(4, 2)])
 66 |   }
 67 | 
 68 |   # adding fixations
 69 |   if (show_fixations & "fixations" %in% names(x)) {
 70 |     if (is.null(trial)) {
 71 |       fixations <- x$fixations
 72 |     } else {
 73 |       fixations <- x$fixations[x$fixations$trial %in% trial, ]
 74 |     }
 75 |     the_plot <- the_plot + geom_point(data=fixations, aes_string(x = "gavx", y = "gavy", size = fixation_size_property), alpha=0.3)
 76 | 
 77 |     if (!is.null(fixation_size_property) & !is.na(size_legend)) {
 78 |       the_plot <- the_plot + labs(size = size_legend)
 79 |     }
 80 |   }
 81 | 
 82 |   # adding saccades
 83 |   if (show_saccades & "saccades" %in% names(x)) {
 84 |     if (is.null(trial)) {
 85 |       saccades <- x$saccades
 86 |     } else {
 87 |       saccades <- x$saccades[x$saccades$trial %in% trial, ]
 88 |     }
 89 |     the_plot <-
 90 |       the_plot +
 91 |       geom_segment(data=saccades, aes_string(x = "gstx", y = "gsty", xend = "genx", yend = "geny", color = saccade_color_property))
 92 | 
 93 |     if (!is.null(saccade_color_property) & !is.na(color_legend)) {
 94 |       the_plot <- the_plot + labs(color = color_legend)
 95 |     }
 96 |   }
 97 | 
 98 |   the_plot
 99 | }
100 | 


--------------------------------------------------------------------------------
/R/print.R:
--------------------------------------------------------------------------------
 1 | #' Print info about \code{\link{eyelinkRecording}}
 2 | #'
 3 | #' @param x \code{\link{eyelinkRecording}} object
 4 | #' @param ... Addition parameters (unused)
 5 | #' @return No return value, called for printing to console.
 6 | #' @export
 7 | #' @examples
 8 | #' \donttest{
 9 | #'   if (eyelinkReader::compiled_library_status()) {
10 | #'     recording <- read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"))
11 | #'     print(recording)
12 | #'   }
13 | #' }
14 | print.eyelinkRecording <- function(x, ...){
15 |   if (nrow(x$headers)==1){
16 |     trialsN <- 'one trial'
17 |   }
18 |   else{
19 |     trialsN <- sprintf('%d trials', nrow(x$headers))
20 |   }
21 | 
22 |   if ('events' %in% names(x)){
23 |     if ('samples' %in% names(x))
24 |     {
25 |       cat(sprintf('%d events and %d samples in %s.\n', nrow(x$events), nrow(x$samples), trialsN))
26 |     }
27 |     else{
28 |       cat(sprintf('%d events in %s.\n', nrow(x$events), trialsN))
29 |     }
30 |   }
31 |   else{
32 |     if ('samples' %in% names(x))
33 |     {
34 |       cat(sprintf('%d samples in %s.\n', nrow(x$samples), trialsN))
35 |     }
36 |     else{
37 |       cat(sprintf('%s. Neither events nor samples were imported.', trialsN))
38 |     }
39 |   }
40 | 
41 |   cat('Preamble:\n')
42 |   print(x$preamble)
43 | }
44 | 


--------------------------------------------------------------------------------
/R/read_edf.R:
--------------------------------------------------------------------------------
  1 | #' Read EDF file with gaze data recorded by SR Research EyeLink eye tracker
  2 | #'
  3 | #' Reads EDF file with gaze data recorded by SR Research EyeLink eye tracker
  4 | #' and returns an \code{\link{eyelinkRecording}} object that contains events, samples,
  5 | #' and recordings, as well as specific events such as saccades, fixations, blinks, etc.
  6 | #'
  7 | #' @param file full name of the EDF file
  8 | #' @param consistency consistency check control for the time stamps of the start
  9 | #' and end events, etc. Could be \code{'no consistency check'},
 10 | #' \code{'check consistency and report'} (default), \code{'check consistency and fix'}.
 11 | #' @param import_events logical, whether to import events, defaults to
 12 | #' \code{TRUE}
 13 | #' @param import_recordings logical, whether to import information about start/end of the recording, defaults to
 14 | #' \code{TRUE}
 15 | #' @param import_samples logical, whether to import samples, defaults to \code{FALSE}.
 16 | #' Please note that specifying\code{sample_attributes} automatically sets it to \code{TRUE}.
 17 | #' @param sample_attributes a character vector that lists sample attributes to be imported.
 18 | #' By default, all attributes are imported (default). For the complete list of sample attributes
 19 | #' please refer to \code{\link{eyelinkRecording}} or EDF API documentation.
 20 | #' @param start_marker event string that marks the beginning of the trial. Defaults to \code{"TRIALID"}.
 21 | #' @param end_marker event string that marks the end of the trial. Defaults to \code{"TRIAL_RESULT"}.
 22 | #' Please note that an \strong{empty} string \code{''} means that a trial lasts from one \code{start_marker} till the next one.
 23 | #' @param import_saccades logical, whether to extract saccade events into a separate table for convenience. Defaults to \code{TRUE}.
 24 | #' @param import_blinks logical, whether to extract blink events into a separate table for convenience. Defaults to \code{TRUE}.
 25 | #' @param import_fixations logical, whether to extract fixation events into a separate table for convenience. Defaults to \code{TRUE}.
 26 | #' @param import_variables logical, whether to extract stored variables into a separate table for convenience. Defaults to \code{TRUE}.
 27 | #' @param verbose logical, whether the number of trials and the progress are shown in the console. Defaults to \code{TRUE}.
 28 | #' @param fail_loudly logical, whether lack of compiled library means
 29 | #' error (\code{TRUE}, default) or just warning (\code{FALSE}).
 30 | #'
 31 | #' @return an \code{\link{eyelinkRecording}} object that contains events, samples,
 32 | #' and recordings, as well as specific events such as saccades, fixations, blinks, etc.
 33 | #' @export
 34 | #' @importFrom fs file_exists
 35 | #' @importFrom dplyr %>% mutate mutate_if
 36 | #' @examples
 37 | #' \donttest{
 38 | #'   if (eyelinkReader::compiled_library_status()) {
 39 | #'     # Import only events and recordings information
 40 | #'     recording <- read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"))
 41 | #'
 42 | #'     # Import events and samples (only time and  screen gaze coordinates)
 43 | #'     recording <- read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"),
 44 | #'                           sample_attributes = c('time', 'gx', 'gy'))
 45 | #'
 46 | #'     # Import events and samples (all attributes)
 47 | #'     recording <- read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"),
 48 | #'                           import_samples= TRUE)
 49 | #'   }
 50 | #' }
 51 | read_edf <- function(file,
 52 |                      consistency = 'check consistency and report',
 53 |                      import_events = TRUE,
 54 |                      import_recordings = TRUE,
 55 |                      import_samples = FALSE,
 56 |                      sample_attributes = NULL,
 57 |                      start_marker = 'TRIALID',
 58 |                      end_marker = 'TRIAL_RESULT',
 59 |                      import_saccades = TRUE,
 60 |                      import_blinks = TRUE,
 61 |                      import_fixations = TRUE,
 62 |                      import_variables = TRUE,
 63 |                      verbose = TRUE,
 64 |                      fail_loudly = TRUE){
 65 |   # failing with NULL, if no error was forced
 66 |   if (!check_that_compiled(fail_loudly)) return(NULL)
 67 | 
 68 | 
 69 |   # sanity checks before we pass parameters to C-code
 70 |   if (!fs::file_exists(file)) stop("File not found.")
 71 |   check_logical_flag(import_events)
 72 |   check_logical_flag(import_recordings)
 73 |   check_logical_flag(import_saccades)
 74 |   check_logical_flag(import_blinks)
 75 |   check_logical_flag(import_fixations)
 76 |   check_logical_flag(import_variables)
 77 |   check_logical_flag(verbose)
 78 |   check_string_parameter(start_marker)
 79 |   check_string_parameter(end_marker)
 80 | 
 81 |   # converting consistency to integer constant that C-code understands
 82 |   requested_consistency <- check_consistency_flag(consistency)
 83 | 
 84 |   # figuring out which sample attributes to import, if any
 85 |   sample_attr_flag <- logical_index_for_sample_attributes(import_samples, sample_attributes)
 86 |   import_samples <- sum(sample_attr_flag) > 0
 87 | 
 88 |   # importing data
 89 |   edf_recording <- eyelinkReader::read_edf_file(file,
 90 |                                                 requested_consistency,
 91 |                                                 import_events,
 92 |                                                 import_recordings,
 93 |                                                 import_samples,
 94 |                                                 sample_attr_flag,
 95 |                                                 start_marker,
 96 |                                                 end_marker,
 97 |                                                 verbose)
 98 | 
 99 |   # adding preamble
100 |   edf_recording$preamble <- read_preamble(file)
101 | 
102 |   # converting header to data.frame
103 |   edf_recording$headers <- data.frame(edf_recording$headers)
104 |   edf_recording$headers <- convert_header_codes(edf_recording$headers);
105 | 
106 |   # replacing -32768 with NA and converting lists to data.frames
107 |   if (import_samples){
108 |     edf_recording$samples <-
109 |       data.frame(edf_recording$samples) %>%
110 |       mutate_if(is.numeric, ~ifelse(is.nan(.x), NA, .x)) %>%
111 |       mutate(eye = factor(.data$eye, levels = c(0, 1, 2), labels = c('LEFT', 'RIGHT', 'BINOCULAR')))
112 |   }
113 |   if (import_events){
114 |     edf_recording$events <- data.frame(edf_recording$events)
115 |     edf_recording$events$message <- iconv(edf_recording$events$message, from = "ISO-8859-1", to = "UTF-8")
116 | 
117 |   }
118 |   if (import_recordings){
119 |     edf_recording$recordings <- data.frame(convert_NAs(data.frame(edf_recording$recordings)))
120 |     edf_recording$recordings <- convert_recording_codes(edf_recording$recordings)
121 |   }
122 | 
123 |   if (import_events){
124 |     edf_recording$events$eye <- factor(edf_recording$events$eye, levels= c(0, 1), labels= c('LEFT', 'RIGHT'))
125 |     edf_recording$events$type <- factor(edf_recording$events$type,
126 |                                         levels= c(1, 2, 10, 3, 4, 5, 6, 7, 8, 9, 15, 16, 17, 18, 24, 25, 28, 0x3F),
127 |                                         labels = c('STARTPARSE', 'ENDPARSE', 'BREAKPARSE',
128 |                                                    'STARTBLINK', 'ENDBLINK', 'STARTSACC', 'ENDSACC', 'STARTFIX', 'ENDFIX', 'FIXUPDATE',
129 |                                                    'STARTSAMPLES', 'ENDSAMPLES', 'STARTEVENTS', 'ENDEVENTS',
130 |                                                    'MESSAGEEVENT', 'BUTTONEVENT', 'INPUTEVENT', 'LOST_DATA_EVENT'))
131 |   }
132 | 
133 |   # extracting specific event types, if requested
134 |   if (import_events){
135 |     # checking display info, if present
136 |     edf_recording$display_coords <- extract_display_coords(edf_recording$events, silent = TRUE)
137 | 
138 |     if (import_saccades){
139 |       edf_recording$saccades <- extract_saccades(edf_recording$events)
140 |     }
141 |     if (import_blinks){
142 |       edf_recording$blinks <- extract_blinks(edf_recording$events)
143 |     }
144 |     if (import_fixations){
145 |       edf_recording$fixations <- extract_fixations(edf_recording$events)
146 |     }
147 |     if (import_variables){
148 |       edf_recording$variables <- extract_variables(edf_recording$events)
149 |     }
150 |   }
151 | 
152 |   class(edf_recording) <- 'eyelinkRecording'
153 |   return (edf_recording);
154 | }
155 | 


--------------------------------------------------------------------------------
/R/read_preamble.R:
--------------------------------------------------------------------------------
 1 | #' Reads edf-file preamble
 2 | #'
 3 | #' @description Read the preamble of the EDF file and parses it into an reading-friendly format
 4 | #' @param file name of the EDF file
 5 | #' @param fail_loudly logical, whether lack of compiled library means
 6 | #' error (\code{TRUE}, default) or just warning (\code{FALSE}).
 7 | #'
 8 | #' @return a character vector but with added class \code{eyelinkPreamble} to simplify printing.
 9 | #' @export
10 | #' @importFrom stringr str_split str_remove_all
11 | #'
12 | #' @examples
13 | #' \donttest{
14 | #'  if (eyelinkReader::compiled_library_status()) {
15 | #'   read_preamble(system.file("extdata", "example.edf", package = "eyelinkReader"))
16 | #' }
17 | #' }
18 | read_preamble <- function(file, fail_loudly = TRUE){
19 |   # failing with NULL, if no error was forced
20 |   if (!check_that_compiled(fail_loudly)) return(NULL)
21 | 
22 |   # getting the preamble as a single string and splitting it by new-line
23 |   preamble <- eyelinkReader::read_preamble_str(file) %>%
24 |     stringr::str_split('\\n', simplify = FALSE)
25 | 
26 |   # removing leading '** ', cause why would we need them?
27 |   preamble <- stringr::str_remove_all(preamble[[1]], '[\\*]{2} ')
28 | 
29 |   # dropping any empty strings
30 |   preamble <- preamble[sapply(preamble, stringr::str_length)>0]
31 | 
32 |   # assigning class name
33 |   class(preamble) <- 'eyelinkPreamble'
34 |   preamble
35 | }
36 | 
37 | 
38 | #' @export
39 | print.eyelinkPreamble <- function(x, ...){
40 |   preamble_output <- lapply(x, function(y){cat(y); cat("\n")})
41 | }
42 | 


--------------------------------------------------------------------------------
/R/zzz.R:
--------------------------------------------------------------------------------
  1 | #' Compiles the library linking it to EDF API
  2 | #'
  3 | #' @param libname character
  4 | #' @param pkgname character
  5 | #' @return No return value, called to compile EDF API interface.
  6 | #' @export
  7 | #' @importFrom methods is
  8 | #' @keywords internal
  9 | .onLoad <- function(libname, pkgname) {
 10 |   # attempt_to_compile()
 11 |   required_headers <- c('edf.h', 'edf_data.h', 'edftypes.h')
 12 | 
 13 |   locate_files <- function(files, folders) {
 14 |     for(a_folder in folders) if (all(file.exists(paste0(a_folder, "/", files)))) return(a_folder)
 15 | 
 16 |     return(NULL)
 17 |   }
 18 | 
 19 |   # copying the C++ source file file to a temporary folder for compilation
 20 |   temp_dir <- tempdir()
 21 |   file.copy(system.file("cpp", "edf_interface.cpp", package = pkgname), temp_dir)
 22 |   filename <- paste0(temp_dir, "/edf_interface.cpp")
 23 | 
 24 |   # make a copy of original compilation flags
 25 |   the_CXXFLAGS <- Sys.getenv("PKG_CXXFLAGS")
 26 |   the_PKG_LIBS <- Sys.getenv("PKG_LIBS")
 27 | 
 28 |   # figuring out which OS are we dealing with
 29 |   if (Sys.info()["sysname"] == "Windows") {
 30 |     include_path <- locate_files(required_headers,
 31 |                                  c(Sys.getenv("EDFAPI_INC"),
 32 |                                  "c:/Program Files (x86)/SR Research/EyeLink/Includes/eyelink"))
 33 | 
 34 |     if (.Machine$sizeof.pointer == 8) {
 35 |       # 64-bit
 36 |       library_file <- "edfapi64"
 37 |       library_path <- locate_files(paste0(library_file, ".dll"),
 38 |                                    c(Sys.getenv("EDFAPI_LIB64"),
 39 |                                      paste0(Sys.getenv("EDFAPI_LIB"), "/x64"),
 40 |                                      "c:/Program Files (x86)/SR Research/EyeLink/libs/x64"))
 41 |     } else {
 42 |       # 32-bit
 43 |       library_file <- "edfapi"
 44 |       library_path <- locate_files(paste0(library_file, ".dll"),
 45 |                                    c(Sys.getenv("EDFAPI_LIB"),
 46 |                                      "c:/Program Files (x86)/SR Research/EyeLink/libs"))
 47 |     }
 48 | 
 49 |     if (all(c(!is.null(include_path), !is.null(library_path)))) {
 50 |       Sys.setenv("PKG_CXXFLAGS"=sprintf('-I"%s"', include_path))
 51 |       Sys.setenv("PKG_LIBS"=sprintf('-L"%s" -l%s', library_path, library_file))
 52 |       compilation_outcome <- try(Rcpp::sourceCpp(filename, env = parent.env(environment())))
 53 |     }
 54 |   } else if (Sys.info()["sysname"] == "Linux") {
 55 |     include_path <- locate_files(required_headers,
 56 |                                  c(Sys.getenv("EDFAPI_INC"),
 57 |                                  "/usr/include/EyeLink"))
 58 |     if (!is.null(include_path)) {
 59 |       Sys.setenv("PKG_CXXFLAGS"=sprintf('-I"%s"', include_path))
 60 |       Sys.setenv("PKG_LIBS"='-ledfapi')
 61 |       compilation_outcome <- try(Rcpp::sourceCpp(filename,
 62 |                                                  env = parent.env(environment()),
 63 |                                                  echo = FALSE,
 64 |                                                  verbose = FALSE))
 65 |     }
 66 |   } else if (Sys.info()["sysname"] == "Darwin") {
 67 |     include_path <- locate_files(required_headers,
 68 |                                  c(Sys.getenv("EDFAPI_INC"),
 69 |                                    '/Library/Frameworks/edfapi.framework/Headers/'))
 70 |     library_path <-'/Library/Frameworks/'
 71 |     if (!is.null(include_path)) {
 72 |       Sys.setenv("PKG_CXXFLAGS"=sprintf('-I"%s"', include_path))
 73 |       Sys.setenv("PKG_LIBS"=sprintf('-framework edfapi -F%s -rpath %s', library_path, library_path))
 74 |       compilation_outcome <- try(Rcpp::sourceCpp(filename,
 75 |                                                  env = parent.env(environment()),
 76 |                                                  echo = FALSE,
 77 |                                                  verbose = FALSE))
 78 |     }
 79 |   }
 80 | 
 81 |   # restore original compilation flags
 82 |   Sys.setenv("PKG_CXXFLAGS" = the_CXXFLAGS)
 83 |   Sys.setenv("PKG_LIBS" = the_PKG_LIBS)
 84 | }
 85 | 
 86 | 
 87 | #' Check if the library was compiled
 88 | #'
 89 | #' @param libname character
 90 | #' @param pkgname character
 91 | #' @return No return value, called to check and warn if compiled EDF API interface is missing.
 92 | #' @export
 93 | #' @keywords internal
 94 | .onAttach <- function(libname, pkgname) {
 95 |   if (!eyelinkReader::compiled_library_status()){
 96 |     if (Sys.info()["sysname"] %in% c("Windows", "Linux", "Darwin")){
 97 |       packageStartupMessage("Failed to compile EDF API interface, please read installation instructions.")
 98 |     } else{
 99 |       packageStartupMessage("Unfortunately, there is no EDF API implementation for your plaform.")
100 |     }
101 |   }
102 | }
103 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # eyelinkReader <a href="https://alexander-pastukhov.github.io/eyelinkReader/"><img align="right" src="https://raw.githubusercontent.com/alexander-pastukhov/eyelinkReader/refs/heads/master/man/figures/logo.svg" alt="Logo" height="138" style="float:right; height:138px;"/></a>
  2 | <!-- badges: start -->
  3 | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7050482.svg)](https://doi.org/10.5281/zenodo.7050482)
  4 | [![CRAN status](https://www.r-pkg.org/badges/version/eyelinkReader)](https://cran.r-project.org/package=eyelinkReader)
  5 | <!-- badges: end -->
  6 | 
  7 | R package to import eye tracking recording generated by [SR Research](https://www.sr-research.com/) EyeLink eye tracker from  EDF-files. It includes options to import events and/or recorded samples and extract individual events such as saccades, fixations, blinks, and recorded variables.
  8 | 
  9 | ## Installation
 10 | 
 11 | These instructions are also available as a vignette.
 12 | 
 13 | The library installation involves three easy (famous last words) steps.
 14 | 
 15 | ### Install SR Research EyeLink Developers Kit
 16 | This package relies on _edfapi_ library that is as part of the _EyeLink Developers Kit_. Therefore, `read_edf()` function **will not work without it** but you will still be able to use utility functions. The _EyeLink Developers Kit_ can be downloaded from [www.sr-research.com/support](https://www.sr-research.com/support/) website. Note that you need to register and wait for your account to be activated. Next, follow instructions to install _EyeLink Developers Kit_ for your platform. The forum thread should be under _SR Support Forum › Downloads › EyeLink Developers Kit / API › Download: EyeLink Developers Kit / API Downloads (Windows, macOS, Linux)_.
 17 | 
 18 | ### Configure R environment variables
 19 | 
 20 | The package needs to configure compiler flags for its dependency on EDF API library. Specifically, it needs to specify paths to include header files (_edf.h_, _edf_data.h_, and _edftypes.h_) and to the library itself. The package will try to compile using sensible defaults for each platform, i.e., default installation paths for _EyeLink Developers Kit v2.1.1_. However, these defaults may change in the future or you may wish to install the library to a non-standard location (relevant primarily for Windows).
 21 | 
 22 | If compilation with default paths fails, you need to define R environment variables as described below. These variables must be defined either in user or project [.Renviron](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html) file. The simplest way to edit it is via [usethis](https://usethis.r-lib.org/) library and [edit_r_environ()](https://usethis.r-lib.org/reference/edit.html) function. Type `usethis::edit_r_environ()` for user and `usethis::edit_r_environ('project')` for projects environments (note that the latter shadows the former, read [documentation](https://usethis.r-lib.org/) for details). Note that in the case of Windows, you do not need to worry about forward vs. backward slashes as R will normalize strings for you. Once you define the variables, restart session and check them by typing `Sys.getenv()` (to see all variables) or `Sys.getenv("EDFAPI_INC")` to check a specific one.
 23 | 
 24 | #### Windows
 25 | For the package to work on Windows, you must install [Rtools](https://cran.r-project.org/bin/windows/Rtools/). Please note that as of 31.05.2024, you need [Rtool43](https://cran.r-project.org/bin/windows/Rtools/rtools43/rtools.html) even if your R version is 4.4.x, the compilation fails with Rtools44.
 26 | 
 27 | Default values assume that the EyeLink Developers Kit is installed in `c:/Program Files (x86)/SR Research/EyeLink` (default installation path).
 28 | 
 29 | * `EDFAPI_LIB` : path to `edfapi.dll` for **32-bit systems**. Defaults to `c:/Program Files (x86)/SR Research/EyeLink/libs`.
 30 | * `EDFAPI_LIB64` (optional): path to `edfapi64.dll` for **64-bit systems**. By default, the 64-bit library is in _x64_ subfolder, i.e., `c:/Program Files (x86)/SR Research/EyeLink/libs/x64`. This variable is optional, as the package will try to guess this by itself by appending `/x64` to `EDFAPI_LIB` path. However, you should specify this variable explicitly if 64-libraries are in a non-standard folder (or SR Research changed it, or you just want to be sure).
 31 | * `EDFAPI_INC` : path to C header files necessary for compilation. Specifically, the package requires _edf.h_, _edf_data.h_, and _edftypes.h_. Defaults to `c:/Program Files (x86)/SR Research/EyeLink/Includes/eyelink`.
 32 | 
 33 | Your `.Renviron` file should include lines similar to the ones below
 34 | ```
 35 | EDFAPI_LIB="c:/Program Files (x86)/SR Research/EyeLink/libs"
 36 | EDFAPI_LIB64="c:/Program Files (x86)/SR Research/EyeLink/libs/x64"
 37 | EDFAPI_INC="c:/Program Files (x86)/SR Research/EyeLink/Includes/eyelink"
 38 | ```
 39 | 
 40 | #### Linux
 41 | * `EDFAPI_INC` : path to C header files necessary for compilation. Specifically, the package requires _edf.h_, _edf_data.h_, and _edftypes.h_. Defaults to `/usr/include/EyeLink`.
 42 | 
 43 | Your `.Renviron` file should include a line like this
 44 | ```
 45 | EDFAPI_INC="/usr/include/EyeLink"
 46 | ```
 47 | 
 48 | #### Mac OS
 49 | 
 50 | * `EDFAPI_LIB`: path to EDF API framework. Defaults to `/Library/Frameworks`
 51 | * `EDFAPI_INC` : path to C header files necessary for compilation. Specifically, the package requires _edf.h_, _edf_data.h_, and _edftypes.h_. Defaults to `/Library/Frameworks/edfapi.framework/Headers`
 52 | 
 53 | Your `.Renviron` file should include lines similar to the ones below
 54 | ```
 55 | EDFAPI_LIB="/Library/Frameworks"
 56 | EDFAPI_INC="/Library/Frameworks/edfapi.framework/Headers"
 57 | ```
 58 | 
 59 | ### Install the library
 60 | 
 61 | To install from CRAN
 62 | 
 63 | ```r
 64 | install.packages("eyelinkReader")
 65 | ```
 66 | 
 67 | To install from github
 68 | ```r
 69 | library("devtools")
 70 | install_github("alexander-pastukhov/eyelinkReader", dependencies=TRUE)
 71 | ```
 72 | 
 73 | ## Usage
 74 | 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.
 75 | ```r
 76 | library(eyelinkReader)
 77 | gaze <- read_edf('eyelink-recording.edf')
 78 | ```
 79 | 
 80 | 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. 
 81 | ```r
 82 | View(gaze$saccades)
 83 | ```
 84 | 
 85 | There is a basic utility for plotting saccades and fixations for an individual trial
 86 | ```r
 87 | plot(gaze, trial = 1, show_fixations = TRUE, show_saccades = TRUE)
 88 | ```
 89 | 
 90 | or across trials
 91 | ```r
 92 | plot(gaze, trial = NULL, show_fixations = TRUE, show_saccades = FALSE)
 93 | ```
 94 | 
 95 | The package also includes functions to parse non-standard events: recorded areas of interest (`extract_AOIs`) and trigger events that help to time events (`extract_triggers`). These need to be called separately.
 96 | 
 97 | ```r
 98 | gaze <- extract_AOIs(gaze)
 99 | gaze <- extract_triggers(gaze)
100 | ```
101 | 
102 | 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.
103 | 
104 | ```r
105 | # import samples with all attributes
106 | gaze <- read_edf('eyelink-recording.edf', import_samples = TRUE)
107 | 
108 | # import samples with selected attributes
109 | gaze <- read_edf('eyelink-recording.edf',
110 |                  import_samples = TRUE,
111 |                  sample_attributes = c('time', 'gx', 'gy'))
112 | ```
113 | 
114 | See also a vignette on package usage. Please refer to documentation on `eyelinkRecording` class for details on events and samples.
115 | 
116 | 
117 | ## Further information on EDF file content
118 | 
119 | I have attempted to document the package as thoroughly as I could. However, for any question about specific attributes please refer to the EDF API manual and EyeLink documentation, which is supplied by SR Research alongside the library.
120 | 
121 | 


--------------------------------------------------------------------------------
/_pkgdown.yml:
--------------------------------------------------------------------------------
1 | url: https://alexander-pastukhov.github.io/eyelinkReader/
2 | template:
3 |   bootstrap: 5
4 | 
5 | 


--------------------------------------------------------------------------------
/data/gaze.rda:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alexander-pastukhov/eyelinkReader/f041af9117ac14c954078b2871681207743d0fe4/data/gaze.rda


--------------------------------------------------------------------------------
/eyelinkReader.Rproj:
--------------------------------------------------------------------------------
 1 | Version: 1.0
 2 | ProjectId: ba7a73bd-c284-4c9f-b0a8-752076b52a8c
 3 | 
 4 | RestoreWorkspace: Default
 5 | SaveWorkspace: Default
 6 | AlwaysSaveHistory: Default
 7 | 
 8 | EnableCodeIndexing: Yes
 9 | UseSpacesForTab: Yes
10 | NumSpacesForTab: 2
11 | Encoding: UTF-8
12 | 
13 | RnwWeave: Sweave
14 | LaTeX: pdfLaTeX
15 | 
16 | AutoAppendNewline: Yes
17 | StripTrailingWhitespace: Yes
18 | 
19 | BuildType: Package
20 | PackageUseDevtools: Yes
21 | PackageInstallArgs: --no-multiarch --with-keep.source
22 | PackageRoxygenize: rd,collate,namespace,vignette
23 | 


--------------------------------------------------------------------------------
/inst/WORDLIST:
--------------------------------------------------------------------------------
 1 | AOI
 2 | AOIs
 3 | COORDS
 4 | EyeLink
 5 | Headref
 6 | IAREA
 7 | PARSEDBY
 8 | Renviron
 9 | Saccades
10 | attr
11 | cyclopean
12 | edf
13 | edfapi
14 | edftypes
15 | environ
16 | eyelinkRecording
17 | geoms
18 | ggplot
19 | github
20 | gx
21 | gxL
22 | gxR
23 | headref
24 | macOS
25 | postprocessing
26 | pre
27 | progressbar
28 | saccade
29 | saccades
30 | sr
31 | subfolder
32 | tidyverse
33 | usethis
34 | 


--------------------------------------------------------------------------------
/inst/cpp/edf_interface.cpp:
--------------------------------------------------------------------------------
  1 | #include <sstream>
  2 | #include <math.h>
  3 | 
  4 | #include <Rcpp.h>
  5 | using namespace Rcpp;
  6 | 
  7 | // [[Rcpp::depends(RcppProgress)]]
  8 | #include <progress.hpp>
  9 | 
 10 | namespace edfapi {
 11 | #include "edf.h"
 12 | }
 13 | 
 14 | const float FLOAT_NAN = nanf("");
 15 | 
 16 | 
 17 | //' @title Status of compiled library
 18 | //' @description Return status of compiled library
 19 | //' @return logical
 20 | //' @export
 21 | //' @examples
 22 | //' compiled_library_status()
 23 | //[[Rcpp::export]]
 24 | bool compiled_library_status(){
 25 |   // the other version, compiled at installation returns false
 26 |   return(true);
 27 | }
 28 | 
 29 | 
 30 | // ------------------ data structures, as defined in EDF C API user manual ------------------
 31 | typedef struct TRIAL_EVENTS {
 32 |   std::vector <unsigned int> trial_index;
 33 |   std::vector <edfapi::UINT32> time;
 34 |   std::vector <edfapi::INT16> type;
 35 |   std::vector <edfapi::UINT16> read;
 36 |   std::vector <edfapi::UINT32> sttime;
 37 |   std::vector <edfapi::UINT32> sttime_rel;
 38 |   std::vector <edfapi::UINT32> entime;
 39 |   std::vector <edfapi::UINT32> entime_rel;
 40 |   std::vector <float> hstx;
 41 |   std::vector <float> hsty;
 42 |   std::vector <float> gstx;
 43 |   std::vector <float> gsty;
 44 |   std::vector <float> sta;
 45 |   std::vector <float> henx;
 46 |   std::vector <float> heny;
 47 |   std::vector <float> genx;
 48 |   std::vector <float> geny;
 49 |   std::vector <float> ena;
 50 |   std::vector <float> havx;
 51 |   std::vector <float> havy;
 52 |   std::vector <float> gavx;
 53 |   std::vector <float> gavy;
 54 |   std::vector <float> ava;
 55 |   std::vector <float> avel;
 56 |   std::vector <float> pvel;
 57 |   std::vector <float> svel;
 58 |   std::vector <float> evel;
 59 |   std::vector <float> supd_x;
 60 |   std::vector <float> eupd_x;
 61 |   std::vector <float> supd_y;
 62 |   std::vector <float> eupd_y;
 63 |   std::vector <edfapi::INT16> eye;
 64 |   std::vector <edfapi::UINT16> status;
 65 |   std::vector <edfapi::UINT16> flags;
 66 |   std::vector <edfapi::UINT16> input;
 67 |   std::vector <edfapi::UINT16> buttons;
 68 |   std::vector <edfapi::UINT16> parsedby;
 69 |   std::vector <std::string> message;
 70 | } TRIAL_EVENTS;
 71 | 
 72 | 
 73 | // please note that byte type were replaced with UINT16 for compatibility reasons
 74 | typedef struct TRIAL_RECORDINGS{
 75 |   std::vector <unsigned int> trial_index;
 76 |   std::vector <edfapi::UINT32> time;
 77 |   std::vector <edfapi::UINT32> time_rel;
 78 |   std::vector <float> sample_rate;
 79 |   std::vector <edfapi::UINT16> eflags;
 80 |   std::vector <edfapi::UINT16> sflags;
 81 |   std::vector <edfapi::UINT16> state;
 82 |   std::vector <edfapi::UINT16> record_type;
 83 |   std::vector <edfapi::UINT16> pupil_type;
 84 |   std::vector <edfapi::UINT16> recording_mode;
 85 |   std::vector <edfapi::UINT16> filter_type;
 86 |   std::vector <edfapi::UINT16> pos_type;
 87 |   std::vector <edfapi::UINT16> eye;
 88 | } TRIAL_RECORDINGS;
 89 | 
 90 | typedef struct TRAIL_SAMPLES{
 91 |   std::vector <unsigned int> trial_index;
 92 |   std::vector <edfapi::UINT32> time;
 93 |   std::vector <edfapi::UINT32> time_rel;
 94 |   std::vector <unsigned int> eye;
 95 |   // NumericVector pxL;
 96 |   // NumericVector pxR;
 97 |   std::vector <float> pxL;
 98 |   std::vector <float> pxR;
 99 |   std::vector <float> pyL;
100 |   std::vector <float> pyR;
101 |   std::vector <float> hxL;
102 |   std::vector <float> hxR;
103 |   std::vector <float> hyL;
104 |   std::vector <float> hyR;
105 |   std::vector <float> paL;
106 |   std::vector <float> paR;
107 |   std::vector <float> gxL;
108 |   std::vector <float> gxR;
109 |   std::vector <float> gyL;
110 |   std::vector <float> gyR;
111 |   std::vector <float> rx;
112 |   std::vector <float> ry;
113 |   std::vector <float> gxvelL;
114 |   std::vector <float> gxvelR;
115 |   std::vector <float> gyvelL;
116 |   std::vector <float> gyvelR;
117 |   std::vector <float> hxvelL;
118 |   std::vector <float> hxvelR;
119 |   std::vector <float> hyvelL;
120 |   std::vector <float> hyvelR;
121 |   std::vector <float> rxvelL;
122 |   std::vector <float> rxvelR;
123 |   std::vector <float> ryvelL;
124 |   std::vector <float> ryvelR;
125 |   std::vector <float> fgxvelL;
126 |   std::vector <float> fgxvelR;
127 |   std::vector <float> fgyvelL;
128 |   std::vector <float> fgyvelR;
129 |   std::vector <float> fhxvelL;
130 |   std::vector <float> fhxvelR;
131 |   std::vector <float> fhyvelL;
132 |   std::vector <float> fhyvelR;
133 |   std::vector <float> frxvelL;
134 |   std::vector <float> frxvelR;
135 |   std::vector <float> fryvelL;
136 |   std::vector <float> fryvelR;
137 | 
138 |   std::vector <edfapi::INT16> hdata_1;
139 |   std::vector <edfapi::INT16> hdata_2;
140 |   std::vector <edfapi::INT16> hdata_3;
141 |   std::vector <edfapi::INT16> hdata_4;
142 |   std::vector <edfapi::INT16> hdata_5;
143 |   std::vector <edfapi::INT16> hdata_6;
144 |   std::vector <edfapi::INT16> hdata_7;
145 |   std::vector <edfapi::INT16> hdata_8;
146 | 
147 |   std::vector <edfapi::UINT16> flags;
148 |   std::vector <edfapi::UINT16> input;
149 |   std::vector <edfapi::UINT16> buttons;
150 |   std::vector <edfapi::INT16> htype;
151 |   std::vector <edfapi::UINT16> errors;
152 | } TRIAL_SAMPLES;
153 | 
154 | 
155 | //' @title Converts a float value to an explicit NaN, if necessary
156 | //' @param value float
157 | //' @return float
158 | //' @export
159 | //' @keywords internal
160 | inline float float_or_nan(float value) {
161 |   if ((value <= MISSING_DATA) || (value >= 1e8)) return FLOAT_NAN;
162 |   return value;
163 | }
164 | 
165 | // ------------------ EDF API interface ------------------
166 | 
167 | //' @title Version of the EDF API library
168 | //' @description Returns version of the EDF API library used to interface an EDF file.
169 | //' @export
170 | //' @examples
171 | //' eyelinkReader::library_version()
172 | //[[Rcpp::export]]
173 | CharacterVector library_version(){
174 |   Rcpp::StringVector version_info(1);
175 |   version_info[0] = edfapi::edf_get_version();
176 |   return version_info;
177 | }
178 | 
179 | 
180 | // @title Opens EDF file, throws exception on error
181 | // @description Opens EDF file for reading, throws exception and prints error message if fails.
182 | // @param std::string filename, name of the EDF file
183 | // @param int consistency, consistency check control (for the time stamps of the start
184 | // and end events, etc). 0, no consistency check. 1, check consistency and report.
185 | // 2, check consistency and fix.
186 | // @param int loadevents, load/skip loading events 0, do not load events. 1, load events.
187 | // @param int loadsamples, load/skip loading of samples 0, do not load samples. 1, load samples.
188 | // @return pointer to the EDF file
189 | // @keywords internal
190 | edfapi::EDFFILE* safely_open_edf_file(std::string filename, int consistency, int loadevents, int loadsamples){
191 |   // opening the edf file
192 |   int ReturnValue;
193 |   edfapi::EDFFILE* edfFile = edfapi::edf_open_file(filename.c_str(), consistency, loadevents, loadsamples, &ReturnValue);
194 | 
195 |   // throwing an exception, if things go pear shaped
196 |   if (ReturnValue != 0){
197 |     std::stringstream error_message_stream;
198 |     error_message_stream << "Error opening file '" << filename << "', error code: " << ReturnValue;
199 |     ::Rf_error("%s", error_message_stream.str().c_str());
200 |   }
201 | 
202 |   return edfFile;
203 | }
204 | 
205 | //' @title Reads preamble of the EDF file as a single string.
206 | //' @description Reads preamble of the EDF file as a single string.
207 | //' Please, do not use this function directly. Instead, call \code{\link{read_preamble}} function
208 | //' that provides a more consistent interface.
209 | //' @return string with the preamble
210 | //' @export
211 | //' @keywords internal
212 | //' @examples
213 | //' \donttest{
214 | //' read_preamble(system.file("extdata", "example.edf", package = "eyelinkReader"))
215 | //' }
216 | //[[Rcpp::export]]
217 | std::string read_preamble_str(std::string filename){
218 |   edfapi::EDFFILE* edfFile = safely_open_edf_file(filename, 2, 0, 0);
219 | 
220 |   // getting preable
221 |   int ReturnValue;
222 |   char preamble_buffer[2048];
223 |   ReturnValue = edfapi::edf_get_preamble_text(edfFile, preamble_buffer, 2048);
224 |   if (ReturnValue != 0)
225 |   {
226 |     std::stringstream error_message_stream;
227 |     error_message_stream << "Error reading preable for file '" << filename << "', error code: " << ReturnValue;
228 |     ::Rf_error("%s", error_message_stream.str().c_str());
229 |   }
230 |   std::string preamble(preamble_buffer);
231 | 
232 |   // closing file
233 |   edfapi::edf_close_file(edfFile);
234 | 
235 |   return preamble;
236 | }
237 | 
238 | 
239 | //' @title Sets trial navigation for EDF API
240 | //' @description Sets trial navigation via the markers for the start and the end of the trial.
241 | //' @param EDFFILE* edfFile, pointer to the EDF file
242 | //' @param std::string start_marker_string, event that marks trial start. Defaults to "TRIALID", if empty.
243 | //' @param std::string end_marker_string, event that marks trial end
244 | //' @seealso safely_open_edf_file
245 | //' @keywords internal
246 | void set_trial_navigation_up(edfapi::EDFFILE* edfFile, std::string start_marker_string, std::string end_marker_string){
247 |   // converting strings to char buffers
248 |   char * start_marker_char = new char[start_marker_string.size() + 1];
249 |   std::copy(start_marker_string.begin(), start_marker_string.end(), start_marker_char);
250 |   start_marker_char[start_marker_string.size()] = '\0';
251 | 
252 |   char * end_marker_char = new char[end_marker_string.size() + 1];
253 |   std::copy(end_marker_string.begin(), end_marker_string.end(), end_marker_char);
254 |   end_marker_char[end_marker_string.size()] = '\0';
255 | 
256 |   // setting the trial identifier
257 |   if (edf_set_trial_identifier(edfFile, start_marker_char, end_marker_char)){
258 |     ::Rf_error("Error while setting up trial navigation identifier");
259 |   }
260 | 
261 |   // cleaning up
262 |   delete[] start_marker_char;
263 |   delete[] end_marker_char;
264 | }
265 | 
266 | //' @title Jumps to the i-th trial
267 | //' @description Jumps to the i-th trial, throws an exception and prints an error message, if fails.
268 | //' @param EDFFILE* edfFile, pointer to the EDF file
269 | //' @param int iTrial, index of the desired trial
270 | //' @seealso safely_open_edf_file, set_trial_navigation_up
271 | //' @keywords internal
272 | void jump_to_trial(edfapi::EDFFILE* edfFile, int iTrial){
273 |   if (edfapi::edf_jump_to_trial(edfFile, iTrial) != 0){
274 |     std::stringstream error_message_stream;
275 |     error_message_stream << "Error jumping to trial " << iTrial+1;
276 |     ::Rf_error("%s", error_message_stream.str().c_str());
277 |   }
278 | }
279 | 
280 | //' @title Prepare matrix for trial headers
281 | //' @description Prepare matrix for trial headers.
282 | //' @param int total_trials, total number of trials, i.e. number of rows in the matrix
283 | //' @return NumericMatrix total_trials (rows) x 15 (columns)
284 | //' @keywords internal
285 | NumericMatrix prepare_trial_headers(int total_trials){
286 |   // row names
287 |   NumericVector row_index(total_trials);
288 |   for(int iTrial= 0; iTrial< total_trials; iTrial++)
289 |   {
290 |     row_index[iTrial] = iTrial+1;
291 |   };
292 | 
293 |   // column names
294 |   CharacterVector col_names= CharacterVector::create("trial", "duration", "starttime", "endtime",
295 |                                                      "rec_time", "rec_sample_rate", "rec_eflags",
296 |                                                      "rec_sflags", "rec_state", "rec_record_type",
297 |                                                      "rec_pupil_type", "rec_recording_mode", "rec_filter_type",
298 |                                                      "rec_pos_type", "rec_eye");
299 | 
300 |   // create the matrix
301 |   NumericMatrix trial_headers= NumericMatrix(total_trials, col_names.size());
302 |   trial_headers.attr("dimnames") = List::create(row_index, col_names);
303 |   return (trial_headers);
304 | }
305 | 
306 | //' @title Read header for the i-th trial
307 | //' @description Read head and store it in the i-th row of the headers matrix
308 | //' @param EDFFILE* edfFile, pointer to the EDF file
309 | //' @param NumericMatrix &trial_headers, reference to the trial header matrix
310 | //' @param int iTrial, the row in which the header will be stored.
311 | //' Functions assumes that the correct trial within the EDF file was already navigated to.
312 | //' @return modifes trial_headers i-th row in place
313 | //' @keywords internal
314 | void read_trial_header(edfapi::EDFFILE* edfFile, NumericMatrix &trial_headers, int iTrial){
315 | 
316 |   // obtaining the trial header
317 |   edfapi::TRIAL current_header;
318 |   if (edf_get_trial_header(edfFile, &current_header) != 0){
319 |     std::stringstream error_message_stream;
320 |     error_message_stream << "Error obtaining the header for the trial " << iTrial+1;
321 |     ::Rf_error("%s", error_message_stream.str().c_str());
322 |   }
323 | 
324 |   // copying it over
325 |   trial_headers(iTrial, 0) = iTrial+1;
326 |   trial_headers(iTrial, 1) = current_header.duration;
327 |   trial_headers(iTrial, 2) = current_header.starttime;
328 |   trial_headers(iTrial, 3) = current_header.endtime;
329 |   trial_headers(iTrial, 4) = current_header.rec->time;
330 |   trial_headers(iTrial, 5) = current_header.rec->sample_rate ;
331 |   trial_headers(iTrial, 6) = current_header.rec->eflags;
332 |   trial_headers(iTrial, 7) = current_header.rec->sflags;
333 |   trial_headers(iTrial, 8) = current_header.rec->state;
334 |   trial_headers(iTrial, 9) = current_header.rec->record_type;
335 |   trial_headers(iTrial,10) = current_header.rec->pupil_type;
336 |   trial_headers(iTrial,11) = current_header.rec->recording_mode;
337 |   trial_headers(iTrial,12) = current_header.rec->filter_type;
338 |   trial_headers(iTrial,13) = current_header.rec->pos_type;
339 |   trial_headers(iTrial,14) = current_header.rec->eye;
340 | }
341 | 
342 | //' @title Appends event to the even structure
343 | //' @description Appends a new event to the even structure and copies all the data
344 | //' @param TRIAL_EVENTS &events, reference to the trial events structure
345 | //' @param FEVENT new_event, structure with event info, as described in the EDF API manual
346 | //' @param int iTrial, the index of the trial the event belongs to
347 | //' @param UINT32 trial_start, the timestamp of the trial start.
348 | //' Is used to compute event time relative to it.
349 | //' @return modifies events structure
350 | //' @keywords internal
351 | void append_event(TRIAL_EVENTS &events, edfapi::FEVENT new_event, unsigned int iTrial, edfapi::UINT32 trial_start){
352 |   events.trial_index.push_back(iTrial);
353 |   events.time.push_back(new_event.time);
354 |   events.type.push_back(new_event.type);
355 |   events.read.push_back(new_event.read);
356 |   events.sttime.push_back(new_event.sttime);
357 |   events.sttime_rel.push_back(new_event.sttime-trial_start);
358 |   events.entime.push_back(new_event.entime);
359 |   if (new_event.entime>0){
360 |     events.entime_rel.push_back(new_event.entime-trial_start);
361 |   }
362 |   else
363 |   {
364 |     events.entime_rel.push_back(new_event.entime);
365 |   }
366 |   events.hstx.push_back(new_event.hstx);
367 |   events.hsty.push_back(new_event.hsty);
368 |   events.gstx.push_back(new_event.gstx);
369 |   events.gsty.push_back(new_event.gsty);
370 |   events.sta.push_back(new_event.sta);
371 |   events.henx.push_back(new_event.henx);
372 |   events.heny.push_back(new_event.heny);
373 |   events.genx.push_back(new_event.genx);
374 |   events.geny.push_back(new_event.geny);
375 |   events.ena.push_back(new_event.ena);
376 |   events.havx.push_back(new_event.havx);
377 |   events.havy.push_back(new_event.havy);
378 |   events.gavx.push_back(new_event.gavx);
379 |   events.gavy.push_back(new_event.gavy);
380 |   events.ava.push_back(new_event.ava);
381 |   events.avel.push_back(new_event.avel);
382 |   events.pvel.push_back(new_event.pvel);
383 |   events.svel.push_back(new_event.svel);
384 |   events.evel.push_back(new_event.evel);
385 |   events.supd_x.push_back(new_event.supd_x);
386 |   events.eupd_x.push_back(new_event.eupd_x);
387 |   events.supd_y.push_back(new_event.supd_y);
388 |   events.eupd_y.push_back(new_event.eupd_y);
389 |   events.eye.push_back(new_event.eye);
390 |   events.status.push_back(new_event.status);
391 |   events.flags.push_back(new_event.flags);
392 |   events.input.push_back(new_event.input);
393 |   events.buttons.push_back(new_event.buttons);
394 |   events.parsedby.push_back(new_event.parsedby);
395 | 
396 |   // special case: LSTRING message
397 |   edfapi::LSTRING* message_ptr = ((edfapi::LSTRING*)new_event.message);
398 |   if (message_ptr == 0 || message_ptr == NULL){
399 |     events.message.push_back("");
400 |   }
401 |   else{
402 |     char* message_char = new char[message_ptr->len];
403 |     strncpy(message_char, &(message_ptr->c), message_ptr->len);
404 |     events.message.push_back(message_char);
405 |     delete[] message_char;
406 |   }
407 | }
408 | 
409 | //' @title Appends recording to the recording structure
410 | //' @description Appends a new recording to the recordings structure and copies all the data
411 | //' @param TRIAL_RECORDINGS &recordings, reference to the trial recording structure
412 | //' @param RECORDINGS new_rec, structure with recordiong info, as described in the EDF API manual
413 | //' @param int iTrial, the index of the trial the event belongs to
414 | //' @param UINT32 trial_start, the timestamp of the trial start.
415 | //' Is used to compute event time relative to it.
416 | //' @return modifies recordings structure
417 | //' @keywords internal
418 | void append_recording(TRIAL_RECORDINGS &recordings, edfapi::RECORDINGS new_rec, unsigned int iTrial, edfapi::UINT32 trial_start){
419 |   recordings.trial_index.push_back(iTrial+1);
420 |   recordings.time.push_back(new_rec.time);
421 |   recordings.time_rel.push_back(new_rec.time-trial_start);
422 |   recordings.sample_rate.push_back(new_rec.sample_rate);
423 |   recordings.eflags.push_back(new_rec.eflags);
424 |   recordings.sflags.push_back(new_rec.sflags);
425 |   recordings.state.push_back(new_rec.state);
426 |   recordings.record_type.push_back(new_rec.record_type);
427 |   recordings.pupil_type.push_back(new_rec.pupil_type);
428 |   recordings.recording_mode.push_back(new_rec.recording_mode);
429 |   recordings.filter_type.push_back(new_rec.filter_type);
430 |   recordings.pos_type.push_back(new_rec.pos_type);
431 |   recordings.eye.push_back(new_rec.eye);
432 | }
433 | 
434 | 
435 | //' @title Appends sample to the samples structure
436 | //' @description Appends a new sample to the samples structure and copies all the data
437 | //' @param TRIAL_SAMPLES &samples, reference to the trial samples structure
438 | //' @param FSAMPLE new_sample, structure with sample info, as described in the EDF API manual
439 | //' @param int iTrial, the index of the trial the event belongs to
440 | //' @param UINT32 trial_start, the timestamp of the trial start. Is used to compute event time relative to it.
441 | //' @param LogicalVector sample_attr_flag, boolean vector that indicates which sample fields are to be stored
442 | //' @return modifies samples structure
443 | //' @keywords internal
444 | void append_sample(TRIAL_SAMPLES &samples, edfapi::FSAMPLE new_sample, unsigned int iTrial, edfapi::UINT32 trial_start, LogicalVector sample_attr_flag)
445 | {
446 |   samples.trial_index.push_back(iTrial+1);
447 | 
448 |   if (new_sample.flags & SAMPLE_LEFT) {
449 |     if (new_sample.flags & SAMPLE_RIGHT) {
450 |       samples.eye.push_back(2);
451 |     }
452 |     else {
453 |       samples.eye.push_back(0);
454 |     }
455 |   }
456 |   else {
457 |     samples.eye.push_back(1);
458 |   }
459 | 
460 |   if (sample_attr_flag[0]){
461 |     samples.time.push_back(new_sample.time);
462 |     samples.time_rel.push_back(new_sample.time - trial_start);
463 |   }
464 |   if (sample_attr_flag[1]){
465 |     samples.pxL.push_back(float_or_nan(new_sample.px[0]));
466 |     samples.pxR.push_back(float_or_nan(new_sample.px[1]));
467 |   }
468 |   if (sample_attr_flag[2]){
469 |     samples.pyL.push_back(float_or_nan(new_sample.py[0]));
470 |     samples.pyR.push_back(float_or_nan(new_sample.py[1]));
471 |   }
472 |   if (sample_attr_flag[3]){
473 |     samples.hxL.push_back(float_or_nan(new_sample.hx[0]));
474 |     samples.hxR.push_back(float_or_nan(new_sample.hx[1]));
475 |   }
476 |   if (sample_attr_flag[4]){
477 |     samples.hyL.push_back(float_or_nan(new_sample.hy[0]));
478 |     samples.hyR.push_back(float_or_nan(new_sample.hy[1]));
479 |   }
480 |   if (sample_attr_flag[5]){
481 |     samples.paL.push_back(float_or_nan(new_sample.pa[0]));
482 |     samples.paR.push_back(float_or_nan(new_sample.pa[1]));
483 |   }
484 |   if (sample_attr_flag[6]){
485 |     samples.gxL.push_back(float_or_nan(new_sample.gx[0]));
486 |     samples.gxR.push_back(float_or_nan(new_sample.gx[1]));
487 |   }
488 |   if (sample_attr_flag[7]){
489 |     samples.gyL.push_back(float_or_nan(new_sample.gy[0]));
490 |     samples.gyR.push_back(float_or_nan(new_sample.gy[1]));
491 |   }
492 |   if (sample_attr_flag[8]){
493 |     samples.rx.push_back(float_or_nan(new_sample.rx));
494 |   }
495 |   if (sample_attr_flag[9]){
496 |     samples.ry.push_back(float_or_nan(new_sample.ry));
497 |   }
498 |   if (sample_attr_flag[10]){
499 |     samples.gxvelL.push_back(float_or_nan(new_sample.gxvel[0]));
500 |     samples.gxvelR.push_back(float_or_nan(new_sample.gxvel[1]));
501 |   }
502 |   if (sample_attr_flag[11]){
503 |     samples.gyvelL.push_back(float_or_nan(new_sample.gyvel[0]));
504 |     samples.gyvelR.push_back(float_or_nan(new_sample.gyvel[1]));
505 |   }
506 |   if (sample_attr_flag[12]){
507 |     samples.hxvelL.push_back(float_or_nan(new_sample.hxvel[0]));
508 |     samples.hxvelR.push_back(float_or_nan(new_sample.hxvel[1]));
509 |   }
510 |   if (sample_attr_flag[13]){
511 |     samples.hyvelL.push_back(float_or_nan(new_sample.hyvel[0]));
512 |     samples.hyvelR.push_back(float_or_nan(new_sample.hyvel[1]));
513 |   }
514 |   if (sample_attr_flag[14]){
515 |     samples.rxvelL.push_back(float_or_nan(new_sample.rxvel[0]));
516 |     samples.rxvelR.push_back(float_or_nan(new_sample.rxvel[1]));
517 |   }
518 |   if (sample_attr_flag[15]){
519 |     samples.ryvelL.push_back(float_or_nan(new_sample.ryvel[0]));
520 |     samples.ryvelR.push_back(float_or_nan(new_sample.ryvel[1]));
521 |   }
522 |   if (sample_attr_flag[16]){
523 |     samples.fgxvelL.push_back(float_or_nan(new_sample.fgxvel[0]));
524 |     samples.fgxvelR.push_back(float_or_nan(new_sample.fgxvel[1]));
525 |   }
526 |   if (sample_attr_flag[17]){
527 |     samples.fgyvelL.push_back(float_or_nan(new_sample.fgyvel[0]));
528 |     samples.fgyvelR.push_back(float_or_nan(new_sample.fgyvel[1]));
529 |   }
530 |   if (sample_attr_flag[18]){
531 |     samples.fhxvelL.push_back(float_or_nan(new_sample.fhxvel[0]));
532 |     samples.fhxvelR.push_back(float_or_nan(new_sample.fhxvel[1]));
533 |   }
534 |   if (sample_attr_flag[19]){
535 |     samples.fhyvelL.push_back(float_or_nan(new_sample.fhyvel[0]));
536 |     samples.fhyvelR.push_back(float_or_nan(new_sample.fhyvel[1]));
537 |   }
538 |   if (sample_attr_flag[20]){
539 |     samples.frxvelL.push_back(float_or_nan(new_sample.frxvel[0]));
540 |     samples.frxvelR.push_back(float_or_nan(new_sample.frxvel[1]));
541 |   }
542 |   if (sample_attr_flag[21]){
543 |     samples.fryvelL.push_back(float_or_nan(new_sample.fryvel[0]));
544 |     samples.fryvelR.push_back(float_or_nan(new_sample.fryvel[1]));
545 |   }
546 |   if (sample_attr_flag[22]){
547 |     samples.hdata_1.push_back(new_sample.hdata[0]);
548 |     samples.hdata_2.push_back(new_sample.hdata[1]);
549 |     samples.hdata_3.push_back(new_sample.hdata[2]);
550 |     samples.hdata_4.push_back(new_sample.hdata[3]);
551 |     samples.hdata_5.push_back(new_sample.hdata[4]);
552 |     samples.hdata_6.push_back(new_sample.hdata[5]);
553 |     samples.hdata_7.push_back(new_sample.hdata[6]);
554 |     samples.hdata_8.push_back(new_sample.hdata[7]);
555 |   }
556 |   if (sample_attr_flag[23]){
557 |     samples.flags.push_back(new_sample.flags);
558 |   }
559 |   if (sample_attr_flag[24]){
560 |     samples.input.push_back(new_sample.input);
561 |   }
562 |   if (sample_attr_flag[25]){
563 |     samples.buttons.push_back(new_sample.buttons);
564 |   }
565 |   if (sample_attr_flag[26]){
566 |     samples.htype.push_back(new_sample.htype);
567 |   }
568 |   if (sample_attr_flag[27]){
569 |     samples.errors.push_back(new_sample.errors);
570 |   }
571 | }
572 | 
573 | 
574 | // Internal function that reads EDF file
575 | //
576 | //' @title Internal function that reads EDF file
577 | //' @description Reads EDF file into a list that contains events, samples, and recordings.
578 | //' DO NOT call this function directly. Instead, use read_edf function that implements
579 | //' parameter checks and additional postprocessing.
580 | //' @param std::string filename, full name of the EDF file
581 | //' @param int consistency, consistency check control (for the time stamps of the start
582 | //' and end events, etc). 0, no consistency check. 1, check consistency and report.
583 | //' 2, check consistency and fix.
584 | //' @param bool import_events, load/skip loading events.
585 | //' @param bool import_recordings, load/skip loading recordings.
586 | //' @param bool import_samples, load/skip loading of samples.
587 | //' @param LogicalVector sample_attr_flag, boolean vector that indicates which sample fields are to be stored
588 | //' @param std::string start_marker_string, event that marks trial start. Defaults to "TRIALID", if empty.
589 | //' @param std::string end_marker_string, event that marks trial end
590 | //' @param verbose, whether to show progressbar and report number of trials
591 | //' @export
592 | //' @keywords internal
593 | //' @return List, contents of the EDF file. Please see read_edf for details.
594 | //[[Rcpp::export]]
595 | List read_edf_file(std::string filename,
596 |                    int consistency,
597 |                    bool import_events,
598 |                    bool import_recordings,
599 |                    bool import_samples,
600 |                    LogicalVector sample_attr_flag,
601 |                    std::string start_marker_string,
602 |                    std::string end_marker_string,
603 |                    bool verbose){
604 |   // data storage
605 |   TRIAL_EVENTS all_events;
606 |   TRIAL_SAMPLES all_samples;
607 |   TRIAL_RECORDINGS all_recordings;
608 | 
609 |   // collecting all message before the first recording
610 |   // should contain service information, such as DISPLAY_COORDS
611 |   edfapi::EDFFILE* edfFile = safely_open_edf_file(filename, consistency, 1, 0);
612 |   for(bool keep_looking = true; keep_looking; ){
613 |     int DataType = edfapi::edf_get_next_data(edfFile);
614 |     edfapi::ALLF_DATA* current_data = edfapi::edf_get_float_data(edfFile);
615 |     switch(DataType){
616 |     case MESSAGEEVENT:
617 |       append_event(all_events, current_data->fe, 0, 0);
618 |       break;
619 |     case RECORDING_INFO:
620 |       // the recording has started, done with preliminaries
621 |       keep_looking = false;
622 |       break;
623 |     }
624 |   }
625 |   edfapi::edf_close_file(edfFile);
626 | 
627 | 
628 |   // opening the edf file to load info trial by trial
629 |   edfFile = safely_open_edf_file(filename, consistency, import_events, import_samples);
630 | 
631 |   // set the trial navigation up
632 |   set_trial_navigation_up(edfFile, start_marker_string, end_marker_string);
633 | 
634 |   // figure out, just how many trials we have
635 |   unsigned int total_trials = edfapi::edf_get_trial_count(edfFile);
636 |   if (verbose){
637 |     ::Rprintf("Trials count: %d\n", total_trials);
638 |   }
639 | 
640 |   // creating headers, events, and samples
641 |   NumericMatrix trial_headers = prepare_trial_headers(total_trials);
642 | 
643 | 
644 |   // looping over the trials
645 |   Progress trial_counter(total_trials, verbose);
646 |   for(unsigned int iTrial = 0; iTrial< total_trials; iTrial++){
647 |     // visuals and interaction
648 |     if (verbose){
649 |       if (Progress::check_abort() ){
650 |         break;
651 |       }
652 |       trial_counter.increment();
653 |     }
654 | 
655 |     jump_to_trial(edfFile, iTrial);
656 | 
657 |     // read headers
658 |     read_trial_header(edfFile, trial_headers, iTrial);
659 | 
660 |     // read trial
661 |     edfapi::ALLF_DATA* current_data;
662 |     edfapi::UINT32 trial_start_time = trial_headers(iTrial, 2);
663 |     edfapi::UINT32 trial_end_time = trial_headers(iTrial, 3);
664 |     if (trial_end_time <= trial_start_time){
665 |       ::warning("Skipping trial %d due to zero or negative duration.", iTrial+1);
666 |       continue;
667 |     }
668 | 
669 |     bool TrialIsOver = false;
670 |     edfapi::UINT32 data_timestamp = 0;
671 |     for(int DataType = edfapi::edf_get_next_data(edfFile);
672 |         (DataType != NO_PENDING_ITEMS) && !TrialIsOver;
673 |         DataType = edfapi::edf_get_next_data(edfFile)){
674 | 
675 |       // obtaining next data piece
676 |       current_data = edfapi::edf_get_float_data(edfFile);
677 |       switch(DataType){
678 |       case SAMPLE_TYPE:
679 |         data_timestamp = current_data->fs.time;
680 |         if (import_samples){
681 |           append_sample(all_samples, current_data->fs, iTrial, trial_start_time, sample_attr_flag);
682 |         }
683 |         break;
684 | 
685 |       case STARTPARSE:
686 |       case ENDPARSE:
687 |       case BREAKPARSE:
688 |       case STARTBLINK:
689 |       case ENDBLINK:
690 |       case STARTSACC:
691 |       case ENDSACC:
692 |       case STARTFIX:
693 |       case ENDFIX:
694 |       case FIXUPDATE:
695 |       case MESSAGEEVENT:
696 |       case STARTSAMPLES:
697 |       case ENDSAMPLES:
698 |       case STARTEVENTS:
699 |       case ENDEVENTS:
700 |       case BUTTONEVENT:
701 |       case INPUTEVENT:
702 |       case LOST_DATA_EVENT:
703 |         data_timestamp = current_data->fe.sttime;
704 |         if (data_timestamp > trial_end_time)
705 |         {
706 |           TrialIsOver = true;
707 |           break;
708 |         }
709 |         if (import_events){
710 |           append_event(all_events, current_data->fe, iTrial + 1, trial_start_time);
711 |         }
712 |         break;
713 | 
714 |       case RECORDING_INFO:
715 |         data_timestamp = current_data->fe.time;
716 |         if (import_recordings){
717 |           append_recording(all_recordings, current_data->rec, iTrial, trial_start_time);
718 |         }
719 |         break;
720 |       case NO_PENDING_ITEMS:
721 |         break;
722 |       }
723 | 
724 |       // end of trial check
725 |       if (data_timestamp > trial_end_time)
726 |         break;
727 |     }
728 |   }
729 | 
730 |   // closing file
731 |   edfapi::edf_close_file(edfFile);
732 | 
733 |   // returning data
734 |   List edf_recording;
735 |   edf_recording["headers"] = trial_headers;
736 | 
737 |   // converting structure of vectors into a data frame
738 |   if (import_events){
739 |     DataFrame events;
740 |     events["trial"] = all_events.trial_index;
741 |     events["time"] = all_events.time;
742 |     events["type"] = all_events.type;
743 |     events["read"] = all_events.read;
744 |     events["sttime"] = all_events.sttime;
745 |     events["entime"] = all_events.entime;
746 |     events["sttime_rel"] = all_events.sttime_rel;
747 |     events["entime_rel"] = all_events.entime_rel;
748 |     events["hstx"] = all_events.hstx;
749 |     events["hsty"] = all_events.hsty;
750 |     events["gstx"] = all_events.gstx;
751 |     events["gsty"] = all_events.gsty;
752 |     events["sta"] = all_events.sta;
753 |     events["henx"] = all_events.henx;
754 |     events["heny"] = all_events.heny;
755 |     events["genx"] = all_events.genx;
756 |     events["geny"] = all_events.geny;
757 |     events["ena"] = all_events.ena;
758 |     events["havx"] = all_events.havx;
759 |     events["havy"] = all_events.havy;
760 |     events["gavx"] = all_events.gavx;
761 |     events["gavy"] = all_events.gavy;
762 |     events["ava"] = all_events.ava;
763 |     events["avel"] = all_events.avel;
764 |     events["pvel"] = all_events.pvel;
765 |     events["svel"] = all_events.svel;
766 |     events["evel"] = all_events.evel;
767 |     events["supd_x"] = all_events.supd_x;
768 |     events["eupd_x"] = all_events.eupd_x;
769 |     events["supd_y"] = all_events.supd_y;
770 |     events["eupd_y"] = all_events.eupd_y;
771 |     events["eye"] = all_events.eye;
772 |     events["status"] = all_events.status;
773 |     events["flags"] = all_events.flags;
774 |     events["input"] = all_events.input;
775 |     events["buttons"] = all_events.buttons;
776 |     events["parsedby"] = all_events.parsedby;
777 |     events["message"] = all_events.message;
778 |     edf_recording["events"] = events;
779 |   }
780 | 
781 |   if (import_recordings){
782 |     DataFrame recordings;
783 |     recordings["trial_index"] = all_recordings.trial_index;
784 |     recordings["time"] = all_recordings.time;
785 |     recordings["time_rel"] = all_recordings.time_rel;
786 |     recordings["sample_rate"] = all_recordings.sample_rate;
787 |     recordings["eflags"] = all_recordings.eflags;
788 |     recordings["sflags"] = all_recordings.sflags;
789 |     recordings["state"] = all_recordings.state;
790 |     recordings["record_type"] = all_recordings.record_type;
791 |     recordings["pupil_type"] = all_recordings.pupil_type;
792 |     recordings["recording_mode"] = all_recordings.recording_mode;
793 |     recordings["filter_type"] = all_recordings.filter_type;
794 |     recordings["pos_type"] = all_recordings.pos_type;
795 |     recordings["eye"] = all_recordings.eye;
796 |     edf_recording["recordings"] = recordings;
797 |   }
798 | 
799 |   if (import_samples){
800 |     DataFrame samples;
801 |     samples["trial"] = all_samples.trial_index;
802 |     samples["eye"] = all_samples.eye;
803 |     if (sample_attr_flag[0]){
804 |       samples["time"] = all_samples.time;
805 |       samples["time_rel"] = all_samples.time_rel;
806 |     }
807 |     if (sample_attr_flag[1]){
808 |       samples["pxL"] = all_samples.pxL;
809 |       samples["pxR"] = all_samples.pxR;
810 |     }
811 |     if (sample_attr_flag[2]){
812 |       samples["pyL"] = all_samples.pyL;
813 |       samples["pyR"] = all_samples.pyR;
814 |     }
815 |     if (sample_attr_flag[3]){
816 |       samples["hxL"] = all_samples.hxL;
817 |       samples["hxR"] = all_samples.hxR;
818 |     }
819 |     if (sample_attr_flag[4]){
820 |       samples["hyL"] = all_samples.hyL;
821 |       samples["hyR"] = all_samples.hyR;
822 |     }
823 |     if (sample_attr_flag[5]){
824 |       samples["paL"] = all_samples.paL;
825 |       samples["paR"] = all_samples.paR;
826 |     }
827 |     if (sample_attr_flag[6]){
828 |       samples["gxL"] = all_samples.gxL;
829 |       samples["gxR"] = all_samples.gxR;
830 |     }
831 |     if (sample_attr_flag[7]){
832 |       samples["gyL"] = all_samples.gyL;
833 |       samples["gyR"] = all_samples.gyR;
834 |     }
835 |     if (sample_attr_flag[8]){
836 |       samples["rx"] = all_samples.rx;
837 |     }
838 |     if (sample_attr_flag[9]){
839 |       samples["ry"] = all_samples.ry;
840 |     }
841 |     if (sample_attr_flag[10]){
842 |       samples["gxvelL"] = all_samples.gxvelL;
843 |       samples["gxvelR"] = all_samples.gxvelR;
844 |     }
845 |     if (sample_attr_flag[11]){
846 |       samples["gyvelL"] = all_samples.gyvelL;
847 |       samples["gyvelR"] = all_samples.gyvelR;
848 |     }
849 |     if (sample_attr_flag[12]){
850 |       samples["hxvelL"] = all_samples.hxvelL;
851 |       samples["hxvelR"] = all_samples.hxvelR;
852 |     }
853 |     if (sample_attr_flag[13]){
854 |       samples["hyvelL"] = all_samples.hyvelL;
855 |       samples["hyvelR"] = all_samples.hyvelR;
856 |     }
857 |     if (sample_attr_flag[14]){
858 |       samples["rxvelL"] = all_samples.rxvelL;
859 |       samples["rxvelR"] = all_samples.rxvelR;
860 |     }
861 |     if (sample_attr_flag[15]){
862 |       samples["ryvelL"] = all_samples.ryvelL;
863 |       samples["ryvelR"] = all_samples.ryvelR;
864 |     }
865 |     if (sample_attr_flag[16]){
866 |       samples["fgxvelL"] = all_samples.fgxvelL;
867 |       samples["fgxvelR"] = all_samples.fgxvelR;
868 |     }
869 |     if (sample_attr_flag[17]){
870 |       samples["fgyvelL"] = all_samples.fgyvelL;
871 |       samples["fgyvelR"] = all_samples.fgyvelR;
872 |     }
873 |     if (sample_attr_flag[18]){
874 |       samples["fhxvelL"] = all_samples.fhxvelL;
875 |       samples["fhxvelR"] = all_samples.fhxvelR;
876 |     }
877 |     if (sample_attr_flag[19]){
878 |       samples["fhyvelL"] = all_samples.fhyvelL;
879 |       samples["fhyvelR"] = all_samples.fhyvelR;
880 |     }
881 |     if (sample_attr_flag[20]){
882 |       samples["frxvelL"] = all_samples.frxvelL;
883 |       samples["frxvelR"] = all_samples.frxvelR;
884 |     }
885 |     if (sample_attr_flag[21]){
886 |       samples["fryvelL"] = all_samples.fryvelL;
887 |       samples["fryvelR"] = all_samples.fryvelR;
888 |     }
889 |     if (sample_attr_flag[22]){
890 |       samples["hdata_1"] = all_samples.hdata_1;
891 |       samples["hdata_2"] = all_samples.hdata_2;
892 |       samples["hdata_3"] = all_samples.hdata_3;
893 |       samples["hdata_4"] = all_samples.hdata_4;
894 |       samples["hdata_5"] = all_samples.hdata_5;
895 |       samples["hdata_6"] = all_samples.hdata_6;
896 |       samples["hdata_7"] = all_samples.hdata_7;
897 |       samples["hdata_8"] = all_samples.hdata_8;
898 |     }
899 |     if (sample_attr_flag[23]){
900 |       samples["flags"] = all_samples.flags;
901 |     }
902 |     if (sample_attr_flag[24]){
903 |       samples["input"] = all_samples.input;
904 |     }
905 |     if (sample_attr_flag[25]){
906 |       samples["buttons"] = all_samples.buttons;
907 |     }
908 |     if (sample_attr_flag[26]){
909 |       samples["htype"] = all_samples.htype;
910 |     }
911 |     if (sample_attr_flag[27]){
912 |       samples["errors"] = all_samples.errors;
913 |     }
914 |     edf_recording["samples"] = samples;
915 |   }
916 | 
917 |   edf_recording.attr("class") = "edf";
918 |   return (edf_recording);
919 | }
920 | 
921 | 


--------------------------------------------------------------------------------
/inst/extdata/example.edf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alexander-pastukhov/eyelinkReader/f041af9117ac14c954078b2871681207743d0fe4/inst/extdata/example.edf


--------------------------------------------------------------------------------
/man/adjust_message_time.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/adjust_message_time.R
 3 | \name{adjust_message_time}
 4 | \alias{adjust_message_time}
 5 | \alias{adjust_message_time.data.frame}
 6 | \alias{adjust_message_time.eyelinkRecording}
 7 | \title{Adjusts message time based on embedded text offset}
 8 | \usage{
 9 | adjust_message_time(object, prefix)
10 | 
11 | \method{adjust_message_time}{data.frame}(object, prefix = "^[-+]?[:digit:]+[:space:]+")
12 | 
13 | \method{adjust_message_time}{eyelinkRecording}(object, prefix = "^[-+]?[:digit:]+[:space:]+")
14 | }
15 | \arguments{
16 | \item{object}{An \code{\link{eyelinkRecording}} object or data.frame with events,
17 | i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.}
18 | 
19 | \item{prefix}{String with a regular expression that defines the offset.
20 | Defaults to \code{"^[-+]?[:digit:]+[:space:]+"} (a string starts with a positive
21 | or negative integer offset followed by a white space and the rest of the message).}
22 | }
23 | \value{
24 | Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
25 | with \emph{modified} \code{events} slot or a data.frame with offset-adjusted events.
26 | }
27 | \description{
28 | Uses text in the message to adjust its time. E.g.,
29 | for a message \code{"-50 TARGET_ONSET"} that was sent at \code{105600}
30 | the actual onset occurred 50 milliseconds earlier (\code{-50}). The function
31 | adjusts the event timing and removes the timing offset information from
32 | the message. I.e., the example message becomes \code{"TARGET_ONSET"} and
33 | its time become \code{105550}.
34 | }
35 | \examples{
36 | data(gaze)
37 | 
38 | # by passing events table
39 | adjusted_events <- adjust_message_time(gaze$events)
40 | 
41 | # by passing the recording
42 | gaze <- adjust_message_time(gaze)
43 | }
44 | 


--------------------------------------------------------------------------------
/man/check_consistency_flag.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/check_consistency_flag.R
 3 | \name{check_consistency_flag}
 4 | \alias{check_consistency_flag}
 5 | \title{Checks consistency flag, stops if invalid, returns code if valid.}
 6 | \usage{
 7 | check_consistency_flag(consistency)
 8 | }
 9 | \arguments{
10 | \item{consistency}{consistency check control for the time stamps of the start
11 | and end events, etc. Could be \code{'no consistency check'} (0),
12 | \code{'check consistency and report'} (1), \code{'check consistency and fix'} (2).}
13 | }
14 | \value{
15 | integer index
16 | }
17 | \description{
18 | Checks consistency flag, stops if invalid, returns code if valid.
19 | }
20 | \examples{
21 | check_consistency_flag('no consistency check')
22 | }
23 | \keyword{internal}
24 | 


--------------------------------------------------------------------------------
/man/check_logical_flag.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/check_logical_flag.R
 3 | \name{check_logical_flag}
 4 | \alias{check_logical_flag}
 5 | \title{Checks for validity of a logical flag, stops if not valid}
 6 | \usage{
 7 | check_logical_flag(logical_flag)
 8 | }
 9 | \arguments{
10 | \item{logical_flag}{Logical scalar}
11 | }
12 | \value{
13 | logical, value of the logical_flag
14 | }
15 | \description{
16 | Checks for validity of a logical flag, stops if not valid
17 | }
18 | \examples{
19 | import_samples <- TRUE
20 | check_logical_flag(import_samples)
21 | }
22 | \keyword{internal}
23 | 


--------------------------------------------------------------------------------
/man/check_string_parameter.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/check_string_parameter.R
 3 | \name{check_string_parameter}
 4 | \alias{check_string_parameter}
 5 | \title{Checks for validity of a string parameter, stops if not valid}
 6 | \usage{
 7 | check_string_parameter(string_parameter)
 8 | }
 9 | \arguments{
10 | \item{string_parameter}{String scalar}
11 | }
12 | \value{
13 | character, value of the string_parameter
14 | }
15 | \description{
16 | Checks for validity of a string parameter, stops if not valid
17 | }
18 | \examples{
19 | start_marker <- "TRIALID"
20 | check_string_parameter(start_marker)
21 | }
22 | \keyword{internal}
23 | 


--------------------------------------------------------------------------------
/man/check_that_compiled.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/check_that_compiled.R
 3 | \name{check_that_compiled}
 4 | \alias{check_that_compiled}
 5 | \title{Checks whether EDF API library was present and
 6 | interface was successfully be compiled}
 7 | \usage{
 8 | check_that_compiled(fail_loudly = TRUE)
 9 | }
10 | \arguments{
11 | \item{fail_loudly}{logical, whether lack of compiled library means
12 | error (\code{TRUE}), just warning (\code{FALSE}), or silent (\code{NA},
13 | for test use only).}
14 | }
15 | \value{
16 | No return value. Stops the computation, if compiled interface to EDF API in missing.
17 | }
18 | \description{
19 | Checks whether EDF API library was present and
20 | interface was successfully be compiled
21 | }
22 | \examples{
23 | check_that_compiled(fail_loudly = FALSE)
24 | }
25 | \keyword{internal}
26 | 


--------------------------------------------------------------------------------
/man/compiled_library_status.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/RcppExports.R
 3 | \name{compiled_library_status}
 4 | \alias{compiled_library_status}
 5 | \title{Status of compiled library}
 6 | \usage{
 7 | compiled_library_status()
 8 | }
 9 | \value{
10 | logical
11 | }
12 | \description{
13 | Return status of compiled library
14 | }
15 | \examples{
16 | compiled_library_status()
17 | }
18 | 


--------------------------------------------------------------------------------
/man/compute_cyclopean_samples.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/compute_cyclopean_samples.R
 3 | \name{compute_cyclopean_samples}
 4 | \alias{compute_cyclopean_samples}
 5 | \alias{compute_cyclopean_samples.data.frame}
 6 | \alias{compute_cyclopean_samples.eyelinkRecording}
 7 | \title{Computes cyclopean samples by averaging over binocular data}
 8 | \usage{
 9 | compute_cyclopean_samples(object, fun = mean)
10 | 
11 | \method{compute_cyclopean_samples}{data.frame}(object, fun = mean)
12 | 
13 | \method{compute_cyclopean_samples}{eyelinkRecording}(object, fun = mean)
14 | }
15 | \arguments{
16 | \item{object}{Either an \code{\link{eyelinkRecording}} object or data.frame with samples,
17 | i.e., \code{samples} slot of the \code{\link{eyelinkRecording}} object.}
18 | 
19 | \item{fun}{Function used to average across eyes, defaults to \code{\link{mean}}.}
20 | }
21 | \value{
22 | Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
23 | with \emph{modified} \code{samples} slot or a data.frame with cyclopean samples.
24 | }
25 | \description{
26 | Computes cyclopean samples by averaging over binocular recorded properties
27 | such as \code{pxL}/\code{pxR}, \code{pyL}/\code{pyR}, \code{hxL}/\code{hxR},
28 | etc. Uses function specified via \code{fun}
29 | parameter to compute the average with \code{na.rm = TRUE} option.
30 | In case of a monocular recording or when the information from one eye missing,
31 | uses information from one eye only, ignoring the other column.
32 | In both binocular and monocular recording cases, simplifies column names
33 | so that \code{pxL} and/or \code{pxR} are replaced
34 | with a single column \code{px}, \code{pyL}/\code{pyR} with \code{py}, etc.
35 | }
36 | \examples{
37 | data(gaze)
38 | 
39 | # by passing samples table
40 | cyclopean_samples <- compute_cyclopean_samples(gaze$samples)
41 | 
42 | # storing cyclopean samples as a separate table in recording
43 | gaze$cyclopean_samples <- compute_cyclopean_samples(gaze$samples)
44 | 
45 | # by passing the recording, cyclopean samples replace original ones
46 | gaze <- compute_cyclopean_samples(gaze)
47 | }
48 | 


--------------------------------------------------------------------------------
/man/convert_NAs.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/RcppExports.R
 3 | \name{convert_NAs}
 4 | \alias{convert_NAs}
 5 | \title{Convert -32767 (missing info) to NA}
 6 | \usage{
 7 | convert_NAs(original_frame)
 8 | }
 9 | \arguments{
10 | \item{original_frame}{data.frame to be processed}
11 | }
12 | \value{
13 | processed data.frame
14 | }
15 | \description{
16 | Converts all -32767 (smallest INT16  value indicating missing info) to NA.
17 | You don't need to call this function directly, as it is automatically evoked within
18 | \code{\link{read_edf}} function.
19 | }
20 | \examples{
21 | \donttest{
22 |   data(gaze)
23 |   gaze$samples <- convert_NAs(gaze$samples)
24 | }
25 | }
26 | 


--------------------------------------------------------------------------------
/man/convert_header_codes.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/convert_codes.R
 3 | \name{convert_header_codes}
 4 | \alias{convert_header_codes}
 5 | \title{Converts integer constants in trial headers to factor with explicit labels}
 6 | \usage{
 7 | convert_header_codes(trial_headers)
 8 | }
 9 | \arguments{
10 | \item{trial_headers}{data.frame that contains trial headers.}
11 | }
12 | \value{
13 | a modified trial_headers table
14 | }
15 | \description{
16 | Converts integer constants in trial headers to factor with explicit labels.
17 | Please refer to EDF API manual for further details.
18 | }
19 | \keyword{internal}
20 | 


--------------------------------------------------------------------------------
/man/convert_recording_codes.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/convert_codes.R
 3 | \name{convert_recording_codes}
 4 | \alias{convert_recording_codes}
 5 | \title{Converts integer constants in recordings to factor with explicit labels}
 6 | \usage{
 7 | convert_recording_codes(trial_recordings)
 8 | }
 9 | \arguments{
10 | \item{trial_recordings}{data.frame that contains trial recordings.}
11 | }
12 | \value{
13 | a modified trial_recordings table
14 | }
15 | \description{
16 | Converts integer constants in trial recordings information to factor with explicit labels.
17 | Please refer to EDF API manual for further details.
18 | }
19 | \keyword{internal}
20 | 


--------------------------------------------------------------------------------
/man/dot-onAttach.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/zzz.R
 3 | \name{.onAttach}
 4 | \alias{.onAttach}
 5 | \title{Check if the library was compiled}
 6 | \usage{
 7 | .onAttach(libname, pkgname)
 8 | }
 9 | \arguments{
10 | \item{libname}{character}
11 | 
12 | \item{pkgname}{character}
13 | }
14 | \value{
15 | No return value, called to check and warn if compiled EDF API interface is missing.
16 | }
17 | \description{
18 | Check if the library was compiled
19 | }
20 | \keyword{internal}
21 | 


--------------------------------------------------------------------------------
/man/dot-onLoad.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/zzz.R
 3 | \name{.onLoad}
 4 | \alias{.onLoad}
 5 | \title{Compiles the library linking it to EDF API}
 6 | \usage{
 7 | .onLoad(libname, pkgname)
 8 | }
 9 | \arguments{
10 | \item{libname}{character}
11 | 
12 | \item{pkgname}{character}
13 | }
14 | \value{
15 | No return value, called to compile EDF API interface.
16 | }
17 | \description{
18 | Compiles the library linking it to EDF API
19 | }
20 | \keyword{internal}
21 | 


--------------------------------------------------------------------------------
/man/extract_AOIs.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/extract_aois.R
 3 | \name{extract_AOIs}
 4 | \alias{extract_AOIs}
 5 | \alias{extract_AOIs.data.frame}
 6 | \alias{extract_AOIs.eyelinkRecording}
 7 | \title{Extracts rectangular areas of interest (AOI)}
 8 | \usage{
 9 | extract_AOIs(object)
10 | 
11 | \method{extract_AOIs}{data.frame}(object)
12 | 
13 | \method{extract_AOIs}{eyelinkRecording}(object)
14 | }
15 | \arguments{
16 | \item{object}{Either an \code{\link{eyelinkRecording}} object or data.frame with events,
17 | i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.}
18 | }
19 | \value{
20 | Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
21 | with an additional \code{AOIs} slot or a data.frame with AOIs' information. See
22 | \code{\link{eyelinkRecording}} for details.
23 | }
24 | \description{
25 | Extracts rectangular areas of interest (AOI),
26 | as defined by \code{"!V IAREA RECTANGLE"} command.
27 | Specifically, we expect it to be in format
28 | \code{!V IAREA RECTANGLE <index> <left> <top> <right> <bottom> <label>},
29 | where \code{<label>} is a string label and all other variables are integer.
30 | Please note that due to a non-standard nature of this function \strong{is not} called
31 | during the \code{\link{read_edf}} call and you need to call it separately.
32 | }
33 | \examples{
34 | data(gaze)
35 | 
36 | # by passing the recording
37 | gaze <- extract_AOIs(gaze)
38 | 
39 | # by passing events table
40 | AOIs <- extract_AOIs(gaze$events)
41 | }
42 | 


--------------------------------------------------------------------------------
/man/extract_blinks.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/extract_blinks.R
 3 | \name{extract_blinks}
 4 | \alias{extract_blinks}
 5 | \alias{extract_blinks.data.frame}
 6 | \alias{extract_blinks.eyelinkRecording}
 7 | \title{Extract blinks}
 8 | \usage{
 9 | extract_blinks(object)
10 | 
11 | \method{extract_blinks}{data.frame}(object)
12 | 
13 | \method{extract_blinks}{eyelinkRecording}(object)
14 | }
15 | \arguments{
16 | \item{object}{Either an \code{\link{eyelinkRecording}} object or data.frame with events,
17 | i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.}
18 | }
19 | \value{
20 | Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
21 | with an additional \code{blinks} slot or a data.frame with blinks' information. See
22 | \code{\link{eyelinkRecording}} for details.
23 | }
24 | \description{
25 | Extracts blinks from the \code{events} table of the \code{\link{eyelinkRecording}} object.. Normally,
26 | you don't need to call this function yourself,
27 | as it is called during the \code{\link{read_edf}} with default settings
28 | (\emph{e.g.}, \code{import_blinks = TRUE}).
29 | }
30 | \examples{
31 | data(gaze)
32 | 
33 | # by passing the recording
34 | gaze <- extract_blinks(gaze)
35 | 
36 | # by passing events table
37 | blinks <- extract_blinks(gaze$events)
38 | }
39 | \seealso{
40 | read_edf, eyelinkRecording
41 | }
42 | 


--------------------------------------------------------------------------------
/man/extract_display_coords.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/extract_display_coords.R
 3 | \name{extract_display_coords}
 4 | \alias{extract_display_coords}
 5 | \alias{extract_display_coords.data.frame}
 6 | \alias{extract_display_coords.eyelinkRecording}
 7 | \title{Extract display coordinates from an event message}
 8 | \usage{
 9 | extract_display_coords(
10 |   object,
11 |   message_prefix = "DISPLAY_COORDS",
12 |   silent = FALSE
13 | )
14 | 
15 | \method{extract_display_coords}{data.frame}(
16 |   object,
17 |   message_prefix = "DISPLAY_COORDS",
18 |   silent = FALSE
19 | )
20 | 
21 | \method{extract_display_coords}{eyelinkRecording}(
22 |   object,
23 |   message_prefix = "DISPLAY_COORDS",
24 |   silent = FALSE
25 | )
26 | }
27 | \arguments{
28 | \item{object}{Either an \code{\link{eyelinkRecording}} object or data.frame with events,
29 | i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.}
30 | 
31 | \item{message_prefix}{Beginning of the message string that identifies the DISPLAY_COORDS message.
32 | Defaults to \code{"DISPLAY_COORDS"}.}
33 | 
34 | \item{silent}{Whether to suppress a warning when DISPLAY_COORDS message is missing. Default to \code{FALSE}.}
35 | }
36 | \value{
37 | A \code{\link{eyelinkRecording}} object with an additional \code{display_coords} slot (if that was \code{object} type),
38 | Either a four element numeric vector with display coordinates, or \code{NULL} if \code{object} was an \code{events} table of
39 | \code{\link{eyelinkRecording}} object. See \code{\link{eyelinkRecording}} for details.
40 | }
41 | \description{
42 | Extracts display coordinates from a message that adheres to a
43 | \code{<message_prefix> <label>} format. Please note that this function called
44 | during the \code{\link{read_edf}} call with \code{silent = TRUE}. If \code{display_coords}
45 | are missing from the \code{\link{eyelinkRecording}}, run this method to see the warnings.
46 | }
47 | \examples{
48 | data(gaze)
49 | 
50 | # by passing the recording
51 | gaze <- extract_display_coords(gaze)
52 | 
53 | # by passing events table
54 | display_coords <- extract_display_coords(gaze$events)
55 | }
56 | \seealso{
57 | read_edf, eyelinkRecording
58 | }
59 | 


--------------------------------------------------------------------------------
/man/extract_fixations.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/extract_fixations.R
 3 | \name{extract_fixations}
 4 | \alias{extract_fixations}
 5 | \alias{extract_fixations.data.frame}
 6 | \alias{extract_fixations.eyelinkRecording}
 7 | \title{Extract fixations}
 8 | \usage{
 9 | extract_fixations(object)
10 | 
11 | \method{extract_fixations}{data.frame}(object)
12 | 
13 | \method{extract_fixations}{eyelinkRecording}(object)
14 | }
15 | \arguments{
16 | \item{object}{Either an \code{\link{eyelinkRecording}} object or data.frame with events,
17 | i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.}
18 | }
19 | \value{
20 | Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
21 | with an additional \code{fixations} slot or a data.frame with fixations' information. See
22 | \code{\link{eyelinkRecording}} for details.
23 | }
24 | \description{
25 | Extracts fixations from the \code{events} table of the \code{\link{eyelinkRecording}} object.
26 | Normally, you don't need to call this function yourself,
27 | as it is called during the \code{\link{read_edf}} with default settings
28 | (\emph{e.g.}, \code{import_fixations = TRUE}).
29 | }
30 | \examples{
31 | data(gaze)
32 | 
33 | # by passing the recording
34 | gaze <- extract_fixations(gaze)
35 | 
36 | # by passing events table
37 | fixations <- extract_fixations(gaze$events)
38 | }
39 | \seealso{
40 | read_edf, eyelinkRecording
41 | }
42 | 


--------------------------------------------------------------------------------
/man/extract_saccades.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/extract_saccades.R
 3 | \name{extract_saccades}
 4 | \alias{extract_saccades}
 5 | \alias{extract_saccades.data.frame}
 6 | \alias{extract_saccades.eyelinkRecording}
 7 | \title{Extract saccades from recorded events}
 8 | \usage{
 9 | extract_saccades(object)
10 | 
11 | \method{extract_saccades}{data.frame}(object)
12 | 
13 | \method{extract_saccades}{eyelinkRecording}(object)
14 | }
15 | \arguments{
16 | \item{object}{Either an \code{\link{eyelinkRecording}} object or data.frame with events,
17 | i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.}
18 | }
19 | \value{
20 | Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
21 | with an additional \code{saccades} slot or a data.frame with saccades' information. See
22 | \code{\link{eyelinkRecording}} for details.
23 | }
24 | \description{
25 | Extract saccades from the \code{events} table of the \code{\link{eyelinkRecording}} object.
26 | Normally, you don't need to call this function yourself,
27 | as it is called during the \code{\link{read_edf}} with default
28 | settings (\emph{e.g.}, \code{import_saccades = TRUE}).
29 | }
30 | \examples{
31 | data(gaze)
32 | 
33 | # by passing the recording
34 | gaze <- extract_saccades(gaze)
35 | 
36 | # by passing events table
37 | saccades <- extract_saccades(gaze$events)
38 | }
39 | \seealso{
40 | read_edf, eyelinkRecording
41 | }
42 | 


--------------------------------------------------------------------------------
/man/extract_triggers.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/extract_triggers.R
 3 | \name{extract_triggers}
 4 | \alias{extract_triggers}
 5 | \alias{extract_triggers.data.frame}
 6 | \alias{extract_triggers.eyelinkRecording}
 7 | \title{Extract triggers, a custom message type}
 8 | \usage{
 9 | extract_triggers(object, message_prefix = "TRIGGER")
10 | 
11 | \method{extract_triggers}{data.frame}(object, message_prefix = "TRIGGER")
12 | 
13 | \method{extract_triggers}{eyelinkRecording}(object, message_prefix = "TRIGGER")
14 | }
15 | \arguments{
16 | \item{object}{Either an \code{\link{eyelinkRecording}} object or data.frame with events,
17 | i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.}
18 | 
19 | \item{message_prefix}{Beginning of the message string that identifies trigger messages.
20 | Defaults to \code{"TRIGGER"}.}
21 | }
22 | \value{
23 | Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
24 | with an additional \code{triggers} slot or a data.frame with triggers' information. See
25 | \code{\link{eyelinkRecording}} for details.
26 | }
27 | \description{
28 | Extracts trigger events, messages that adhere to a
29 | \code{<message_prefix> <label>} format. Their purpose is to identify the time
30 | instance of specific interest.
31 | Please note that due to a non-standard nature of this function \strong{is not} called
32 | during the \code{\link{read_edf}} call and you need to call it separately.
33 | }
34 | \examples{
35 | data(gaze)
36 | 
37 | # by passing the recording
38 | gaze <- extract_triggers(gaze)
39 | 
40 | # by passing events table
41 | triggers <- extract_triggers(gaze$events)
42 | 
43 | # with an explicit message prefix
44 | triggers <- extract_triggers(gaze$events, "TRIGGER")
45 | }
46 | \seealso{
47 | read_edf, eyelinkRecording
48 | }
49 | 


--------------------------------------------------------------------------------
/man/extract_variables.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/extract_variables.R
 3 | \name{extract_variables}
 4 | \alias{extract_variables}
 5 | \alias{extract_variables.data.frame}
 6 | \alias{extract_variables.eyelinkRecording}
 7 | \title{Extract variables}
 8 | \usage{
 9 | extract_variables(object)
10 | 
11 | \method{extract_variables}{data.frame}(object)
12 | 
13 | \method{extract_variables}{eyelinkRecording}(object)
14 | }
15 | \arguments{
16 | \item{object}{Either an \code{\link{eyelinkRecording}} object or data.frame with events,
17 | i.e., \code{events} slot of the \code{\link{eyelinkRecording}} object.}
18 | }
19 | \value{
20 | Object of the same time as input, i.e., either a \code{\link{eyelinkRecording}} object
21 | with an additional \code{variables} slot or a data.frame with variables' information. See
22 | \code{\link{eyelinkRecording}} for details.
23 | }
24 | \description{
25 | Extracts variables from the \code{events} table of the \code{\link{eyelinkRecording}} object.
26 | Normally, you don't need to call this function yourself,
27 | as it is called during the \code{\link{read_edf}} with default settings
28 | (\emph{e.g.}, \code{import_variables = TRUE}).
29 | }
30 | \examples{
31 | data(gaze)
32 | 
33 | # by passing the recording
34 | gaze <- extract_variables(gaze)
35 | 
36 | # by passing events table
37 | variables <- extract_variables(gaze$events)
38 | }
39 | \seealso{
40 | read_edf, eyelinkRecording
41 | }
42 | 


--------------------------------------------------------------------------------
/man/eyelinkReader.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/eyelinkReader-package.R
 3 | \docType{package}
 4 | \name{eyelinkReader}
 5 | \alias{eyelinkReader-package}
 6 | \alias{eyelinkReader}
 7 | \title{eyelinkReader: Import Gaze Data for EyeLink Eye Tracker}
 8 | \description{
 9 | Imports gaze data recorded by a SR Research EyeLink eye tracker from an EDF file.
10 | Includes options to import events and/or recorded samples and extract
11 | individual events such as saccades, fixations, blinks, and recorded variables.
12 | }
13 | \seealso{
14 | Useful links:
15 | \itemize{
16 |   \item \url{https://github.com/alexander-pastukhov/eyelinkReader/}
17 |   \item \url{https://alexander-pastukhov.github.io/eyelinkReader/}
18 |   \item Report bugs at \url{https://github.com/alexander-pastukhov/eyelinkReader/issues}
19 | }
20 | 
21 | }
22 | \author{
23 | \strong{Maintainer}: Alexander Pastukhov \email{pastukhov.alexander@gmail.com} (\href{https://orcid.org/0000-0002-8738-8591}{ORCID})
24 | 
25 | }
26 | 


--------------------------------------------------------------------------------
/man/eyelinkRecording-class.Rd:
--------------------------------------------------------------------------------
  1 | % Generated by roxygen2: do not edit by hand
  2 | % Please edit documentation in R/eyelinkReader-classes.R
  3 | \docType{class}
  4 | \name{eyelinkRecording-class}
  5 | \alias{eyelinkRecording-class}
  6 | \alias{eyelinkRecording}
  7 | \title{Class \code{eyelinkRecording}.}
  8 | \description{
  9 | S3 class containing information imported from an edf-file.
 10 | }
 11 | \details{
 12 | See \code{methods(class = "eyelinkRecording")} for an overview of available methods.
 13 | }
 14 | \section{Slots}{
 15 | 
 16 | \describe{
 17 | \item{\code{preamble}}{A preamble of the recording, see also \code{\link{read_preamble}}.}
 18 | 
 19 | \item{\code{events}}{Events table which is a collection of all \code{FEVENT} imported from the EDF file. See description below.}
 20 | 
 21 | \item{\code{samples}}{Samples table  which is a collection of all \code{FSAMPLE} imported from the EDF file. See description below.}
 22 | 
 23 | \item{\code{headers}}{Headers of the individual trials, see description below.}
 24 | 
 25 | \item{\code{recordings}}{Individual recording start/end information, see description below.}
 26 | 
 27 | \item{\code{display_coords}}{Recorded screen coordinates (if recorded), see \code{\link{extract_display_coords}}.}
 28 | 
 29 | \item{\code{saccades}}{Saccades extracted from \code{events}, see description below and \code{\link{extract_saccades}}.}
 30 | 
 31 | \item{\code{fixations}}{Fixations extracted from \code{events}, see description below and \code{\link{extract_fixations}}.}
 32 | 
 33 | \item{\code{blinks}}{Blinks extracted from \code{events}, see description below and \code{\link{extract_blinks}}.}
 34 | 
 35 | \item{\code{variables}}{Recorded variables extracted from \code{events}, see description below and \code{\link{extract_variables}}.}
 36 | 
 37 | \item{\code{triggers}}{Events messages that adhere to a \code{TRIGGER <label>} format.
 38 | This is a \bold{non-standard message} that the package author uses to mark events like onsets or offsets,
 39 | similar to how it is done in M/EEG. See description below and \code{\link{extract_triggers}}.}
 40 | 
 41 | \item{\code{AOIs}}{Areas of interest events. See description below and \code{\link{extract_AOIs}}.}
 42 | }}
 43 | 
 44 | \section{Events}{
 45 | 
 46 | Events table which is a collection of all \code{FEVENT} imported from the EDF file.
 47 | Column descriptions were copied directly  from the \emph{EDF access C API manual}.
 48 | Please refer to that manual for further details. Additional non-standard fields are marked in bold.
 49 | \itemize{
 50 | \item \strong{\code{trial}} Trial index, starts at 1.
 51 | \item \code{time} Time of event.
 52 | \item \code{type} Event type.
 53 | \item \code{read} Flags which items were included.
 54 | \item \code{sttime} Start time of the event.
 55 | \item \code{entime} End time of the event.
 56 | \item \strong{\code{sttime_rel}} Start time of the event, relative to the start time of the trial.
 57 | \item \strong{\code{entime_rel}} End time of the event, relative to the start time of the trial.
 58 | \item \code{hstx}, \code{hsty} Head reference starting points.
 59 | \item \code{gstx}, \code{gsty} Gaze starting points.
 60 | \item \code{sta} Pupil size at start.
 61 | \item \code{henx}, \code{heny} Headref ending points.
 62 | \item \code{genx}, \code{geny} Gaze ending points.
 63 | \item \code{ena} Pupil size at end.
 64 | \item \code{havx}, \code{havy} Headref averages.
 65 | \item \code{gavx}, \code{gavy} Gaze averages.
 66 | \item \code{ava} Average pupil size.
 67 | \item \code{avel} Accumulated average velocity.
 68 | \item \code{pvel} Accumulated peak velocity.
 69 | \item \code{svel} Start velocity.
 70 | \item \code{evel} End velocity.
 71 | \item \code{supd_x}, \code{supd_y} Start units-per-degree.
 72 | \item \code{eupd_x}, \code{eupd_y} End units-per-degree.
 73 | \item \code{eye} Either \code{'LEFT'} (0) or \code{'RIGHT'} (1).
 74 | \item \code{status} Error, warning flags.
 75 | \item \code{flags} Flags to indicate contents.
 76 | \item \code{input} Extra (input word).
 77 | \item \code{buttons} Button state and changes.
 78 | \item \code{parsedby} 7 bits of flags, PARSEDBY codes.
 79 | \item \code{message} Any message string.
 80 | }
 81 | }
 82 | 
 83 | \section{Samples}{
 84 | 
 85 | Samples table which is a collection of all \code{FSAMPLE} imported from the EDF file.
 86 | Please note that \code{\link{read_edf}} parameters determines which fields are imported.
 87 | Column descriptions were copied directly  from the \emph{EDF access C API manual}.
 88 | Please refer to that manual for further details. Suffixes \code{L} and \code{R} denote left and right eye.
 89 | Non-standard additional fields are marked in bold.
 90 | \itemize{
 91 | \item \strong{\code{trial}} Trial index, starts at 1.
 92 | \item \strong{\code{eye}} \code{'LEFT'} (0), \code{'RIGHT'} (1), or \code{'BINOCULAR'} (2).
 93 | \item \code{time} Time of sample.
 94 | \item \strong{\code{time_rel}} Time relative to the start of the trial.
 95 | \item \code{pxL}, \code{pxR}, \code{pyL}, \code{pyR} Pupil coordinates.
 96 | \item \code{hxL}, \code{hxR}, \code{hyL}, \code{hyR} Headref coordinates.
 97 | \item \code{paL}, \code{paR} Pupil size or area.
 98 | \item \code{gxL}, \code{gxR}, \code{gyL}, \code{gyR} Screen gaze coordinates.
 99 | \item \code{rx}, \code{ry} Screen pixels per degree.
100 | \item \code{gxvelL}, \code{gxvelR}, \code{gyvelL}, \code{gyvelR} Gaze velocity.
101 | \item \code{hxvelL}, \code{hxvelR}, \code{hyvelL}, \code{hyvelR} Headref velocity.
102 | \item \code{rxvelL}, \code{rxvelR}, \code{ryvelL}, \code{ryvelR} Raw velocity.
103 | \item \code{fgxvelL}, \code{fgxvelR}, \code{fgyvelL}, \code{fgyvelR} Fast gaze velocity.
104 | \item \code{fhxvelL}, \code{fhxvelR}, \code{fhyvelL}, \code{fhyvelR} Fast headref velocity.
105 | \item \code{frxvelL}, \code{frxvelR}, \code{fryvelL}, \code{fryvelR} Fast raw velocity.
106 | \item \code{hdata_1} -\code{hdata_8} Head-tracker data (not pre-scaled). Each column correspond to a single element of the \code{INT16 FSAMPLE::hdata[8]}.
107 | \item \code{flags} Flags to indicate contents.
108 | \item \code{input} Extra (input word).
109 | \item \code{buttons} Button state & changes.
110 | \item \code{htype} Head-tracker data type (0=none).
111 | \item \code{errors} Process error flags.
112 | }
113 | }
114 | 
115 | \section{Headers}{
116 | 
117 | Trial headers table which is a collection of all \code{TRIAL} structures imported from the EDF file.
118 | Column descriptions were copied directly  from the \emph{EDF access C API manual}.
119 | Please refer to that manual for further details.
120 | All fields of the \code{RECORDINGS} structure are prefixed with \code{rec_}.
121 | Non-standard additional fields are marked in bold.
122 | \itemize{
123 | \item \strong{\code{trial}} Trial index.
124 | \item \code{duration} Duration of the trial.
125 | \item \code{starttime} Start time of the trial.
126 | \item \code{endtime} End time of the trial.
127 | \item \code{rec_time} Start time or end time.
128 | \item \code{rec_sample rate} Sample rate in Hz: 250, 500, 1000 or 2000.
129 | \item \code{rec_eflags} Extra information about events.
130 | \item \code{rec_sflags} Extra information about samples.
131 | \item \code{rec_state} \code{'START'} (2) or \code{'END'} (1).
132 | \item \code{rec_record_type} \code{'SAMPLES'} (1), \code{'EVENTS'} (2), or \code{'SAMPLES and EVENTS'} (3).
133 | \item \code{rec_pupil_type} \code{'AREA'} (0) or \code{'DIAMETER'} (1).
134 | \item \code{rec_recording_mode} \code{'PUPIL'} (0) or \code{'CR'} (1).
135 | \item \code{rec_filter_type} 1, 2, or 3.
136 | \item \code{rec_pos_type} Should be \code{'GAZE'} (0), \code{'HREF'} (1) or \code{'RAW'}, but currently this column is kept as numeric, since observed values do not match the declared constants.
137 | \item \code{rec_eye} \code{'LEFT'} (1), \code{'RIGHT'} (2) or \code{'LEFT and RIGHT'} (3).
138 | }
139 | }
140 | 
141 | \section{Recordings}{
142 | 
143 | Recordings table which is a collection of all \code{RECORDING} structures imported from the EDF file.
144 | Column descriptions were copied directly  from the \emph{EDF access C API manual}.
145 | Please refer to that manual for further details. Non-standard additional fields are marked in bold.
146 | \itemize{
147 | \item \strong{\code{trial}} Trial index.
148 | \item \code{time} Start time or end time.
149 | \item \code{sample rate} Sample rate in Hz: 250, 500, 1000 or 2000.
150 | \item \code{eflags} Extra information about events.
151 | \item \code{sflags} Extra information about samples.
152 | \item \code{state} \code{'START'} (2) or \code{'END'} (1).
153 | \item \code{record_type} \code{'SAMPLES'} (1), \code{'EVENTS'} (2), or \code{'SAMPLES and EVENTS'} (3).
154 | \item \code{pupil_type} \code{'AREA'} (0) or \code{'DIAMETER'} (1).
155 | \item \code{recording_mode} \code{'PUPIL'} (0) or \code{'CR'} (1).
156 | \item \code{filter_type} 1, 2, or 3.
157 | \item \code{pos_type} Should be \code{'GAZE'} (0), \code{'HREF'} (1) or \code{'RAW'}, but currently this column is kept as numeric, since observed values do not match the declared constants.
158 | \item \code{eye} \code{'LEFT'} (1), \code{'RIGHT'} (2) or \code{'LEFT and RIGHT'} (3).
159 | }
160 | }
161 | 
162 | \section{Saccades and Fixations}{
163 | 
164 | Saccades and fixations extracted from the \code{events}, tables have the same structure.
165 | Column descriptions were copied directly  from the \emph{EDF access C API manual}.
166 | Please refer to that manual for further details. Non-standard additional fields are marked in bold.
167 | \itemize{
168 | \item \strong{\code{trial}} Trial index.
169 | \item \code{sttime} Start time.
170 | \item \code{entime} End time.
171 | \item \strong{\code{sttime_rel}} Start time, relative to the start time of the trial.
172 | \item \strong{\code{entime_rel}} End time, relative to the start time of the trial.
173 | \item \strong{\code{duration}} Duration.
174 | \item \code{hstx}, \code{hsty} Head reference starting points.
175 | \item \code{gstx}, \code{gsty} Gaze starting points.
176 | \item \code{sta} Pupil size at start.
177 | \item \code{henx}, \code{heny} Headref ending points.
178 | \item \code{genx}, \code{geny} Gaze ending points.
179 | \item \code{ena} Pupil size at end.
180 | \item \code{havx}, \code{havy} Headref averages.
181 | \item \code{gavx}, \code{gavy} Gaze averages.
182 | \item \code{ava} Average pupil size.
183 | \item \code{avel} Accumulated average velocity.
184 | \item \code{pvel} Accumulated peak velocity.
185 | \item \code{svel} Start velocity.
186 | \item \code{evel} End velocity.
187 | \item \code{supd_x}, \code{supd_y} Start units-per-degree.
188 | \item \code{eupd_x}, \code{eupd_y} End units-per-degree.
189 | \item \code{eye} Either \code{'LEFT'} (1) or \code{'RIGHT'} (2).
190 | }
191 | }
192 | 
193 | \section{Blinks}{
194 | 
195 | Blinks extracted from the \code{events} table. Column descriptions were copied directly from the \emph{EDF access C API manual}.
196 | Please refer to that manual for further details. Non-standard additional fields are marked in bold.
197 | \itemize{
198 | \item \strong{\code{trial}} Trial index.
199 | \item \code{sttime} Start time.
200 | \item \code{entime} End time.
201 | \item \strong{\code{sttime_rel}} Start time, relative to the start time of the trial.
202 | \item \strong{\code{entime_rel}} End time, relative to the start time of the trial.
203 | \item \strong{\code{duration}} Duration.
204 | \item \code{eye} Either \code{'LEFT'} (1) or \code{'RIGHT'} (2).
205 | }
206 | }
207 | 
208 | \section{Variables}{
209 | 
210 | User recorded variables extracted from message events with a \code{'TRIAL_VAR'} prefix.
211 | Original format can be either \code{'TRIAL_VAR <name> <value>'} or \code{'TRIAL_VAR <name>=<value>'}.
212 | The \code{<name>} cannot contain spaces or \code{'='} sign.
213 | White spaces are trimmed for both \code{<name>} and \code{<value>}.
214 | \itemize{
215 | \item \code{trial} Trial index.
216 | \item \code{sttime} Start time.
217 | \item \code{sttime_rel} Start time, relative to the start time of the trial.
218 | \item \code{variable} Variable name, the \code{<name>} part of the event message.
219 | \item \code{value} Variable value, the \code{<value>} part of the event message.
220 | }
221 | }
222 | 
223 | \section{Trigger events}{
224 | 
225 | Events messages that adhere to a \code{TRIGGER <label>} format.
226 | This is a \strong{non-standard message} that the package author uses to mark events like onsets or offsets,
227 | similar to how it is done in M/EEG.
228 | \itemize{
229 | \item \code{trial} Trial index.
230 | \item \code{sttime} Start time.
231 | \item \code{sttime_rel} Start time, relative to the start time of the trial.
232 | \item \code{label} \emph{label} part of the message, can contain white spaces.
233 | }
234 | }
235 | 
236 | \section{AOIs}{
237 | 
238 | Rectangular areas of interest (AOI), as defined by "!V IAREA RECTANGLE" command.
239 | Specifically, they are expected to be in format
240 | \code{!V IAREA RECTANGLE <index> <left> <top> <right> <bottom> <label>}.
241 | where \code{<label>} is a string label and all other variables are integer.
242 | \itemize{
243 | \item \code{trial} Trial index.
244 | \item \code{sttime} Start time.
245 | \item \code{sttime_rel} Start time, relative to the start time of the trial.
246 | \item \code{index} AOI index.
247 | \item \code{left}, \code{top}, \code{right}, \code{bottom} AOI coordinates.
248 | \item \code{label} AOI label.
249 | }
250 | }
251 | 
252 | \seealso{
253 | \code{\link{read_edf}}, \code{\link{extract_saccades}}, \code{\link{extract_fixations}}, \code{\link{extract_blinks}}, \code{\link{extract_triggers}}, \code{\link{extract_display_coords}}, \code{\link{extract_AOIs}}
254 | }
255 | 


--------------------------------------------------------------------------------
/man/figures/logo.svg:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 2 | <!-- Generator: Adobe Illustrator 26.5.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
 3 | 
 4 | <svg
 5 |    version="1.1"
 6 |    id="Layer_1"
 7 |    x="0px"
 8 |    y="0px"
 9 |    viewBox="0 0 2521 2911"
10 |    style="enable-background:new 0 0 2521 2911;"
11 |    xml:space="preserve"
12 |    sodipodi:docname="eyelinkReader.svg"
13 |    inkscape:version="1.3 (0e150ed6c4, 2023-07-21)"
14 |    inkscape:export-filename="eyelinkReader.png"
15 |    inkscape:export-xdpi="96"
16 |    inkscape:export-ydpi="96"
17 |    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
18 |    xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
19 |    xmlns="http://www.w3.org/2000/svg"
20 |    xmlns:svg="http://www.w3.org/2000/svg"><defs
21 |    id="defs247"><rect
22 |    x="412.5"
23 |    y="1193.75"
24 |    width="2818.75"
25 |    height="531.25"
26 |    id="rect248" />&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;	&#10;</defs><sodipodi:namedview
27 |    id="namedview247"
28 |    pagecolor="#ffffff"
29 |    bordercolor="#000000"
30 |    borderopacity="0.25"
31 |    inkscape:showpageshadow="2"
32 |    inkscape:pageopacity="0.0"
33 |    inkscape:pagecheckerboard="0"
34 |    inkscape:deskcolor="#d1d1d1"
35 |    inkscape:zoom="0.16"
36 |    inkscape:cx="-350"
37 |    inkscape:cy="1553.125"
38 |    inkscape:window-width="2400"
39 |    inkscape:window-height="1471"
40 |    inkscape:window-x="-9"
41 |    inkscape:window-y="-9"
42 |    inkscape:window-maximized="1"
43 |    inkscape:current-layer="Layer_1" />&#10;<style
44 |    type="text/css"
45 |    id="style1">&#10;	.st0{fill:#005590;}&#10;	.st1{fill:#004064;}&#10;	.st2{fill:#E6B35A;}&#10;	.st3{opacity:0.94;}&#10;	.st4{fill:#FFFFFF;}&#10;	.st5{fill:none;}&#10;	.st6{fill:#110B0C;}&#10;</style>&#10;<polygon
46 |    class="st0"
47 |    points="1260.5,85.8 63.1,777.2 63.1,2159.9 1260.5,2851.3 2457.9,2159.9 2457.9,777.2 1260.5,85.8 "
48 |    id="polygon1"
49 |    style="fill:#b3dee5;fill-opacity:1" /><path
50 |    class="st1"
51 |    d="M 2521,2183.6 V 727.7 L 2420.5,669.7 1467.4,119.3 1260.5,0 1053.6,119.4 100.5,669.8 0,727.7 v 1455.5 l 100.5,58 965.1,557.2 195.2,112.5 195.2,-112.5 965.1,-557.2 z M 100.5,2129 V 789.2 l 1160,-669.8 v 0 l 1160,669.8 V 2129 l -1160,669.8 z"
52 |    id="path1"
53 |    style="fill:#31525b;fill-opacity:1" />&#10;<text
54 |    xml:space="preserve"
55 |    id="text248"
56 |    style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:293.333px;font-family:'Clear Sans';-inkscape-font-specification:'Clear Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;white-space:pre;shape-inside:url(#rect248);display:inline;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75748;stroke-linejoin:round"
57 |    transform="translate(-569.38286,717.19728)"><tspan
58 |      x="898.26274"
59 |      y="1443.6846"
60 |      id="tspan1">eyelinkReader</tspan></text><g
61 |    id="g344"
62 |    transform="matrix(1.6341557,0,0,1.6341557,2125.906,-801.17685)"><path
63 |      style="opacity:1;fill:#fae6b1;fill-opacity:1;stroke:#faac22;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
64 |      d="M -812.41645,1588.5974 V 837.29642 h 433.00957 l 132.67584,132.67584 v 618.62514 h -565.68541"
65 |      id="path343" /><path
66 |      style="opacity:1;fill:#fae6b1;fill-opacity:1;stroke:#faac22;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
67 |      d="m -379.40688,837.29642 132.67584,132.67584 h -132.67584 z"
68 |      id="path344" /></g><g
69 |    id="g332"
70 |    transform="matrix(1.6341557,0,0,1.6341557,-108.10528,-614.42991)"><g
71 |      id="g331"
72 |      transform="matrix(0.8361508,0,0,1,139.83668,-0.30355908)"
73 |      style="fill:#ffffff"><path
74 |        style="opacity:0.828452;fill:#ffffff;fill-opacity:1;stroke:#ffa101;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
75 |        d="m 631.25,1065.625 c 174.56699,-148.05048 311.23253,-95.01747 406.25,0"
76 |        id="path330"
77 |        sodipodi:nodetypes="cc" /><path
78 |        style="opacity:0.828452;fill:#ffffff;fill-opacity:1;stroke:#ffa101;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
79 |        d="m 631.25,1066.2321 c 174.56699,148.0505 311.23253,95.0175 406.25,0"
80 |        id="path331"
81 |        sodipodi:nodetypes="cc" /></g><circle
82 |      style="opacity:0.828452;fill:#fda308;fill-opacity:1;stroke:#ffa101;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
83 |      id="path329"
84 |      cx="837.5"
85 |      cy="1065.625"
86 |      r="50" /></g></svg>
87 | 


--------------------------------------------------------------------------------
/man/gaze.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/data.R
 3 | \docType{data}
 4 | \name{gaze}
 5 | \alias{gaze}
 6 | \title{Imported example.edf, events and samples}
 7 | \format{
 8 | An object of class \code{eyelinkRecording} of length 12.
 9 | }
10 | \usage{
11 | gaze
12 | }
13 | \description{
14 | An \code{\link{eyelinkRecording}} for \emph{example.edf} via
15 | \code{read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"), import_samples = TRUE)}).
16 | Contains all extracted events including triggers, areas of interested, and display coordinates. The original
17 | recording consist of ten trials with a participant fixating on a target that jumps to a new location after
18 | one second and stays on the screen for another second. Includes all relevant events.
19 | }
20 | \details{
21 | See \code{\link{eyelinkRecording}} for details.
22 | }
23 | \seealso{
24 | \code{\link{eyelinkRecording}}, \code{\link{read_edf}}
25 | }
26 | \keyword{datasets}
27 | 


--------------------------------------------------------------------------------
/man/logical_index_for_sample_attributes.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/logical_index_for_sample_attributes.R
 3 | \name{logical_index_for_sample_attributes}
 4 | \alias{logical_index_for_sample_attributes}
 5 | \title{Checks validity of sample attribute vector and returns logical indexes.}
 6 | \usage{
 7 | logical_index_for_sample_attributes(import_samples, sample_attributes)
 8 | }
 9 | \arguments{
10 | \item{import_samples}{logical, whether importing was requested.}
11 | 
12 | \item{sample_attributes}{character vector with names of attributes.}
13 | }
14 | \value{
15 | logical vector
16 | }
17 | \description{
18 | Checks validity of sample attribute vector and returns logical indexes.
19 | }
20 | \examples{
21 | logical_index_for_sample_attributes(TRUE, c('time', 'gx', 'gy'))
22 | }
23 | \keyword{internal}
24 | 


--------------------------------------------------------------------------------
/man/plot.eyelinkRecording.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/plot.R
 3 | \name{plot.eyelinkRecording}
 4 | \alias{plot.eyelinkRecording}
 5 | \title{Plot fixations and saccades for a set of trials}
 6 | \usage{
 7 | \method{plot}{eyelinkRecording}(
 8 |   x,
 9 |   trial = 1,
10 |   show_fixations = TRUE,
11 |   fixation_size_property = "duration",
12 |   size_legend = ifelse(fixation_size_property == "duration", "Fixation duration [ms]",
13 |     NA),
14 |   show_saccades = TRUE,
15 |   saccade_color_property = "sttime_rel",
16 |   color_legend = ifelse(saccade_color_property == "sttime_rel", "Saccade onset [ms]", NA),
17 |   background_grobs = NULL,
18 |   ...
19 | )
20 | }
21 | \arguments{
22 | \item{x}{\code{\link{eyelinkRecording}} object}
23 | 
24 | \item{trial}{Trials to be plotted, could be a scalar index,
25 | a vector of indexes, or \code{NULL} (all trials). Defaults to \code{1}.}
26 | 
27 | \item{show_fixations}{logical, whether to draw fixation as circles. Defaults to \code{TRUE}.}
28 | 
29 | \item{fixation_size_property}{Which fixation property is used as circle aesthetics. Defaults to \code{"duration"}.}
30 | 
31 | \item{size_legend}{An optional legend title, defaults to \code{"Fixation duration [ms]"}
32 | if \code{fixation_size_property} is \code{"duration"} and to \code{NA} otherwise. In the latter case, the legend
33 | title is unmodified (i.e., determined by ggplot).}
34 | 
35 | \item{show_saccades}{logical, whether to draw saccades as line segments. Defaults to \code{TRUE}.}
36 | 
37 | \item{saccade_color_property}{Which saccade property is used as color aesthetics. Defaults to \code{"sttime_rel"}
38 | (onset time relative to the trial start).}
39 | 
40 | \item{color_legend}{An optional legend title, defaults to \code{"Saccade onset [ms]"}
41 | if \code{saccade_color_property} is \code{"sttime_rel"} and to \code{NA} otherwise. In the latter case, the legend
42 | title is unmodified (i.e., determined by ggplot).}
43 | 
44 | \item{background_grobs}{ggplot2 graphic objects add to the plot \emph{before} plotting data.}
45 | 
46 | \item{...}{Addition parameters (unused)}
47 | }
48 | \value{
49 | ggplot object
50 | }
51 | \description{
52 | This is only a basic plotting utility intended primarily
53 | for a quick visual check. Please refer to companion vignette on plotting
54 | for details about geoms and implementing your own custom plotting routine.
55 | }
56 | \examples{
57 | data(gaze)
58 | 
59 | # fixations and saccades for the first trial
60 | plot(gaze)
61 | 
62 | # fixations for the all trials
63 | plot(gaze, trial = NULL, show_saccades = FALSE)
64 | 
65 | # saccades for the first two trials
66 | plot(gaze, trial = 1:2, show_fixations = FALSE)
67 | 
68 | # color codes duration of a saccade
69 | plot(gaze, saccade_color_property = "duration")
70 | }
71 | 


--------------------------------------------------------------------------------
/man/print.eyelinkRecording.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/print.R
 3 | \name{print.eyelinkRecording}
 4 | \alias{print.eyelinkRecording}
 5 | \title{Print info about \code{\link{eyelinkRecording}}}
 6 | \usage{
 7 | \method{print}{eyelinkRecording}(x, ...)
 8 | }
 9 | \arguments{
10 | \item{x}{\code{\link{eyelinkRecording}} object}
11 | 
12 | \item{...}{Addition parameters (unused)}
13 | }
14 | \value{
15 | No return value, called for printing to console.
16 | }
17 | \description{
18 | Print info about \code{\link{eyelinkRecording}}
19 | }
20 | \examples{
21 | \donttest{
22 |   if (eyelinkReader::compiled_library_status()) {
23 |     recording <- read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"))
24 |     print(recording)
25 |   }
26 | }
27 | }
28 | 


--------------------------------------------------------------------------------
/man/read_edf.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/read_edf.R
 3 | \name{read_edf}
 4 | \alias{read_edf}
 5 | \title{Read EDF file with gaze data recorded by SR Research EyeLink eye tracker}
 6 | \usage{
 7 | read_edf(
 8 |   file,
 9 |   consistency = "check consistency and report",
10 |   import_events = TRUE,
11 |   import_recordings = TRUE,
12 |   import_samples = FALSE,
13 |   sample_attributes = NULL,
14 |   start_marker = "TRIALID",
15 |   end_marker = "TRIAL_RESULT",
16 |   import_saccades = TRUE,
17 |   import_blinks = TRUE,
18 |   import_fixations = TRUE,
19 |   import_variables = TRUE,
20 |   verbose = TRUE,
21 |   fail_loudly = TRUE
22 | )
23 | }
24 | \arguments{
25 | \item{file}{full name of the EDF file}
26 | 
27 | \item{consistency}{consistency check control for the time stamps of the start
28 | and end events, etc. Could be \code{'no consistency check'},
29 | \code{'check consistency and report'} (default), \code{'check consistency and fix'}.}
30 | 
31 | \item{import_events}{logical, whether to import events, defaults to
32 | \code{TRUE}}
33 | 
34 | \item{import_recordings}{logical, whether to import information about start/end of the recording, defaults to
35 | \code{TRUE}}
36 | 
37 | \item{import_samples}{logical, whether to import samples, defaults to \code{FALSE}.
38 | Please note that specifying\code{sample_attributes} automatically sets it to \code{TRUE}.}
39 | 
40 | \item{sample_attributes}{a character vector that lists sample attributes to be imported.
41 | By default, all attributes are imported (default). For the complete list of sample attributes
42 | please refer to \code{\link{eyelinkRecording}} or EDF API documentation.}
43 | 
44 | \item{start_marker}{event string that marks the beginning of the trial. Defaults to \code{"TRIALID"}.}
45 | 
46 | \item{end_marker}{event string that marks the end of the trial. Defaults to \code{"TRIAL_RESULT"}.
47 | Please note that an \strong{empty} string \code{''} means that a trial lasts from one \code{start_marker} till the next one.}
48 | 
49 | \item{import_saccades}{logical, whether to extract saccade events into a separate table for convenience. Defaults to \code{TRUE}.}
50 | 
51 | \item{import_blinks}{logical, whether to extract blink events into a separate table for convenience. Defaults to \code{TRUE}.}
52 | 
53 | \item{import_fixations}{logical, whether to extract fixation events into a separate table for convenience. Defaults to \code{TRUE}.}
54 | 
55 | \item{import_variables}{logical, whether to extract stored variables into a separate table for convenience. Defaults to \code{TRUE}.}
56 | 
57 | \item{verbose}{logical, whether the number of trials and the progress are shown in the console. Defaults to \code{TRUE}.}
58 | 
59 | \item{fail_loudly}{logical, whether lack of compiled library means
60 | error (\code{TRUE}, default) or just warning (\code{FALSE}).}
61 | }
62 | \value{
63 | an \code{\link{eyelinkRecording}} object that contains events, samples,
64 | and recordings, as well as specific events such as saccades, fixations, blinks, etc.
65 | }
66 | \description{
67 | Reads EDF file with gaze data recorded by SR Research EyeLink eye tracker
68 | and returns an \code{\link{eyelinkRecording}} object that contains events, samples,
69 | and recordings, as well as specific events such as saccades, fixations, blinks, etc.
70 | }
71 | \examples{
72 | \donttest{
73 |   if (eyelinkReader::compiled_library_status()) {
74 |     # Import only events and recordings information
75 |     recording <- read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"))
76 | 
77 |     # Import events and samples (only time and  screen gaze coordinates)
78 |     recording <- read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"),
79 |                           sample_attributes = c('time', 'gx', 'gy'))
80 | 
81 |     # Import events and samples (all attributes)
82 |     recording <- read_edf(system.file("extdata", "example.edf", package = "eyelinkReader"),
83 |                           import_samples= TRUE)
84 |   }
85 | }
86 | }
87 | 


--------------------------------------------------------------------------------
/man/read_edf_file.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/RcppExports.R
 3 | \name{read_edf_file}
 4 | \alias{read_edf_file}
 5 | \title{Internal function that reads EDF file}
 6 | \usage{
 7 | read_edf_file(
 8 |   filename,
 9 |   consistency,
10 |   import_events,
11 |   import_recordings,
12 |   import_samples,
13 |   sample_attr_flag,
14 |   start_marker_string,
15 |   end_marker_string,
16 |   verbose
17 | )
18 | }
19 | \arguments{
20 | \item{filename}{full name of the EDF file}
21 | 
22 | \item{consistency}{consistency check control (for the time stamps of the start
23 | and end events, etc). 0, no consistency check. 1, check consistency and report.
24 | 2, check consistency and fix.}
25 | 
26 | \item{import_events}{load/skip loading events.}
27 | 
28 | \item{import_recordings}{load/skip loading recordings.}
29 | 
30 | \item{import_samples}{load/skip loading of samples.}
31 | 
32 | \item{sample_attr_flag}{boolean vector that indicates which sample fields are to be stored}
33 | 
34 | \item{start_marker_string}{event that marks trial start. Defaults to "TRIALID", if empty.}
35 | 
36 | \item{end_marker_string}{event that marks trial end}
37 | 
38 | \item{verbose}{whether to show progressbar and report number of trials}
39 | }
40 | \value{
41 | contents of the EDF file. Please see read_edf for details.
42 | }
43 | \description{
44 | Reads EDF file into a list that contains events, samples, and recordings.
45 | DO NOT call this function directly. Instead, use read_edf function that implements
46 | parameter checks and additional postprocessing.
47 | }
48 | \keyword{internal}
49 | 


--------------------------------------------------------------------------------
/man/read_preamble.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/read_preamble.R
 3 | \name{read_preamble}
 4 | \alias{read_preamble}
 5 | \title{Reads edf-file preamble}
 6 | \usage{
 7 | read_preamble(file, fail_loudly = TRUE)
 8 | }
 9 | \arguments{
10 | \item{file}{name of the EDF file}
11 | 
12 | \item{fail_loudly}{logical, whether lack of compiled library means
13 | error (\code{TRUE}, default) or just warning (\code{FALSE}).}
14 | }
15 | \value{
16 | a character vector but with added class \code{eyelinkPreamble} to simplify printing.
17 | }
18 | \description{
19 | Read the preamble of the EDF file and parses it into an reading-friendly format
20 | }
21 | \examples{
22 | \donttest{
23 |  if (eyelinkReader::compiled_library_status()) {
24 |   read_preamble(system.file("extdata", "example.edf", package = "eyelinkReader"))
25 | }
26 | }
27 | }
28 | 


--------------------------------------------------------------------------------
/man/read_preamble_str.Rd:
--------------------------------------------------------------------------------
 1 | % Generated by roxygen2: do not edit by hand
 2 | % Please edit documentation in R/RcppExports.R
 3 | \name{read_preamble_str}
 4 | \alias{read_preamble_str}
 5 | \title{Reads preamble of the EDF file as a single string.}
 6 | \usage{
 7 | read_preamble_str(filename)
 8 | }
 9 | \value{
10 | string with the preamble
11 | }
12 | \description{
13 | Reads preamble of the EDF file as a single string.
14 | Please, do not use this function directly. Instead, call \code{\link{read_preamble}} function
15 | that provides a more consistent interface.
16 | }
17 | \examples{
18 | \donttest{
19 | if (eyelinkReader::compiled_library_status()) {
20 |   read_preamble(system.file("extdata", "example.edf", package = "eyelinkReader"))
21 | }
22 | }
23 | }
24 | \keyword{internal}
25 | 


--------------------------------------------------------------------------------
/pkgdown/favicon/apple-touch-icon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alexander-pastukhov/eyelinkReader/f041af9117ac14c954078b2871681207743d0fe4/pkgdown/favicon/apple-touch-icon.png


--------------------------------------------------------------------------------
/pkgdown/favicon/favicon-96x96.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alexander-pastukhov/eyelinkReader/f041af9117ac14c954078b2871681207743d0fe4/pkgdown/favicon/favicon-96x96.png


--------------------------------------------------------------------------------
/pkgdown/favicon/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alexander-pastukhov/eyelinkReader/f041af9117ac14c954078b2871681207743d0fe4/pkgdown/favicon/favicon.ico


--------------------------------------------------------------------------------
/pkgdown/favicon/favicon.svg:
--------------------------------------------------------------------------------
  1 | <svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svgjs="http://svgjs.dev/svgjs" width="2521" height="2911"><svg version="1.1" id="SvgjsSvg1033" x="0px" y="0px" viewBox="0 0 2521 2911" style="enable-background:new 0 0 2521 2911;" xml:space="preserve" sodipodi:docname="eyelinkReader.svg" inkscape:version="1.3 (0e150ed6c4, 2023-07-21)" inkscape:export-filename="eyelinkReader.png" inkscape:export-xdpi="96" inkscape:export-ydpi="96" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"><defs id="SvgjsDefs1032"><rect x="412.5" y="1193.75" width="2818.75" height="531.25" id="SvgjsRect1031"></rect>
  2 | 	
  3 | 	
  4 | 	
  5 | 	
  6 | 	
  7 | 	
  8 | 	
  9 | 	
 10 | 	
 11 | 	
 12 | 	
 13 | 	
 14 | 	
 15 | 	
 16 | 	
 17 | 	
 18 | 	
 19 | 	
 20 | 	
 21 | 	
 22 | 	
 23 | 	
 24 | 	
 25 | 	
 26 | 	
 27 | 	
 28 | 	
 29 | 	
 30 | 	
 31 | 	
 32 | 	
 33 | 	
 34 | 	
 35 | 	
 36 | 	
 37 | 	
 38 | 	
 39 | 	
 40 | 	
 41 | 	
 42 | 	
 43 | 	
 44 | 	
 45 | 	
 46 | 	
 47 | 	
 48 | 	
 49 | 	
 50 | 	
 51 | 	
 52 | 	
 53 | 	
 54 | 	
 55 | 	
 56 | 	
 57 | 	
 58 | 	
 59 | 	
 60 | 	
 61 | 	
 62 | 	
 63 | 	
 64 | 	
 65 | 	
 66 | 	
 67 | 	
 68 | 	
 69 | 	
 70 | 	
 71 | 	
 72 | 	
 73 | 	
 74 | 	
 75 | 	
 76 | 	
 77 | 	
 78 | 	
 79 | 	
 80 | 	
 81 | 	
 82 | 	
 83 | 	
 84 | 	
 85 | 	
 86 | 	
 87 | 	
 88 | 	
 89 | 	
 90 | 	
 91 | 	
 92 | 	
 93 | 	
 94 | 	
 95 | 	
 96 | 	
 97 | 	
 98 | 	
 99 | 	
100 | 	
101 | 	
102 | 	
103 | 	
104 | 	
105 | 	
106 | 	
107 | 	
108 | 	
109 | 	
110 | 	
111 | 	
112 | 	
113 | 	
114 | 	
115 | 	
116 | 	
117 | 	
118 | 	
119 | 	
120 | 	
121 | 	
122 | 	
123 | 	
124 | 	
125 | 	
126 | 	
127 | 	
128 | 	
129 | 	
130 | 	
131 | 	
132 | 	
133 | 	
134 | 	
135 | 	
136 | 	
137 | 	
138 | 	
139 | 	
140 | 	
141 | 	
142 | 	
143 | 	
144 | 	
145 | 	
146 | 	
147 | 	
148 | 	
149 | 	
150 | 	
151 | 	
152 | 	
153 | 	
154 | 	
155 | 	
156 | 	
157 | 	
158 | 	
159 | 	
160 | 	
161 | 	
162 | 	
163 | 	
164 | 	
165 | 	
166 | 	
167 | 	
168 | 	
169 | 	
170 | 	
171 | 	
172 | 	
173 | 	
174 | 	
175 | 	
176 | 	
177 | 	
178 | 	
179 | 	
180 | 	
181 | 	
182 | 	
183 | 	
184 | 	
185 | 	
186 | 	
187 | 	
188 | 	
189 | 	
190 | 	
191 | 	
192 | 	
193 | 	
194 | 	
195 | 	
196 | 	
197 | 	
198 | 	
199 | 	
200 | 	
201 | 	
202 | 	
203 | 	
204 | 	
205 | 	
206 | 	
207 | 	
208 | 	
209 | 	
210 | 	
211 | 	
212 | 	
213 | 	
214 | 	
215 | 	
216 | 	
217 | 	
218 | 	
219 | 	
220 | 	
221 | 	
222 | 	
223 | 	
224 | 	
225 | 	
226 | 	
227 | 	
228 | 	
229 | 	
230 | 	
231 | 	
232 | 	
233 | 	
234 | 	
235 | 	
236 | 	
237 | 	
238 | 	
239 | 	
240 | 	
241 | 	
242 | 	
243 | 	
244 | 	
245 | 	
246 | 	
247 | 	
248 | 	
249 | 	
250 | 	
251 | 	
252 | 	
253 | 	
254 | 	
255 | 	
256 | 	
257 | 	
258 | 	
259 | 	
260 | </defs><sodipodi:namedview id="SvgjsSodipodi:namedview1030" pagecolor="#ffffff" bordercolor="#000000" borderopacity="0.25" inkscape:showpageshadow="2" inkscape:pageopacity="0.0" inkscape:pagecheckerboard="0" inkscape:deskcolor="#d1d1d1" inkscape:zoom="0.16" inkscape:cx="-350" inkscape:cy="1553.125" inkscape:window-width="2400" inkscape:window-height="1471" inkscape:window-x="-9" inkscape:window-y="-9" inkscape:window-maximized="1" inkscape:current-layer="Layer_1"></sodipodi:namedview>
261 | <style type="text/css" id="SvgjsStyle1029">
262 | 	.st0{fill:#005590;}
263 | 	.st1{fill:#004064;}
264 | 	.st2{fill:#E6B35A;}
265 | 	.st3{opacity:0.94;}
266 | 	.st4{fill:#FFFFFF;}
267 | 	.st5{fill:none;}
268 | 	.st6{fill:#110B0C;}
269 | </style>
270 | <polygon class="st0" points="1260.5,85.8 63.1,777.2 63.1,2159.9 1260.5,2851.3 2457.9,2159.9 2457.9,777.2 1260.5,85.8 " id="SvgjsPolygon1028" style="fill:#b3dee5;fill-opacity:1"></polygon><path class="st1" d="M 2521,2183.6 V 727.7 L 2420.5,669.7 1467.4,119.3 1260.5,0 1053.6,119.4 100.5,669.8 0,727.7 v 1455.5 l 100.5,58 965.1,557.2 195.2,112.5 195.2,-112.5 965.1,-557.2 z M 100.5,2129 V 789.2 l 1160,-669.8 v 0 l 1160,669.8 V 2129 l -1160,669.8 z" id="SvgjsPath1027" style="fill:#31525b;fill-opacity:1"></path>
271 | <text xml:space="preserve" id="SvgjsText1026" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:293.333px;font-family:'Clear Sans';-inkscape-font-specification:'Clear Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;white-space:pre;shape-inside:url(#rect248);display:inline;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75748;stroke-linejoin:round" transform="translate(-569.38286,717.19728)" svgjs:data="{&quot;leading&quot;:&quot;1.3&quot;}"><tspan x="898.26274" y="1443.6846" id="SvgjsTspan1025">eyelinkReader</tspan></text><g id="SvgjsG1024" transform="matrix(1.6341557,0,0,1.6341557,2125.906,-801.17685)"><path style="opacity:1;fill:#fae6b1;fill-opacity:1;stroke:#faac22;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1" d="M -812.41645,1588.5974 V 837.29642 h 433.00957 l 132.67584,132.67584 v 618.62514 h -565.68541" id="SvgjsPath1023"></path><path style="opacity:1;fill:#fae6b1;fill-opacity:1;stroke:#faac22;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1" d="m -379.40688,837.29642 132.67584,132.67584 h -132.67584 z" id="SvgjsPath1022"></path></g><g id="SvgjsG1021" transform="matrix(1.6341557,0,0,1.6341557,-108.10528,-614.42991)"><g id="SvgjsG1020" transform="matrix(0.8361508,0,0,1,139.83668,-0.30355908)" style="fill:#ffffff"><path style="opacity:0.828452;fill:#ffffff;fill-opacity:1;stroke:#ffa101;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1" d="m 631.25,1065.625 c 174.56699,-148.05048 311.23253,-95.01747 406.25,0" id="SvgjsPath1019" sodipodi:nodetypes="cc"></path><path style="opacity:0.828452;fill:#ffffff;fill-opacity:1;stroke:#ffa101;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1" d="m 631.25,1066.2321 c 174.56699,148.0505 311.23253,95.0175 406.25,0" id="SvgjsPath1018" sodipodi:nodetypes="cc"></path></g><circle style="opacity:0.828452;fill:#fda308;fill-opacity:1;stroke:#ffa101;stroke-width:24.7133;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1" id="SvgjsCircle1017" cx="837.5" cy="1065.625" r="50"></circle></g></svg><style>@media (prefers-color-scheme: light) { :root { filter: none; } }
272 | @media (prefers-color-scheme: dark) { :root { filter: none; } }
273 | </style></svg>


--------------------------------------------------------------------------------
/pkgdown/favicon/site.webmanifest:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "",
 3 |   "short_name": "",
 4 |   "icons": [
 5 |     {
 6 |       "src": "/web-app-manifest-192x192.png",
 7 |       "sizes": "192x192",
 8 |       "type": "image/png",
 9 |       "purpose": "maskable"
10 |     },
11 |     {
12 |       "src": "/web-app-manifest-512x512.png",
13 |       "sizes": "512x512",
14 |       "type": "image/png",
15 |       "purpose": "maskable"
16 |     }
17 |   ],
18 |   "theme_color": "#ffffff",
19 |   "background_color": "#ffffff",
20 |   "display": "standalone"
21 | }


--------------------------------------------------------------------------------
/pkgdown/favicon/web-app-manifest-192x192.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alexander-pastukhov/eyelinkReader/f041af9117ac14c954078b2871681207743d0fe4/pkgdown/favicon/web-app-manifest-192x192.png


--------------------------------------------------------------------------------
/pkgdown/favicon/web-app-manifest-512x512.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/alexander-pastukhov/eyelinkReader/f041af9117ac14c954078b2871681207743d0fe4/pkgdown/favicon/web-app-manifest-512x512.png


--------------------------------------------------------------------------------
/src/.gitignore:
--------------------------------------------------------------------------------
1 | *.o
2 | *.so
3 | *.dll
4 | 


--------------------------------------------------------------------------------
/src/Makevars:
--------------------------------------------------------------------------------
1 | 
2 | 


--------------------------------------------------------------------------------
/src/Makevars.win:
--------------------------------------------------------------------------------
1 | 
2 | 


--------------------------------------------------------------------------------
/src/RcppExports.cpp:
--------------------------------------------------------------------------------
 1 | // Generated by using Rcpp::compileAttributes() -> do not edit by hand
 2 | // Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
 3 | 
 4 | #include <Rcpp.h>
 5 | 
 6 | using namespace Rcpp;
 7 | 
 8 | #ifdef RCPP_USE_GLOBAL_ROSTREAM
 9 | Rcpp::Rostream<true>&  Rcpp::Rcout = Rcpp::Rcpp_cout_get();
10 | Rcpp::Rostream<false>& Rcpp::Rcerr = Rcpp::Rcpp_cerr_get();
11 | #endif
12 | 
13 | // compiled_library_status
14 | bool compiled_library_status();
15 | RcppExport SEXP _eyelinkReader_compiled_library_status() {
16 | BEGIN_RCPP
17 |     Rcpp::RObject rcpp_result_gen;
18 |     Rcpp::RNGScope rcpp_rngScope_gen;
19 |     rcpp_result_gen = Rcpp::wrap(compiled_library_status());
20 |     return rcpp_result_gen;
21 | END_RCPP
22 | }
23 | // convert_NAs
24 | List convert_NAs(List original_frame);
25 | RcppExport SEXP _eyelinkReader_convert_NAs(SEXP original_frameSEXP) {
26 | BEGIN_RCPP
27 |     Rcpp::RObject rcpp_result_gen;
28 |     Rcpp::RNGScope rcpp_rngScope_gen;
29 |     Rcpp::traits::input_parameter< List >::type original_frame(original_frameSEXP);
30 |     rcpp_result_gen = Rcpp::wrap(convert_NAs(original_frame));
31 |     return rcpp_result_gen;
32 | END_RCPP
33 | }
34 | // read_edf_file
35 | List read_edf_file(std::string filename, int consistency, bool import_events, bool import_recordings, bool import_samples, LogicalVector sample_attr_flag, std::string start_marker_string, std::string end_marker_string, bool verbose);
36 | RcppExport SEXP _eyelinkReader_read_edf_file(SEXP filenameSEXP, SEXP consistencySEXP, SEXP import_eventsSEXP, SEXP import_recordingsSEXP, SEXP import_samplesSEXP, SEXP sample_attr_flagSEXP, SEXP start_marker_stringSEXP, SEXP end_marker_stringSEXP, SEXP verboseSEXP) {
37 | BEGIN_RCPP
38 |     Rcpp::RObject rcpp_result_gen;
39 |     Rcpp::RNGScope rcpp_rngScope_gen;
40 |     Rcpp::traits::input_parameter< std::string >::type filename(filenameSEXP);
41 |     Rcpp::traits::input_parameter< int >::type consistency(consistencySEXP);
42 |     Rcpp::traits::input_parameter< bool >::type import_events(import_eventsSEXP);
43 |     Rcpp::traits::input_parameter< bool >::type import_recordings(import_recordingsSEXP);
44 |     Rcpp::traits::input_parameter< bool >::type import_samples(import_samplesSEXP);
45 |     Rcpp::traits::input_parameter< LogicalVector >::type sample_attr_flag(sample_attr_flagSEXP);
46 |     Rcpp::traits::input_parameter< std::string >::type start_marker_string(start_marker_stringSEXP);
47 |     Rcpp::traits::input_parameter< std::string >::type end_marker_string(end_marker_stringSEXP);
48 |     Rcpp::traits::input_parameter< bool >::type verbose(verboseSEXP);
49 |     rcpp_result_gen = Rcpp::wrap(read_edf_file(filename, consistency, import_events, import_recordings, import_samples, sample_attr_flag, start_marker_string, end_marker_string, verbose));
50 |     return rcpp_result_gen;
51 | END_RCPP
52 | }
53 | // read_preamble_str
54 | std::string read_preamble_str(std::string filename);
55 | RcppExport SEXP _eyelinkReader_read_preamble_str(SEXP filenameSEXP) {
56 | BEGIN_RCPP
57 |     Rcpp::RObject rcpp_result_gen;
58 |     Rcpp::RNGScope rcpp_rngScope_gen;
59 |     Rcpp::traits::input_parameter< std::string >::type filename(filenameSEXP);
60 |     rcpp_result_gen = Rcpp::wrap(read_preamble_str(filename));
61 |     return rcpp_result_gen;
62 | END_RCPP
63 | }
64 | 
65 | static const R_CallMethodDef CallEntries[] = {
66 |     {"_eyelinkReader_compiled_library_status", (DL_FUNC) &_eyelinkReader_compiled_library_status, 0},
67 |     {"_eyelinkReader_convert_NAs", (DL_FUNC) &_eyelinkReader_convert_NAs, 1},
68 |     {"_eyelinkReader_read_edf_file", (DL_FUNC) &_eyelinkReader_read_edf_file, 9},
69 |     {"_eyelinkReader_read_preamble_str", (DL_FUNC) &_eyelinkReader_read_preamble_str, 1},
70 |     {NULL, NULL, 0}
71 | };
72 | 
73 | RcppExport void R_init_eyelinkReader(DllInfo *dll) {
74 |     R_registerRoutines(dll, NULL, CallEntries, NULL, NULL);
75 |     R_useDynamicSymbols(dll, FALSE);
76 | }
77 | 


--------------------------------------------------------------------------------
/src/compiled_library_status.cpp:
--------------------------------------------------------------------------------
 1 | #include <Rcpp.h>
 2 | using namespace Rcpp;
 3 | 
 4 | //' @title Status of compiled library
 5 | //' @description Return status of compiled library
 6 | //' @return logical
 7 | //' @export
 8 | //' @examples
 9 | //' compiled_library_status()
10 | //[[Rcpp::export]]
11 | bool compiled_library_status(){
12 |   // the other version, compiled alongside the library returns true
13 |   return(false);
14 | }
15 | 


--------------------------------------------------------------------------------
/src/convert_NAs.cpp:
--------------------------------------------------------------------------------
 1 | #include <Rcpp.h>
 2 | using namespace Rcpp;
 3 | 
 4 | //' @title Convert -32767 (missing info) to NA
 5 | //' @description Converts all -32767 (smallest INT16  value indicating missing info) to NA.
 6 | //' You don't need to call this function directly, as it is automatically evoked within
 7 | //' \code{\link{read_edf}} function.
 8 | //' @param original_frame data.frame to be processed
 9 | //' @return processed data.frame
10 | //' @export
11 | //' @examples
12 | //' \donttest{
13 | //'   data(gaze)
14 | //'   gaze$samples <- convert_NAs(gaze$samples)
15 | //' }
16 | //[[Rcpp::export]]
17 | List convert_NAs(List original_frame){
18 |   List target_frame = clone(original_frame);
19 |   for( List::iterator it = target_frame.begin(); it != target_frame.end(); ++it ) {
20 |     switch( TYPEOF(*it) ) {
21 |       case REALSXP: {
22 |         NumericVector tmp = as<NumericVector>(*it);
23 |         for(unsigned int iRow= 0; iRow<tmp.size(); iRow++){
24 |           if ((tmp[iRow]<=-32767) || (tmp[iRow] >= 1e8)){
25 |             tmp(iRow)= NA_REAL;
26 |           }
27 |         }
28 |         break;
29 |       }
30 |       case INTSXP: {
31 |         if( Rf_isFactor(*it) ) break; // factors have internal type INTSXP too
32 |         IntegerVector tmp = as<IntegerVector>(*it);
33 |         for(unsigned int iRow= 0; iRow<tmp.size(); iRow++){
34 |           if (tmp[iRow]<=-32767 || (tmp[iRow] >= 1e8)){
35 |             tmp(iRow)= NA_INTEGER;
36 |           }
37 |         }
38 |         break;
39 |       }
40 |     }
41 |   }
42 | 
43 |   // target_frame.attr("class") = "data.frame";
44 |   return target_frame;
45 | }
46 | 


--------------------------------------------------------------------------------
/src/read_edf_file.cpp:
--------------------------------------------------------------------------------
 1 | #include <Rcpp.h>
 2 | using namespace Rcpp;
 3 | 
 4 | 
 5 | //' @title Internal function that reads EDF file
 6 | //' @description Reads EDF file into a list that contains events, samples, and recordings.
 7 | //' DO NOT call this function directly. Instead, use read_edf function that implements
 8 | //' parameter checks and additional postprocessing.
 9 | //' @param filename full name of the EDF file
10 | //' @param consistency consistency check control (for the time stamps of the start
11 | //' and end events, etc). 0, no consistency check. 1, check consistency and report.
12 | //' 2, check consistency and fix.
13 | //' @param import_events load/skip loading events.
14 | //' @param import_recordings load/skip loading recordings.
15 | //' @param import_samples load/skip loading of samples.
16 | //' @param sample_attr_flag boolean vector that indicates which sample fields are to be stored
17 | //' @param start_marker_string event that marks trial start. Defaults to "TRIALID", if empty.
18 | //' @param end_marker_string event that marks trial end
19 | //' @param verbose whether to show progressbar and report number of trials
20 | //' @export
21 | //' @keywords internal
22 | //' @return contents of the EDF file. Please see read_edf for details.
23 | //[[Rcpp::export]]
24 | List read_edf_file(std::string filename,
25 |                    int consistency,
26 |                    bool import_events,
27 |                    bool import_recordings,
28 |                    bool import_samples,
29 |                    LogicalVector sample_attr_flag,
30 |                    std::string start_marker_string,
31 |                    std::string end_marker_string,
32 |                    bool verbose){
33 |   return(List::create());
34 | }
35 | 


--------------------------------------------------------------------------------
/src/read_preamble_str.cpp:
--------------------------------------------------------------------------------
 1 | #include <Rcpp.h>
 2 | using namespace Rcpp;
 3 | 
 4 | 
 5 | //' @title Reads preamble of the EDF file as a single string.
 6 | //' @description Reads preamble of the EDF file as a single string.
 7 | //' Please, do not use this function directly. Instead, call \code{\link{read_preamble}} function
 8 | //' that provides a more consistent interface.
 9 | //' @return string with the preamble
10 | //' @export
11 | //' @keywords internal
12 | //' @examples
13 | //' \donttest{
14 | //' if (eyelinkReader::compiled_library_status()) {
15 | //'   read_preamble(system.file("extdata", "example.edf", package = "eyelinkReader"))
16 | //' }
17 | //' }
18 | //[[Rcpp::export]]
19 | std::string read_preamble_str(std::string filename){
20 |   return("");
21 | }
22 | 


--------------------------------------------------------------------------------
/tests/testthat.R:
--------------------------------------------------------------------------------
1 | Sys.setenv("R_TESTS" = "")
2 | 
3 | library(testthat)
4 | library(eyelinkReader)
5 | 
6 | test_check("eyelinkReader")
7 | 


--------------------------------------------------------------------------------
/tests/testthat/test-safety_checks.R:
--------------------------------------------------------------------------------
 1 | test_that("check_consistency_flag works", {
 2 |   valid_flags <- c('no consistency check', 'check consistency and report', 'check consistency and fix')
 3 |   for(iFlag in 1:length(valid_flags)) {
 4 |     expect_equal(check_consistency_flag(valid_flags[iFlag]), iFlag - 1)
 5 |   }
 6 |   expect_error(check_consistency_flag("some other flag"))
 7 |   expect_error(check_consistency_flag(0))
 8 |   expect_error(check_consistency_flag(valid_flags))
 9 |   expect_error(check_consistency_flag(NA))
10 |   expect_error(check_consistency_flag(NULL))
11 | })
12 | 
13 | test_that("check_logical_flag works", {
14 |   expect_equal(check_logical_flag(TRUE), TRUE)
15 |   expect_equal(check_logical_flag(FALSE), FALSE)
16 |   expect_error(check_logical_flag(1))
17 |   expect_error(check_logical_flag("TRUE"))
18 |   expect_error(check_logical_flag(c(TRUE, FALSE)))
19 |   x <- NA
20 |   expect_error(check_logical_flag(x))
21 |   x <- NULL
22 |   expect_error(check_logical_flag(x))
23 | })
24 | 
25 | test_that("check_string_parameter works", {
26 |   expect_equal(check_string_parameter('TRUE'), "TRUE")
27 |   expect_error(check_string_parameter(1))
28 |   expect_error(check_string_parameter(TRUE))
29 |   expect_error(check_string_parameter(c("TRUE", "FALSE")))
30 |   x <- NA
31 |   expect_error(check_string_parameter(x))
32 |   x <- NULL
33 |   expect_error(check_string_parameter(x))
34 | })
35 | 
36 | 
37 | test_that("compiled_library_status() works", {
38 |   expect_type(compiled_library_status(), "logical" )
39 | })
40 | 


--------------------------------------------------------------------------------
/tests/testthat/test-sample-attributes.R:
--------------------------------------------------------------------------------
 1 | test_that("sample attribute logical flags work ", {
 2 |   sample_attr_labels <- c('time', 'px', 'py', 'hx', 'hy', 'pa',
 3 |                           'gx', 'gy', 'rx', 'ry',
 4 |                           'gxvel', 'gyvel', 'hxvel', 'hyvel', 'rxvel', 'ryvel',
 5 |                           'fgxvel', 'fgyvel', 'fhxvel', 'fhyvel', 'frxvel', 'fryvel',
 6 |                           'hdata', 'flags', 'input', 'buttons', 'htype', 'errors')
 7 | 
 8 | 
 9 |   expect_equal(logical_index_for_sample_attributes(TRUE, c('time', 'gx', 'gy')),
10 |                sample_attr_labels %in% c('time', 'gx', 'gy'))
11 | 
12 |   # all attributes by default (NULL instead of character list)
13 |   expect_equal(logical_index_for_sample_attributes(TRUE, NULL),
14 |                rep(TRUE, length(sample_attr_labels)))
15 |   expect_equal(logical_index_for_sample_attributes(FALSE, NULL),
16 |                rep(FALSE, length(sample_attr_labels)))
17 | 
18 | 
19 |   # attributes override the logical flag
20 |   expect_equal(logical_index_for_sample_attributes(FALSE, c('time', 'gx', 'gy')),
21 |                sample_attr_labels %in% c('time', 'gx', 'gy'))
22 |   # wrong attribute name time2 instead of time
23 |   expect_error(logical_index_for_sample_attributes(TRUE, c('time2', 'gx', 'gy')))
24 |   expect_error(logical_index_for_sample_attributes(TRUE, NA))
25 |   expect_error(logical_index_for_sample_attributes(TRUE, c(1, 2, 3)))
26 | 
27 |   # wrong import_samples flag
28 |   expect_error(logical_index_for_sample_attributes("TRUE", c('time2', 'gx', 'gy')))
29 | 
30 | 
31 | })
32 | 


--------------------------------------------------------------------------------
/vignettes/.gitignore:
--------------------------------------------------------------------------------
1 | *.html
2 | *.R
3 | 


--------------------------------------------------------------------------------
/vignettes/installation.Rmd:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: "Installation"
 3 | output: rmarkdown::html_vignette
 4 | vignette: >
 5 |   %\VignetteIndexEntry{Installation}
 6 |   %\VignetteEngine{knitr::rmarkdown}
 7 |   %\VignetteEncoding{UTF-8}
 8 | ---
 9 | 
10 | ```{r, include = FALSE}
11 | knitr::opts_chunk$set(
12 |   collapse = TRUE,
13 |   comment = "#>"
14 | )
15 | ```
16 | 
17 | The library installation involves three easy (famous last words) steps.
18 | 
19 | ### Install SR Research EyeLink Developers Kit
20 | This package relies on _edfapi_ library that is as part of the _EyeLink Developers Kit_. Therefore, `read_edf()` function **will not work without it** but you will still be able to use utility functions. The _EyeLink Developers Kit_ can be downloaded from [www.sr-research.com/support](https://www.sr-research.com/support/) website. Note that you need to register and wait for your account to be activated. Next, follow instructions to install _EyeLink Developers Kit_ for your platform. The forum thread should be under _SR Support Forum › Downloads › EyeLink Developers Kit / API › Download: EyeLink Developers Kit / API Downloads (Windows, macOS, Linux)_.
21 | 
22 | ### Configure R environment variables
23 | 
24 | The package needs to configure compiler flags for its dependency on EDF API library. Specifically, it needs to specify paths to include header files ( _edf.h_, _edf_data.h_, and _edftypes.h_) and to the library itself. The package will try to compile using sensible defaults for each platform, i.e., default installation paths for _EyeLink Developers Kit v2.1.1_. However, these defaults may change in the future or you may wish to install the library to a non-standard location (relevant primarily for Windows).
25 | 
26 | If compilation with default paths fails, you need to define R environment variables as described below. These variables must be defined either in user or project [.Renviron](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html) file. The simplest way to edit it is via [usethis](https://usethis.r-lib.org/) library and [edit_r_environ()](https://usethis.r-lib.org/reference/edit.html) function. Type `usethis::edit_r_environ()` for user and `usethis::edit_r_environ('project')` for projects environments (note that the latter shadows the former, read [documentation](https://usethis.r-lib.org/) for details). In the case of Windows, note that you do not need to worry about forward vs. backward slashes as R will normalize strings for you. Once you define the variables, restart session and check them by typing `Sys.getenv()` (to see all variables) or `Sys.getenv("EDFAPI_INC")` to check a specific one.
27 | 
28 | #### Windows
29 | Default values assume that the EyeLink Developers Kit is installed in `c:/Program Files (x86)/SR Research/EyeLink` (default installation path).
30 | 
31 | * `EDFAPI_LIB` : path to `edfapi.dll` for **32-bit systems**. Defaults to `c:/Program Files (x86)/SR Research/EyeLink/libs`.
32 | * `EDFAPI_LIB64` (optional): path to `edfapi64.dll` for **64-bit systems**. By default, the 64-bit library is in _x64_ subfolder, i.e., `c:/Program Files (x86)/SR Research/EyeLink/libs/x64`. This variable is optional, as the package will try to guess this by itself by appending `/x64` to `EDFAPI_LIB` path. However, you should specify this variable explicitly if 64-libraries are in a non-standard folder (or SR Research changed it, or you just want to be sure).
33 | * `EDFAPI_INC` : path to C header files necessary for compilation. Specifically, the package requires _edf.h_, _edf_data.h_, and _edftypes.h_. Defaults to `c:/Program Files (x86)/SR Research/EyeLink/Includes/eyelink`.
34 | 
35 | Your `.Renviron` file include lines similar to the ones below
36 | ```
37 | EDFAPI_LIB="c:/Program Files (x86)/SR Research/EyeLink/libs"
38 | EDFAPI_LIB64="c:/Program Files (x86)/SR Research/EyeLink/libs/x64"
39 | EDFAPI_INC="c:/Program Files (x86)/SR Research/EyeLink/Includes/eyelink"
40 | ```
41 | 
42 | #### Linux
43 | * `EDFAPI_INC` : path to C header files necessary for compilation. Specifically, the package requires _edf.h_, _edf_data.h_, and _edftypes.h_. Defaults to `/usr/include/EyeLink`.
44 | 
45 | Your `.Renviron` file should include a line like this
46 | ```
47 | EDFAPI_INC="/usr/include/EyeLink"
48 | ```
49 | 
50 | #### Mac OS
51 | 
52 | * `EDFAPI_LIB`: path to EDF API framework. Defaults to `/Library/Frameworks`
53 | * `EDFAPI_INC` : path to C header files necessary for compilation. Specifically, the package requires _edf.h_, _edf_data.h_, and _edftypes.h_. Defaults to `/Library/Frameworks/edfapi.framework/Headers`
54 | 
55 | Your `.Renviron` file include lines similar to the ones below
56 | ```
57 | EDFAPI_LIB="/Library/Frameworks"
58 | EDFAPI_INC="/Library/Frameworks/edfapi.framework/Headers"
59 | ```
60 | 
61 | ### Install the library
62 | 
63 | To install from github
64 | ```
65 | library("devtools")
66 | install_github("alexander-pastukhov/eyelinkReader", dependencies=TRUE,  build_vignettes = TRUE)
67 | ```
68 | 


--------------------------------------------------------------------------------
/vignettes/plotting.Rmd:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: "Plotting"
 3 | output: rmarkdown::html_vignette
 4 | vignette: >
 5 |   %\VignetteIndexEntry{Plotting}
 6 |   %\VignetteEngine{knitr::rmarkdown}
 7 |   %\VignetteEncoding{UTF-8}
 8 | ---
 9 | 
10 | ```{r, include = FALSE}
11 | knitr::opts_chunk$set(
12 |   collapse = TRUE,
13 |   comment = "#>"
14 | )
15 | ```
16 | 
17 | ```{r setup}
18 | ```
19 | 
20 | The package provides basic plotting functionality via \code{plot} function that uses [ggplot2](https://ggplot2.tidyverse.org/) as a back end. This means that you can extend the plot by adding further layers and geoms. Below is the basic code that shows how to use [ggplot2](https://ggplot2.tidyverse.org/) to generate a custom plot replicating the \code{plot}.
21 | ```{r out.width='100%', fig.width=10, fig.height=8}
22 | library(eyelinkReader)
23 | library(ggplot2)
24 | 
25 | data(gaze)
26 | 
27 | # extracting fixations and saccades for the first trial
28 | fixations <- gaze$fixations[gaze$fixations$trial == 1, ]
29 | saccades <- gaze$saccades[gaze$saccades$trial == 1, ]
30 | 
31 |  ggplot() +
32 |   
33 |   # enforce same scaling, as on the screen
34 |   coord_equal(expand=FALSE) +
35 |    
36 |   # define screen limits and INVERSE y-axis to match Eyelink
37 |   scale_x_continuous(name = "x", limits = gaze$display_coords[c(1, 3)]) +
38 |   scale_y_reverse(name = "y", limits = gaze$display_coords[c(4, 2)]) +
39 |    
40 |   # draw fixations as circles
41 |   geom_point(data = fixations, aes_string(x = "gavx", y = "gavy", size = "duration"), alpha=0.3) +
42 |    
43 |   # draw saccades as line segments
44 |   geom_segment(data = saccades, aes_string(x = "gstx", y = "gsty", xend = "genx", yend = "geny", color = "sttime_rel")) +
45 |    
46 |   # better legend titles
47 |   labs(size = "Fixation duration [ms]",
48 |        color = "Saccade onset [ms]")
49 | ```
50 | 
51 | 
52 | 


--------------------------------------------------------------------------------
/vignettes/usage.Rmd:
--------------------------------------------------------------------------------
 1 | ---
 2 | title: "Usage"
 3 | output: rmarkdown::html_vignette
 4 | vignette: >
 5 |   %\VignetteIndexEntry{Usage}
 6 |   %\VignetteEngine{knitr::rmarkdown}
 7 |   %\VignetteEncoding{UTF-8}
 8 | ---
 9 | 
10 | ```{r, include = FALSE}
11 | knitr::opts_chunk$set(
12 |   collapse = TRUE,
13 |   comment = "#>"
14 | )
15 | ```
16 | 
17 | ```{r setup}
18 | library(eyelinkReader)
19 | ```
20 | 
21 | 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.
22 | ```r
23 | library(eyelinkReader)
24 | gaze <- read_edf('eyelink-recording.edf')
25 | ```
26 | 
27 | 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. 
28 | ```r
29 | View(gaze$saccades)
30 | ```
31 | 
32 | ## Working with samples
33 | 
34 | 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.
35 | 
36 | ```r
37 | # import samples with all attributes
38 | gaze <- read_edf('eyelink-recording.edf', import_samples = TRUE)
39 | 
40 | # import samples with selected attributes
41 | gaze <- read_edf('eyelink-recording.edf',
42 |                  import_samples = TRUE,
43 |                  sample_attributes = c('time', 'gx', 'gy'))
44 | ```
45 | 
46 | 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.
47 | 
48 | ```r
49 | cyclopean_samples <- compute_cyclopean_samples(gaze$samples)
50 | ```
51 | 
52 | ## Utility functions
53 | 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`). 
54 | 
55 | ```r
56 | gaze <- extract_AOIs(gaze)
57 | gaze <- extract_triggers(gaze)
58 | ```
59 | 
60 | or, tidyverse-style
61 | ```r
62 | library(tidyverse)
63 | gaze <-
64 |   read_edf('eyelink-recording.edf') %>%
65 |   extract_AOIs() %>%
66 |   extract_triggers()
67 | ```
68 | 
69 | 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`.
70 | 
71 | ```r
72 | gaze <- adjust_message_time(gaze)
73 | ```
74 | 


--------------------------------------------------------------------------------