Package 'gazer'

Description

Takes a data frame of gaze positions (or other locations), plus screen size and aoi size (or location), and computes the area of interest (AOI) for each location. Defaults assume standard four-corner design.

Usage

assign_aoi(
  gaze,
  screen_size = c(1024, 768),
  aoi_size = c(400, 300),
  aoi_loc = NULL,
  X = "CURRENT_FIX_X",
  Y = "CURRENT_FIX_Y"
)

Arguments

Value

Original gaze data frame with AOI column added. Non-AOI and off-screen gazes are marked NA.

Description

Performs linear (sub) or divisive baseline correction relative to desired stim_onset and off_set

Usage

baseline_correction_pupil(
  datafile,
  pupil_colname = "pupil",
  baseline_window = NA,
  baseline_method = "sub",
  baseline_stat = "median"
)

Arguments

Value

data frame containing baseline corrected data from event of interest

Description

Performs linear (sub) or divisive baseline correction relative to desired stim_onset and off_set with messages.

Usage

baseline_correction_pupil_msg(
  datafile,
  pupil_colname = NULL,
  baseline_dur = 500,
  event = "event",
  baseline_method = "sub",
  baseline_stat = "median"
)

Arguments

Value

data frame containing baseline corrected data from event of interest

Description

culls important behavioral data from the sample report

Usage

behave_pupil(datafile, omiterrors = TRUE, behave_colnames = NULL)

Arguments

Value

data frame with or withour errors

Description

Takes a data frame list of fixations and returns a time series with the fixations expanded into time bins of specified duration.

Usage

binify_fixations(
  gaze,
  binSize = 20,
  keepCols = c("Subject", "TrialNumber", "Target", "T"),
  maxTime = NULL
)

Arguments

Value

data frame containing gaze data arranged by bin

Description

Take pupil file and detect blinks merge blinks with sample report Requires the saccades package (remotes::install_github("tmalsburg/saccades/saccades")).

Usage

blink_detect(samp)

Arguments

Value

merged data file with blinks detected

Description

This function takes a dataframe and applies a simple velocity algorithm to detect blinks in the data based off velocity of pupil size changes. The algorithm has four parameters that need to be adjusted based on the particulars of the data: the amount of smoothing, the (negative) onset velocity threshold, the (positive) reversal velocity threshold, and the temporal margin

Usage

blink_velocity(
  df,
  neg_velocity_thresh = -5,
  pos_velocity_thresh = 5,
  fillback = 10,
  fillforward = 10,
  hz = 250
)

Arguments

Value

data frame containing pupil values where blinks have been linear interpolated.

Description

calculates the median absoulte deviation (MAD) and sets the threshold to filter on.

Usage

calc_mad(max_dilation, n = 16)

Arguments

Value

threhold value to filter on

Description

Takes a data frame, name of predictor variable, and polynomial order. Creates polynomial-transformed predictor variables, adds them to the data frame and returns the result. Original data frame is unchanged, remember to assign the result.

Usage

code_poly(
  df = NULL,
  predictor = NULL,
  poly.order = NULL,
  orthogonal = TRUE,
  draw.poly = TRUE
)

Arguments

Value

Returns a data frame containing the original data and at least two new columns: "predictor".Index, and a column for each order of the polynomial-transformed predictor

Examples

WordLearnEx.gca <- code_poly(df=WordLearnEx, predictor="Block", poly.order=2)
TargetFix.gca <- code_poly(df=TargetFix, predictor="Time", poly.order=2, orthogonal=FALSE)

Description

Fixation time course data from 8 participants with aphasia and 12 age-matched control participants.

Usage

CohortRhyme

Format

A data frame with 1600 rows and 7 variables:

subjID

subject ID, factor

Group

subject group: Control, Broca's aphasia, Wernicke's aphasia

Time

time (in ms) since word onset in 100ms bins

timeBin

time bin number (1-20)

Object

object type: phonologically related Competitor or Unrelated object. Target object data are omitted

Type

type of phonological competitor: Cohort (e.g., penny - pencil) or Rhyme (e.g., carrot - parrot)

FixProp

fixation proportion: proportion of correct-response trials on which the object was fixated

