Module: gaze

Nodes for Gaze (Eye Tracking) analysis.

These nodes are for processing of eye-tracker data or other eye movement measures.

AdaptiveThreshold

Calculate adaptive threshold.

Calculate threshold based on the following equation: Th = MED + alpha x MAD x 1.4826, where MED is the median of the given data, MAD is median absolute deviation, and alpha and beta are constant. The default values for alpha and beta based on [1] set to: alpha = 3 [1] https://pdfs.semanticscholar.org/07be/e9c26ac092bd8ea1c0b907fb6eabba145ce4.pdf

Version 1.0.0

Ports/Properties

• 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)
    

• data
  Data to process.

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

• outdata
  Calculated threshold.

  • verbose name: Outdata
  • default value: None
  • port type: DataPort
  • value type: float (can be None)
  • data direction: OUT
    

• alpha
  Threshold in (robust) standard deviations.

  • verbose name: Alpha
  • default value: 3.0
  • port type: FloatPort
  • value type: float (can be None)
    

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

• 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)
    

• 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)
    

GazeScreenCoordinateConversion

Perform coordinate conversions on gaze data.

Conversions are related to the screen resolution, viewer distance, etc. Normalized coordinates are between 0 and 1 (not between -0.5 and +0.5). However, meters, centimeters, degrees and radians are measured relative to the screen center and can therefore be negative. This expects the screen metadata to be stored in the chunk properties. Use the SetGazeMetadata node if you need to set that data (i.e., if it is not present in the original gaze data).

Version 1.0.0

Ports/Properties

• 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)
    

• data
  Data to process.

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

• convert_from
  Current units.

  • verbose name: Convert From
  • default value: pixels
  • port type: EnumPort
  • value type: str (can be None)
    

• convert_to
  Units to convert to.

  • verbose name: Convert To
  • default value: degrees
  • port type: EnumPort
  • value type: str (can be None)
    

• correct_flat
  Correct for screen being flat. Only relevant in conversions between angular and linear measures.

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

• convert_instance_fields
  List of instance axis data field names (table columns) to convert as well.

  • verbose name: Convert Instance Fields
  • default value: None
  • port type: ListPort
  • value type: list (can be None)
    

SanitizeGazeData

Clean up gaze data before extracting gaze events.

Removes bad gaze data identified either as NaN values or as values in a 'Confidence' channel below a configurable threshold. Provides the option to either drop or interpolate the removed data. Typically used before the ExtractGazeEvents node as needed. To manually set sample values to NaN, precede this node with the ReplaceValues node.

Version 0.1.2

Ports/Properties

• 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)
    

• data
  Data with gaze stream(s)

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

• confidence_threshold
  Minimum confidence to keep a sample. Confidence channel must be named 'confidence' or 'Confidence', which should be true from Tobii data and Pupil Labs data.

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

• confidence_channel
  Label of channel to monitor for confidence_threshold. Note: case insensitive!

  • verbose name: Confidence Channel
  • default value: Confidence
  • port type: StringPort
  • value type: str (can be None)
    

• handle_bad
  'Bad' samples are those that met one of the criteria, either nan or low-confidence. There are three options to handle bad samples: 1) drop: samples are dropped if any criterion is met, even on a single channel. 2) interpolate: samples will be interpolated independently for each channel. 3) cross-interpolate: nan values are interpolated then the result is shifted by the deviation found between the interpolated value and the real value in other channels in its channel-group. Channels are grouped according to interp_identifiers.

  • verbose name: Handle Bad
  • default value: drop
  • port type: EnumPort
  • value type: str (can be None)
    

• interp_identifiers
  For the case that 'cross-interpolate' is selected from the above option, this determines identifier sub-strings for labels of each channel in a pair. Channels with matching names except for this sub-string are paired. Typical use case is to pair similar channels from the two eyes. For Tobii data this should be ['left', 'right']. For Pupil Labs, ['0', '1']. Currently only used by the cross-interpolate method of handle_bad.

  • verbose name: Left/right Channel Name Pattern
  • default value: ['left', 'right']
  • port type: ListPort
  • value type: list (can be None)
    

• excl_identifiers
  Channels with labels matching any of these identifier sub-strings will not be sanitized. Note that the confidence channel is excluded automatically.

  • verbose name: Ignore Channels Containing Patterns
  • default value: []
  • port type: ListPort
  • value type: list (can be None)
    

SetGazeMetaData

Overwrite the screen-related metadata of a gaze stream.

Will fall back to the current screen if parameters not specified. This node is best used before using the GazeScreenCoordinateConversion node to facilitate conversion of gaze units. It is often necessary to convert gaze units prior to using the ExtractGazeEvents node whose default parameters expect certain units.

Version 0.0.3

Ports/Properties

• 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)
    

• data
  Data to process.

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

• screen_index
  If the screen resolution and dimensions arguments are not provided then the fallback will use the screen dimensions of one of the connected screens. Set this argument to the index of the attached screen from which to extract the dimensions. Defaults to 0 (first display).

  • verbose name: Screen Number
  • default value: None
  • port type: IntPort
  • value type: int (can be None)
    

• screen_distance
  Viewer distance from screen in meters.

  • verbose name: Screen Distance
  • default value: None
  • port type: FloatPort
  • value type: float (can be None)
    

• screen_resolution
  [X, Y] screen resolution in pixels. This argument must be complemented with either screen_dimensions or screen_dpi, otherwise this value is not used and the fallback will be used.

  • verbose name: Screen Resolution
  • default value: None
  • port type: ListPort
  • value type: list (can be None)
    

• screen_dimensions
  [X, Y] screen width and height dimensions in meters. (For reference: 24 inches = 0.61 m; 27 inches = 0.69 m)

  • verbose name: Screen Dimensions
  • default value: None
  • port type: ListPort
  • value type: list (can be None)
    

• screen_dpi
  Screen pixel density measured in Dots Per Inch.

  • verbose name: Screen Dpi
  • default value: None
  • port type: FloatPort
  • value type: float (can be None)