popEye: Main popEye encoding function
In sascha2schroeder/popEye: Analysis of eye-tracking data from reading experiments

popEye

R Documentation

Main popEye encoding function

Description

This function is used when you want to analyze eye tracking data using popEye.

Usage

popEye(
  datpath,
  stimulus.file,
  tracker.model = "eyelink",
  tracker.software = "EB",
  tracker.results = NA,
  type = "sentence",
  message.start = "SYNCTIME",
  message.stop = "stop",
  message.boundary = "boundary",
  message.target = "target",
  message.prime = "prime",
  variable.id = "id",
  variable.cond = NA,
  item.practice = "^P",
  item.trigger = "999",
  item.question = 1000,
  item.pracnum = 0,
  stimulus.id = "id",
  stimulus.cond = NA,
  stimulus.preview = "preview",
  stimulus.prime = "prime",
  stimulus.text = "text",
  stimulus.hyphenwrap = T,
  indicator.word = "",
  indicator.ia = "",
  indicator.target = "\\*",
  indicator.line = "\\\\n",
  separator.word = " ",
  separator.sentence = c(".", "!", "?", ";"),
  separator.sentence2 = c(" ", "\""),
  display.marginLeft = 150,
  display.marginTop = 300,
  display.marginRight = 50,
  display.marginBottom = 100,
  font.name = "CourierNew",
  font.size = 16,
  font.spacing = 2,
  font.wrap = TRUE,
  analysis.eyelink = TRUE,
  analysis.smooth = 5,
  analysis.vfac = 5,
  analysis.mindur = 10,
  analysis.postdur = 30,
  analysis.drift = 1,
  analysis.sparse = TRUE,
  assign.driftX = FALSE,
  assign.driftY = FALSE,
  assign.outlier = TRUE,
  assign.outlierDist = 0.2,
  assign.moveMethod = "hit",
  assign.moveX = FALSE,
  assign.moveY = FALSE,
  assign.lineMethod = "chain",
  assign.lineX = 35,
  assign.lineY = 0.5,
  assign.lineS = 0.45,
  assign.lineN = 1.5,
  clean.stage1Dur = 80,
  clean.stage1Dist = 1,
  clean.stage2Dur = 40,
  clean.stage2Dist = 3,
  clean.stage3 = FALSE,
  clean.stage3Dur = 140,
  clean.stage4 = FALSE,
  clean.stage4Min = 80,
  clean.stage4Max = 800,
  clean.delete = FALSE,
  clean.outlier = FALSE,
  exclude.nfix = 3,
  exclude.sac = 150,
  outpath = getwd(),
  outname = "",
  select.version = NULL,
  select.subjects = NULL,
  skip.subjects = NULL,
  select.items = NULL,
  skip.items = NULL,
  select.trials = NULL,
  skip.trials = NULL,
  debug = "none"
)

Arguments