Source

Mirman et al. (2011, Brain & Lang., 117:2, 53-68) http://www.danmirman.org/pdfs/Mirman_etal_2011.pdf

Description

For each numeric variable in a data frame, computes number of observations, mean, and standard deviation, for each group, and t- and p-values for the t-test comparing the groups.

Usage

compare_groups(dat, Group)

Arguments

Value

Returns a data frame with rows for each numeric variable in the input data frame (plus N, for number of observations) and columns for mean, SD, t-value, and p-value.

Examples

## Not run: 
compare_groups(SND, "SemNear_Cond")

## End(Not run)

Description

A "monocular mean" averages both eyes together. If data is available in just one eye, use the available value as the mean. If both eyes are missing, the result is NA.

Usage

compute_monocular_mean(x1, x2)

Arguments

Value

A numeric vector of monocular mean pupil values.

Description

Calculate percent missing data by subject and by trial

Usage

count_missing_pupil(datafile, pupil = "pupil", missingthresh = 0.2)

Arguments

Value

data frame containing missing data information

Description

Computes Crawford-Howell t-test comparing a single case to a set of controls.

Usage

Crawford_Howell(case, control)

Arguments

Value

Returns a data frame with three values: t, df, and p.

Examples

Crawford_Howell(649, c(243, 175, 231, 164, 236, 131, 302, 303, 363, 287, 205, 297, 144, 789, 210, 245))

Description

Aggregate baseline corrected pupillary data for a LDT task that required participants to judge the lexical status of cursive and type-print stimuli.

Usage

cursive_agg_data

Format

A data frame with 52 rows and 3 variables

script

Cursive or Print

timebins

trial onset

aggbaseline

baseline corrected pupil size

Description

Detects blinks in a per-sample pupil time series. Starts from the tracker's missing-data sentinel and refines each missing-sample run's onset and offset by walking outward on the smoothed first-difference signal – picking up the eyelid descent before the missing samples and the recovery rise after. Adjacent blinks separated by less than gap_ms are merged.

Usage

detect_blinks_noise(
  pupil,
  hz,
  smooth_ms = 10,
  gap_ms = 100,
  missing = c(0, NA)
)

Arguments

Details

Tracker-agnostic missing handling: by default treats both NA and 0 as missing (Tobii uses 0; SR Research / EyeLink exports often use NA). Override via missing.

Composes with dplyr exactly like gazeR::extend_blinks():

df |>
  group_by(subject, trial) |>
  mutate(blink = detect_blinks_noise(pupil, hz = 250))

If you want pupil set to NA inside blinks (gazeR-style), chain one more line:

... |>
  mutate(pupil = ifelse(blink > 0, NA_real_, pupil))

Adapted to R with Dr William Paul Boyce ([email protected]); indexing bug in the original port – matching on index instead of time – was diagnosed by Dr Jason Geller.

Value

An integer vector the same length as pupil: 0 outside detected blinks, ⁠1, 2, ...⁠ inside each blink. When used inside dplyr::mutate() under a group_by(), blink ids restart at 1 in each group.

Description

This function will combine gaze samples into time bins.

Usage

downsample_gaze(
  dataframe,
  bin.length = 50,
  timevar = "time",
  aggvars = c("subject", "condition", "target", "trial", "object", "timebins"),
  type = "gaze",
  pupil = "baselinecorrectedp"
)

Arguments

Value

Downsampled DataFrame.

Description

This function will reduce the sampling fequency

Usage

downsample_pupil(
  dataframe,
  bin.length = NULL,
  timevar = "time",
  aggvars = c("subject", "script", "timebins")
)

Arguments

Description

calc dynamic pupil range (Ayasse et al., 2017; Piquado et al., 2010)) must have min pupil and max pupil size merged into df to work

Usage

dynamic_pupil(pupil_col, dmin = NA, dmax = NA)

Arguments

Value

return dynamic pupil size scaled to P

Description

Extends blinks if not already done in SR Data Viewer

Usage

extend_blinks(values, fillback = 5, fillforward = 5, hz = NA)

Arguments

Value

vector containing extended blinks

Description

