Skip to content

← gaze package

ExtractGazeEvents

Detect fixations and saccades in continuous gaze data.

Incoming gaze data must have a time axis. Detected events are used to create entries in a new Instance axis. Gaze-event detection parameters are often expected to be in specific units such as degrees of visual angle. Precede this node by the SetGazeMetaData and GazeScreenCoordinateConversion nodes to convert the gaze data to the expected units. Version 0.1.2

Ports/Properties

data

Data with Pupil Stream(s)

  • verbose name: Data
  • default value: None
  • port type: DataPort
  • value type: Packet (can be None)
  • data direction: INOUT

fixation_algorithm

none: Do not create fixation events. between saccades: Use the saccade algorithm only, and segments between saccades are assumed fixations. I-VT: Velocity threshold based algorithm described in Salvucci and Goldberg 2000. I-DT: Dispersion threshold algorithm described in Salvucci and Goldberg 2000.

  • verbose name: Fixation Algorithm
  • default value: I-DT
  • port type: EnumPort
  • value type: str (can be None)

saccade_algorithm

none: Do not create saccade events; between fixations: Use the fixation algorithm only, and segments between fixations are assumed saccades; V+A threshold: Velocity and Amplitude threshold, based on Armstrong et al Neuron 50, 791-798, June 1, 2006. Currently works in offline-mode only.

  • verbose name: Saccade Algorithm
  • default value: between fixations
  • port type: EnumPort
  • value type: str (can be None)

min_fixation_duration

Minimum duration (in seconds) of contiguous data meeting other fixation criteria for the segment of data to be considered a fixation.

  • verbose name: Min Fixation Duration
  • default value: 0.1
  • port type: FloatPort
  • value type: float (can be None)

max_fixation_duration

Maximum duration (in seconds) of contiguous data meeting other fixation criteria that can still be considered a single fixation. Note that if this is None and using I-VT then fixations may also include smooth pursuit, or if this is not None and using I-DT then fixations may also include smooth pursuit.

  • verbose name: Max Fixation Duration
  • default value: None
  • port type: FloatPort
  • value type: float (can be None)

dispersion_threshold

The maximum dispersion distance allowed beyond which the most recent data point will be considered part of a new event. Pupil Labs uses 3 degrees. Dispersion threshold doubles as a distance threshold for dejittering when using I-VT.

  • verbose name: Dispersion Threshold
  • default value: 1.0
  • port type: FloatPort
  • value type: float (can be None)

robust_dispersion_frac

The proportion (0,1) of largest dispersions to be included when estimating (median) the dispersion. Set to 0 to use only the single maximum (efficient codepath). If you find that your fixation events are terminating prematurely, then you can increase this number to .1 or .2. Alternatively, you can increase the dispersion threshold.

  • verbose name: Robust Dispersion Frac
  • default value: 0.0
  • port type: FloatPort
  • value type: float (can be None)

merge_fixation_distance_threshold

Consecutive uninterrupted fixations with fixation points separated by less than this amount will be merged into a single fixation.

  • verbose name: Merge Fixation Distance Threshold
  • default value: 0.5
  • port type: FloatPort
  • value type: float (can be None)

velocity_threshold

For I-VT only: The maximum velocity allowed beyond which the most recent data point will be considered part of a saccade. Sen and Megaw use 20; Komogortsev recommends (?) 70, 20-50?;

  • verbose name: Velocity Threshold
  • default value: 8.0
  • port type: FloatPort
  • value type: float (can be None)

distance_metric

https://docs.s cipy.org/doc/scipy/reference/generated/scipy.spatial.distance.cdist.html

  • verbose name: Distance Metric
  • default value: euclidean
  • port type: EnumPort
  • value type: str (can be None)

dejitter

Dejittering is only supported when using velocity thresholding. It doesn't make sense in the context of dispersion thresholding; just use a larger threshold if your data are noisy. The dejittering algorithm is described in a paper titled Improving the Accuracy of Gaze Input for Interaction by Kumar and Klingner. http://graphics.stanford.edu/~klingner/publications/GazeInputAccuracy.pdf

  • verbose name: Dejitter
  • default value: False
  • port type: BoolPort
  • value type: bool (can be None)

set_breakpoint

Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

  • verbose name: Set Breakpoint (Debug Only)
  • default value: False
  • port type: BoolPort
  • value type: bool (can be None)

metadata

User-definable meta-data associated with the node. Usually reserved for technical purposes.

  • verbose name: Metadata
  • default value: {}
  • port type: DictPort
  • value type: dict (can be None)