`datpath`	Path to eye tracking files
`stimulus.file`	Path and name of stimulus file
`tracker.model`	Eye tracker used for data collection (only "eyelink" available at present)
`tracker.software`	Software used for data collection ("EB" for "Experiment Builder" or "ET" for "EyeTrack")
`tracker.results`	Name of the results file that is generated by the eye tracking software (if any)
`type`	Type of experiment used in the study ("text", "sentence", "target", "boundary", "fast")
`message.start`	Message in eye tracking file indicating the start of the trial
`message.stop`	Message in eye tracking file indicating the end of the trial
`message.boundary`	Message in eye tracking file indicating when the boundary is triggered (only relevant for boundary and fast priming experiments)
`message.target`	Message in eye tracking file indicating the onset of the target display (only relevant for boundary experiments)
`message.prime`	Message in eye tracking file indicating the onset of the prime display (only relevant for fast priming experiments)
`variable.id`	Variable in eye tracking experiment indicating which item is displayed in a trial ("id" by default)
`variable.cond`	Variable in eye tracking experiment indicating in which (within-item) condition the item is displayed in a trial (if any; no conditions by default)
`item.practice`	Indicator for a practice item that is displayed at the beginning of an experiment (only relevant for EyeTrack experiments)
`item.trigger`	Indicator for an gaze trigger element used in the experiment (only relevant for EyeTrack experiments)
`item.question`	Indicator for a comprehension question trial used during the experiment (only relevant for EyeTrack experiments)
`item.pracnum`	Number of practice items shown at the beginning of an experiment (which are discarded during the analysis)
`stimulus.id`	Name of the column providing the item number in stimulus file
`stimulus.cond`	Name of the column providing the condition name in the stimulus file
`stimulus.preview`	Name of the column providing the preview display in the stimulus file (only relevant for boundary and fast priming experiments)
`stimulus.prime`	Name of the column providing the prime display in the stimulus file (only relevant for fast priming experiments)
`stimulus.text`	Name of the column providing the target (or only) display in the stimulus file
`stimulus.hyphenwrap`	Indicator whether words are split at hyphens at line breaks (default is TRUE)
`indicator.word`	Indicator used to separate words from each other (empty by default)
`indicator.ia`	Indicator used to separate interest areas from each other (words are used as interest areas by default)
`indicator.target`	Indicator used to denote the target interest area ("*" by default)
`indicator.line`	Indicator used for manual line breaks ("\n" by default)
`separator.word`	Characters used to separate words from each other (white space by default)
`separator.sentence`	Characters used to separate sentences (.!? by default)
`display.marginLeft`	Size of the margin at the left of the screen (in pixels)
`display.marginTop`	Size of the margin at the top of the screen (in pixels)
`display.marginRight`	Size of the margin at the right of the screen (in pixels)
`display.marginBottom`	Size of the margin at the bottom of the screen (in pixels)
`font.name`	Name of the font used in the experiment (currently, "Arial", "CourierNew","Consolas", "Times New Roman", and "Symbol" are supported for most font sizes between 12 and 24 pt in steps of 2)
`font.size`	Size of the font (in pixels, 16 by default)
`font.spacing`	Spacing between lines (numeric, 2 by default)
`analysis.eyelink`	Should the real-time parsing from the eyelink system be used? (TRUE or FALSE, default is TRUE)
`analysis.smooth`	Amount of smoothing applied to raw x and y data. Number of samples used to compute a (two-sided) moving average (numeric, default is 5)
`analysis.vfac`	Velocity threshold used for saccade detection (see Engbert & Kliegl, 2003; default is 5)
`analysis.mindur`	Minimum duration of a saccade (see Engbert & Kliegl, 2003; default is 10 ms)
`analysis.postdur`	Minimum duration of a fixation (see Engbert & Kliegl, 2003; default is 30 ms)
`analysis.drift`	Threshold for the decision whether a fixation is treated as a blink; amount of drift on the x or y dimension in terms of the font height (numeric; default is 1. See Engbert & Kliegl, 2003)
`analysis.sparse`	If TRUE, the msg, sample, and event slots are cleaned during the analysis (TRUE or FALSE, default is TRUE)
`assign.driftX`	If TRUE fixation is corrected for drift on the x axis (TRUE or FALSE, default is FALSE; only relevant for EB experiments in which the drift correct element is used)
`assign.driftY`	If TRUE fixation is corrected for drift on the y axis (TRUE or FALSE, default is FALSE; only relevant for EB experiments in which the drift correct element is used)
`assign.outlier`	Indicates whether outlier detection should be carried out (fixations deviating from the text box in the x and y dimension by a certain amount are flagged as outliers, default is TRUE)
`assign.outlierDist`	Parameter that controls the definition of the outlier (i.e., the necessary distance to the text area in input values 0-1, default is 0.2)
`assign.moveMethod`	If TRUE fixations are moved on the x axis to fit into text area (TRUE or FALSE, default is FALSE)
`assign.moveX`	If TRUE fixations are moved on the x axis to fit into text area (TRUE or FALSE, default is FALSE)
`assign.moveY`	If TRUE fixations are moved on the y axis to fit into text area (TRUE or FALSE, default is FALSE)
`assign.lineMethod`	Method used to assign fixations to lines ("attach", "chain" or "merge", "chain" is default; see Vignette)
`assign.lineX`	Parameter used to detect runs on the x axis (default is 35)
`assign.lineY`	Parameter used to detect runs on the y axis (default is 0.5)
`assign.lineS`	Parameter used to decide that two lines are the same (only relevant for the slice assignment method, default is 0.45)
`assign.lineN`	Parameter used to decide that two lines are different (only relevant for the slice assignment method, default is 0.5)
`clean.stage1Dur`	Minimum duration for fixation during stage 1 cleaning (default: 80 ms)
`clean.stage1Dist`	Minimum distance between fixations (in number of letters) during stage 1 cleaning (default: 1)
`clean.stage2Dur`	Minimum duration of fixation during stage 2 cleaning (default: 40 ms)
`clean.stage2Dist`	Minimum distance between fixations (in number of letters) during stage 2 cleaning
`clean.stage3`	If TRUE, stage 3 cleaning is conducted (default is FALSE)
`clean.stage3Dur`	Minimum duration of fixation during stage 3 cleaning (default is 140 ms)
`clean.stage4`	If TRUE stage 4 cleaning is conducted (default is FALSE)
`clean.stage4Min`	Minimum duration of fixation during stage 4 cleaning (default is 80 ms)
`clean.stage4Max`	Maximum duration of fixation during stage 4 cleaning (default is 800 ms)
`clean.outlier`	If TRUE outlying fixations at the begining and the end of a trial are deleted (default is FALSE)
`exclude.nfix`	Minimum number of fixations that a trial has to have received (deleted otherwise; default is 3)
`exclude.sac`	Duration for screen for unplausibel long saccades (in ms; 200 ms as default).
`outpath`	Path were output file should be saved
`outname`	Name of output file
`select.version`	Restrict analysis to a specific version of the experiment (numeric; internal for debugging; only relevant for EB experiments)
`select.subjects`	Restrict analysis to a subset of subjects (within a version). Select a single subject by providing the corresponding subject ID, e.g., select.subjects = "t01". Select a set of subjects by providing a vector, e.g., select.subjects = c("t01", t02").
`skip.subjects`	Remove a subset of subjects (within a version) from the analysis. Select a single subject by providing the corresponding subject ID, e.g., skip.subjects = "t01". Select a set of subjects by providing a vector, e.g., skip.subjects = c("t01", t02").
`select.items`	Restrict analysis to a subset of trials (usually within a single subject). Select a single item by providing the corresponding item ID, e.g., select.items = "item01". Select a set of itemss by providing a vector, e.g., select.items = c("item01", item02").
`skip.items`	Remove a subset of items (within a version) from the analysis. Select a single item by providing the corresponding item ID, e.g., skip.item = "item01". Select a set of items by providing a vector, e.g., skip.items = c("item01", "item02").
`select.trials`	Restrict analysis to a subset of trials (usually within a single subject). The difference between "items" and "trials" is just that the trials are selected by their item ID and "trials" by the position within the analysis. Both arguments can also be combined. Select a single trial by providing the corresponding trial ID, e.g., select.trials = 1. Select a set of trials by providing a vector, e.g., select.trials = c(1, 2).
`skip.trials`	Remove a subset of trials (within a version) from the analysis. Select a single trial by providing the corresponding trial ID, e.g., skip.trials = 10. Select a set of trials by providing a vector, e.g., skip.trials = c(10, 11).
`debug`	Perform analysis only for specific steps of the analysis ("setup", "subjects", "read", "remove", "create", "add", "extract", "line", "assign", "combine", "aggregate")
`exclude.blink`	If TRUE a trial is flagged as critical if at least one blink has occured on it (default is FALSE)