Take asc files and return important events Collect trial variables for your experiment. #' This code was written by Dr. Holger Mitterer

Usage

find_messages_asc(
  dirList,
  homeDir = "./",
  time2extract = NULL,
  msg2extract = NULL,
  vars2extract = NULL,
  nOfTrials = -1,
  binocular = FALSE
)

Arguments

Description

Collect trial variables for your experiment.

Usage

find_messages_edf(file_list, varnames, patterns, output_dir)

Arguments

Description

Fixation time course data from a spoken word-to-picture matching study with semantic distractors in the display.

Usage

FunctTheme

Format

A data frame with 1530 rows and 5 variables:

Subject

subject ID, factor

Time

time (in ms) since word onset in 50ms bins

meanFix

fixation proportion (subject mean): proportion of correct-response trials on which the object was fixated

Condition

semantic relatedness condition: Function (e.g., broom - sponge) or Thematic (e.g., broom - dustpan)

Object

object type: Target, semantically related Competitor, or Unrelated

Source

Kalenine et al. (2012, J. Exp. Psychol. Learn. Mem. Cog., 38:5, 1274-1295) http://www.danmirman.org/pdfs/Kalenine_etal2012.pdf

Description

Fixation time course data for participants with left hemisphere stroke from a spoken word-to-picture matching study with semantic distractors in the display.

Usage

FunctThemePts

Format

A data frame with 8199 rows and 8 variables:

Subject

subject ID, factor

Condition

semantic relatedness condition: Function (e.g., broom - sponge) or Thematic (e.g., broom - dustpan)

Object

object type: Target, semantically related Competitor, or Unrelated

Time

time (in ms) relative to word onset in 50ms bins; negative numbers indicate preview period (visual display before word onset)

meanFix

fixation proportion (subject mean): proportion of correct-response trials on which the object was fixated

sumFix

fixation sum: number of correct-response trials on which the object was fixated (i.e., numerator for meanFix)

N

number of correct-response trials (i.e., denominator for meanFix)

Source

Kalenine, Mirman, & Buxbaum (2012, Front. Hum. Neurosci., 6:106, 1-12) http://journal.frontiersin.org/Journal/10.3389/fnhum.2012.00106

Description

Functions for reading and pre-processing eye tracking data.

Author(s)

Maintainer: Jason Geller [email protected]

Authors:

• Jason Geller [email protected]

• Dan Mirman [email protected]

• Tristan Mahr [email protected]

• Matt Winn [email protected]

• Holger Mitterer [email protected]

See Also

Useful links:

• http://github.com/dmirman/gazer

• Report bugs at http://github.com/dmirman/gazer/issues

Description

Takes edf files and converts them to asc This code was written by Dr. Holger Mitterer

Usage

generate_edf2asc_bat(homeDir, subDirs, deleteExisting = F)

Arguments

Description

Use fixation data to calculate two diagnostics of gaze track quality: non-fixation time and out-of-bounds proportion.

Usage

get_gaze_diagnostics(gaze, screen_size = c(1024, 768))

Arguments

Value

data frame containing gaze diagnostics

Description

Takes a model fit with lmer and (optionally) an estimation method, returns a data frame containing fixed effect coefficient estimates, SE, t-values, and p-values. Can use normal approximation, Kenward-Roger approximation for degrees of freedom, or both. If Kenward-Roger approximation is used, result also contains approximated degrees of freedom.

Usage

get_pvalues(model, method = "normal")

Arguments

Value

data frame containing fixed effect estimates, SE, t-values, (degrees of freedom if appropriate) and p-values.

Examples

require(lme4)
model <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
get_pvalues(model)
get_pvalues(model, "KR")

Description

Takes a model and name of a random effect. Returns a data frame containing those random effect estimates arranged and ready for quantifying individual effect sizes.

Usage

get_ranef(model = NULL, ranef_name = NULL)

Arguments

Value

Returns a data frame containing the random effect estimates

Examples

## Not run: 
# FunctTheme example model
FunctTheme.gca <- code_poly(FunctTheme, predictor = "Time", poly.order = 2, draw.poly = FALSE)
m.FT <- lme4::lmer(meanFix ~ (poly1 + poly2) * Object * Condition +
                     (poly1 + poly2 | Subject) + (poly1 + poly2 | Subject:Object:Condition),
                   data = FunctTheme.gca, REML = FALSE)
re <- get_ranef(m.FT, "Subject:Object:Condition")

## End(Not run)

Description

Calculate trackloss and remove trials and subjects with excessive trackloss

Usage

get_trackloss(gaze, screen_size = c(1024, 768), missingthresh = 0.2)

Arguments

Value

data frame containing gaze df with trackloss by subjs and trial. Trials and Subjs with excessive trackloss removed

Description

Perfroms hanning smoothing on pupil data

Usage

hanning_filter(pupil, degree = 11)

Arguments

Value

vector containing hanning filtered pupil data

Description

Turns pupil sizes with blinks NA and linearly interpolates values

Usage

interpolate_pupil(
  datafile,
  pupil,
  subject,
  trial,
  extendblinks = FALSE,
  maxgap = Inf,
  type = c("linear", "cubic"),
  hz = NA
)

Arguments

Value

data frame containing interpolated data

Description

A wrapper function to make setting legend position easier when using ggplot.

Usage

legend_positioning(pos, edge_color = "black", legend_fill = "white")

Arguments

Examples

library(ggplot2)
p <- ggplot(TargetFix, aes(Time, meanFix, color = Condition)) + stat_summary(fun = mean, geom = "line")
p + legend_positioning(c(0,1)) #put legend in upper left corner
p + legend_positioning(c(1,0)) #put legend in lower right corner

Description

This function performs low pass filtering

Usage

lowpass_filter(pd, order, filter_to_use, samplerate = NA)

Arguments

Value

vector containing low pass filtered pupil data

Description

This will make sure your data is in the right format for processing. This package is designed to deal with data at it comes out of the eyetracker in a long-form csv style format. Thus data input here would be a long dataframe, wherein each row is a single frame collected by the eyetracker.

x, y, and pupil may each name a single column or several. A single column is renamed to gazeR's canonical name (x, y, or pupil); when you pass more than one column (e.g. left and right eye) the original column names are kept as-is. Either way the selected columns are moved to the front of the data frame and every other column is kept, in its original order, after them.

Usage

make_gazer(
  data,
  subject = "subject",
  trial = "trial",
  time = "time",
  x = "x",
  y = "y",
  pupil = NULL
)

Arguments

Value

A dataframe ready to use in gazer

Description

Take asc files and extract relevant data Merges eye data (from parse_asc) with message data (from find_messages_asc) This code was written by Dr. Holger Mitterer

Usage

merge_asc_files(dirList, homeDir = "./", dataType = c("fixation", "sample"))

Arguments

Description

Merge eye files from a ufolder if filetype is from sr renames column variables and makes them lower case Places time in ms if edf files just reads them in

Usage

merge_gazer_files(
  file_list,
  blink_colname = "blink",
  pupil_colname = "pupil",
  filetype = "sr"
)

Arguments

Value

data frame containing pupil data

Description

Merge pupil files from a folder Renames column variables and makes them lower case Places time in ms

Usage

merge_pupil(file_list, blink_colname = "", pupil_colname = "", filetype = "sr")

Arguments

Value

data frame containing pupil data

Description

Loads gaze samples and event messages from two parallel folders, attaches each message to the nearest gaze sample by system_time_stamp (as-of merge), assigns trial numbers from onset / offset markers, and rebases time to be trial-relative. The result is one row per gaze sample, with event-marker columns set sparsely on the samples that absorbed an event.

Usage

merge_tobii_titta(
  gaze,
  msg,
  onset_prefix = "onset_",
  offset_prefix = "offset_"
)

Arguments

Details

merge_tobii_titta() reads the split CSVs that the current Titta build emits.

Inputs

Files are paired by basename. A subject's gaze and msg file must share the same filename minus extension, e.g. gaze/sub01.csv <-> msg/sub01.csv. The basename (without extension) becomes subject.

Trial assignment

Trials are identified by message prefixes. Three modes are supported, picked automatically from the data:

• Bracketed (default): ⁠onset_<label>⁠ starts a trial, ⁠offset_<label>⁠ ends it. Samples between an offset and the next onset are dropped.

• Onset-only: pass offset_prefix = NULL, or simply have no rows matching the offset prefix. Each onset runs until the next onset.

• Custom prefixes: override onset_prefix / offset_prefix for any other convention (⁠start_<n>⁠, ⁠startfix_<n>⁠, etc.).

The text following the onset prefix is kept as event_label and broadcast across every sample in that trial – it can be a stim filename, a trial number, a condition tag, whatever your protocol uses.

Nearest-sample merge

Because gaze is sampled on a fixed cadence (30 / 120 / 300 Hz on Tobii trackers) but messages fire asynchronously, a message timestamp almost never exactly equals a sample timestamp. Each message is therefore merged onto the gaze sample whose timestamp is closest, found vectorized via findInterval(). match_offset_us (⁠matched sample ts - msg ts⁠) is exposed for diagnostics; on a 30 Hz tracker this is at most ~16 ms (half the inter-sample gap), and well below 1 ms on a 300 Hz tracker.

Pupil / openness

Raw left_pupil_diameter, right_pupil_diameter, left_eye_openness_diameter, and right_eye_openness_diameter (if present) pass through unchanged. Average them downstream if you want a single signal – gazeR::compute_monocular_mean() or rowMeans(..., na.rm = TRUE).

Output time

time is in milliseconds relative to each trial's first sample (the one the onset message merged onto), matching gazeR's per-trial convention.

Value

A tibble with one row per gaze sample inside a trial window. Leading columns: subject, system_time_stamp, time, msg, message, event, event_label, match_offset_us, trial. The raw Tobii sample columns (gaze x/y, pupil diameter, eye openness, validity flags, etc.) follow.

Examples

## Not run: 
out <- merge_tobii_titta(
  gaze = "data/raw/gaze",
  msg  = "data/raw/msg"
)

# Onset-only recording with custom prefix
out <- merge_tobii_titta(
  gaze = "data/raw/gaze",
  msg  = "data/raw/msg",
  onset_prefix  = "startfix_",
  offset_prefix = NULL
)

## End(Not run)

Description

Creates a moving average using a specified averageing window if n is 5, then it uses the target value, 2 preceding and 2 following

Usage

moving_average_pupil(x, n = 5, centered = TRUE)

Arguments

Value

return sum divided by count

Description

Picture naming data from individuals with aphasia undergoing a treatment trial. Each participant was tested on a 175-item picture naming test (Philadelphia Naming Test) multiple times over the course of the treatment and responses were coded.

Usage

NamingRecovery

Format

A data frame with 115 rows and 9 variables:

SubjectID

subject ID, factor

Diagnosis

participant's aphasia subtype: Anomic, Conduction, or Wernicke's aphasia

TestTime

test iteration, 0 is the baseline at the start of treatment

Correct

proportion correct naming responses

Semantic.error

proportion semantic errors (cat - "dog")

Mixed.error

proportion mixed errors (cat - "rat")

Formal.error

proportion formal errors (cat - "mat")

Unrelated.error

proportion unrelated errors (cat - "log")

Nonword.error

proportion nonword errors (cat - "lat")

Source

Moss Aphasia Psycholinguistics Database <mappd.org>

Description

Centers the sample index or time stamp of your time series to a reference marker, such that 0 always coincides with the onset of a particular event.

Usage

onset_pupil(time, marker, event)

Arguments

Value

Numeric vector that zeroes time to the trial onset. In the event that no onset marker is found, a warning is issued and a vector of NAs is returned.

Description

Take asc files and extract relevant data Does not merge data with messages for fixation data, obtains sample report and puts time in ms This code was written by Dr. Holger Mitterer

Usage

parse_asc(
  dirList,
  homeDir = "./",
  overwriteBlinks = FALSE,
  cutPreview = 0,
  binocular = FALSE
)

Arguments

Description

Take EDF files and return data that is in format usable for gazeR for pupil merges the sample data with the message data (merges on nearest values (millisecond diff between SR and this function) puts time in ms adds subject variable column cleans up the column names creates pupil column that is ambigious as to whether you sampled from left eye, right eye, or both (takes the average) For fixation data, obtains sample report and puts time in ms

Usage

parse_edf(file_list, output_dir, type = "pupil")

Arguments

Description

Take EDF files and return message events to extract behav data creates pupil column that is ambigious to whether you sampled from left eye, right eye, or both (takes the average)

Usage

parse_edf_messages(file_list, output.dir)

Arguments

Description

Reads gaze.csv, ⁠3d_eye_states.csv⁠, events.csv, and gaze_surface.csv from a subject folder, attaches the nearest (non-recording) event to gaze rows (within a lag), defines trial boundaries, removes blank trials, and resets time to 0 within each trial.

Usage

parse_pl(
  subject_dir,
  subject_id = basename(normalizePath(subject_dir)),
  aoi = FALSE,
  max_event_lag_ms = 100,
  start_mode = c("any", "exact"),
  start_messages = NULL
)

Arguments

Value

Tibble: ⁠subject, trial, time, x, y, pupil, blink, message, start_message_first⁠.

Description

Recursively finds immediate subfolders, runs read_pl_subject on each, writes per-subject CSVs and a combined CSV, and invisibly returns the combined tibble.

Usage

process_all_subjects_PL(
  root_dir,
  output_dir = file.path(root_dir, "processed"),
  ...
)

Arguments

Value

Invisibly returns a combined tibble of all processed subjects.

Examples

## Not run: 
process_all_subjects("/path/Timeseries",
                     start_mode = "exact",
                     start_messages = c("trial-started-light", "start-dark"))

## End(Not run)

Description

A fast, single-file reader for EyeLink .asc files (convert .edf with SR Research's edf2asc first). The file is parsed in a few vectorised passes, so even large recordings take seconds. Unlike parse_asc() and find_messages_asc(), it needs no folder-per-subject layout and writes nothing to disk: it returns one long data frame, one row per sample, ready for the pupil functions (extend_blinks(), smooth_interpolate_pupil(), baseline_correction_pupil_msg(), ...), or the shiny gazeR app (https://github.com/jgeller112/shiny-gazeR).

Usage

read_asc(
  file,
  eye = c("average", "left", "right", "both"),
  subject = NULL,
  trial_start = "TRIALID",
  trial_end = "TRIAL_RESULT",
  keep_messages = FALSE
)

Arguments

Details

What it does:

• Trials run from each TRIALID message to the matching TRIAL_RESULT message (both configurable). Samples outside a trial are dropped. time is in ms relative to the start of recording in that trial (the ⁠!MODE RECORD⁠ message, or TRIALID if there is none), matching parse_asc(). The raw tracker clock is kept in tracker_time.

• Messages are attached to the first sample at or after the message time, in a message column. Experiment Builder offsets (⁠MSG <time> <offset> <text>⁠) are applied (time − offset). Tracker housekeeping messages (RECCFG, GAZE_COORDS, ⁠!V DRAW_LIST⁠, ...) are left out of the sample data but kept in the full message table.

• Trial variables written by Experiment Builder (⁠!V TRIAL_VAR name value⁠) become one column per variable, with types guessed by utils::type.convert(). These are usually your condition columns.

• Blinks come from the tracker's SBLINK/EBLINK events (blink is 1 during a blink). Pupil values of 0 and missing gaze (.) become NA.

• Binocular data are handled with eye: "average", "left", "right", or "both" (per-eye columns plus the average). With "average" and "both", pupil, x and y are the mean of the two eyes, computed only where both eyes are valid (otherwise NA), and blink is 1 if either eye is in a blink.

Value

A tibble with one row per sample:

• subject: participant label (file name without extension, or subject).

• trial: trial number (one per TRIALID).

• time: ms from the start of recording in the trial (⁠!MODE RECORD⁠).

• pupil: pupil size in tracker units (area or diameter, see asc_info); NA when missing. For eye = "average"/"both", the mean of both eyes where both are valid.

• x, y: gaze position in screen pixels; NA when missing. Averaged like pupil.

• blink: 1 during a blink, 0 otherwise. For eye = "average"/"both", 1 if either eye is in a blink.

• message: event message(s) attached to this sample, otherwise NA.

• tracker_time: the tracker's own clock (ms).

• With eye = "both": pupil_left, pupil_right, x_left, y_left, x_right, y_right, blink_left, blink_right, each for one eye.

• One column per Experiment Builder trial variable.

Attribute "asc_info" holds the sampling rate (hz), recorded eyes, pupil type (area or diameter) and the eye used.

Examples

## Not run: 
d <- read_asc("data/PN001.asc", eye = "left")
attr(d, "asc_info")$hz

## End(Not run)

Description

Reads eye-tracking recordings stored in the BIDS format for physiological recordings (BEP020): ⁠*_recording-<label>_physio.tsv.gz⁠ files (no header) with JSON sidecars describing their columns, plus optional ⁠*_physioevents.tsv.gz⁠ files with messages and events. Returns one long data frame, one row per sample, in the same layout as read_asc().

Usage

read_bids_eyetrack(
  path,
  eye = c("average", "left", "right", "both"),
  trial_start = NULL
)

Arguments

Details

• Participants: subject is built from the ⁠sub-⁠, ⁠ses-⁠, ⁠task-⁠ and ⁠run-⁠ entities of each file name (e.g. ⁠sub-01_task-rest_run-1⁠).

• Columns: timestamp, x_coordinate, y_coordinate and pupil_size become time, x, y and pupil; other columns are kept. Timestamps are converted to ms from the Units of timestamp in the sidecar (s, ms, us or ns, so Pupil Labs and Tobii conversions work too), or, without units, from the step between samples and SamplingFrequency.

• Eyes: recordings of the left and right eye (e.g. recording-eye1 and recording-eye2, identified by RecordedEye in the sidecar) are merged by timestamp. eye works as in read_asc(): "average" (mean of both eyes where both are valid; blink is 1 if either eye blinks), "left", "right", or "both" (per-eye columns plus the average).

• Events: rows of ⁠*_physioevents.tsv.gz⁠ with a message are attached to the first sample at or after their onset; rows with trial_type == "blink" (or blink == 1) mark blink for their duration.

• Trials: a BIDS recording is continuous, so by default each run is one trial. With trial_start, a new trial starts at each message matching one of these strings, and time is ms from that message; samples before the first one are dropped.

Value

A tibble with subject, trial, time, pupil, x, y, blink, message, tracker_time, sample_rate, eyes_recorded and any extra columns. Attribute "bids_info" has one row per subject with sample_rate, eyes_recorded, manufacturer and pupil_units from the sidecars, and blink_events (whether any blink events were found).

Examples

## Not run: 
d <- read_bids_eyetrack("my_bids_dataset", eye = "left")
d <- read_bids_eyetrack("my_bids_dataset", trial_start = "TRIALID")

## End(Not run)

Description

Reads in a fixation report created by EyeLink's EyeDataViewer application

Usage

read_fixation_report(
  filename,
  screen_size = c(1024, 768),
  name_changes = c(Subject = "RECORDING_SESSION_LABEL", ACC = "StimSlide.ACC", RT =
    "StimSlide.RT", TargetLoc = "CorrectPort"),
  plot_fix_scatter = TRUE,
  pages = 1
)

Arguments

Value

gaze data frame containing fixation report

Description

Brings each participant's data to target_hz, working within each subject and trial:

Usage

resample_gaze(
  x,
  target_hz,
  hz = NULL,
  pupil_cols = c("pupil", "pupil_left", "pupil_right"),
  gaze_cols = c("x", "y", "x_left", "y_left", "x_right", "y_right"),
  blink_cols = c("blink", "blink_left", "blink_right"),
  event_cols = "message",
  interpolate = TRUE
)

Arguments

Details

• Downsampling (recorded rate above target_hz): consecutive samples are averaged into bins of 1000 / target_hz ms, which avoids aliasing. Pupil and gaze values are the bin mean, and are NA if any sample in the bin is missing (pupil values ⁠<= 0⁠ count as missing). Blink columns are 1 if any sample in the bin was in a blink. Event columns keep every message in the bin (joined with "; "). Other columns take the bin's first value. time becomes the start of the bin.

• Upsampling (recorded rate below target_hz): new samples are added with upsample_gaze(). With interpolate = TRUE, their pupil and gaze values are linearly interpolated from the recorded samples either side, and left NA if either neighbour is missing (e.g. during a blink).

• Same rate: each trial is put on an evenly spaced grid, inserting any samples the tracker dropped as NA (never interpolated), ready for the usual blink and interpolation steps.

Inserted samples are flagged in a resampled column. Upsampling and the uniform grid need a whole-millisecond step (e.g. 1000, 500, 250 Hz).

Value

x at target_hz, sorted by subject, trial and time, with a logical resampled column (TRUE for samples added by upsampling or gap filling).

See Also

upsample_gaze(), downsample_pupil() and downsample_gaze() (which average into analysis time bins rather than resample).

Examples

x <- data.frame(subject = "s1", trial = 1, time = 0:9,
                pupil = c(1000:1003, NA, 1005:1009), message = NA)
x$message[3] <- "stim"
resample_gaze(x, target_hz = 500)   # 1000 -> 500 Hz

Description

Smooths the pupil trace before linear or cubic interpolation.

Usage

smooth_interpolate_pupil(
  datafile,
  pupil = "pupil",
  extendpupil = "extendpupil",
  extendblinks = FALSE,
  step.first = "smooth",
  filter = "moving",
  maxgap = Inf,
  type = NULL,
  hz = NA,
  n = NA
)

Arguments

Value

df containing interpolated data

Description

Calculates max absoulte dilation speed as suggested in Kret & Sjak-Shie (in press) calculates the median absoulte deviation (MAD) and sets the threshold to filter on.

Usage

speed_pupil(pup, time)

Arguments

Value

data with pupil speeds for each time point

Description

Time course of target object fixation during a spoken word-to-picture matching (i.e., "visual world paradigm").

Usage

TargetFix

Format

A data frame with 300 rows and 7 variables

Subject

subject ID, factor

Time

time (in ms) relative to word onset in 50ms bins, 300-1000

timeBin

rescaling of Time variable for easier model-fitting, 1-15

Condition

word frequency condition: High (e.g., torch, frog) or Low (e.g., class, horse)

meanFix

fixation proportion (subject mean): proportion of correct-response trials on which the object was fixated

sumFix

fixation sum: number of correct-response trials on which the object was fixated (i.e., numerator for meanFix)

N

number of correct-response trials (i.e., denominator for meanFix)

Description

Increase the sampling frequency to target_hz Hz by inserting additional rows. Missing values in gaze and pupil data will be preserved for later interpolation.

Usage

upsample_gaze(
  x,
  pupil_cols = c("Pupil_Diameter"),
  gaze_cols = c("x_pred_normalised", "y_pred_normalised"),
  target_hz = 1000,
  upsample_pupil = TRUE,
  event_cols = c("message")
)

Arguments

Details

Original rows are returned unchanged. Each inserted row takes its other columns (e.g. condition, trial variables) from the original sample before it, except pupil_cols/gaze_cols (left NA for interpolation) and event_cols (left NA, so each event message still appears once).

Value

A dataframe with up-sampled time points and an up_sampled column (TRUE for inserted rows, FALSE for original ones).

Description

Accuracy in 2-alternative forced-choice word learning experiment. On each trial, participants see two complex geometric shapes, hear a novel word (e.g., "pibu"), and have to guess which object corresponds to the word. They receive feedback and gradually learn which object goes with which word. There are 6 trials in each of the 10 training blocks. Transitional probability of the novel words (i.e., p("bu"|"pi")) was experimentally manipulated (between-subjects) during an exposure phase immediately preceding the word learning phase.

Usage

WordLearnEx

Format

A data frame with 560 rows and 4 variables

Subject

subject id, N=56

TP

transitional probability of words, manipulated between-subjects

Block

training block (1-10), each block consists of 6 trials

Accuracy

proportion correct responses during the block, chance = 0.5

Source

Partial data from Mirman et al. (2008, Cognition, 108:1, 271-280). http://www.danmirman.org/pdfs/MirmanMagnusonGrafEstesDixon2008.pdf