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 based on the following equation: Th = MED + alpha x MAD x 1.4

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

Process pupil gaze data and detect fixations and saccades, extracting each event and placing in a trial along a new Instance axis.

Adds the following metadata to the instance.data field for each event. Incoming data must have a time axis.

Version 0.1.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)
  • 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: object (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: object (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: object (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 related to the screen resolution, viewer distance, and so forth.

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)
  • 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: object (can be None)
  • convert_to
    Units to convert to.

    • verbose name: Convert To
    • default value: degrees
    • port type: EnumPort
    • value type: object (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)

SanitizeGazeData

Clean up gaze data before extracting gaze events (with ExtractGazeEvents), by removing NaN data, data with low confidence (using a configurable threshold), etc.

Provides the option to either drop or interpolate the removed data. Typically used before the ExtractGazeEvents node as needed. If the bad gaze data are not already tagged with nan, then precede this node with a ReplaceValues node.

Version 0.1.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)
  • 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: object (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: Interp Identifiers
    • 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: Excl Identifiers
    • default value: []
    • port type: ListPort
    • value type: list (can be None)

SetGazeMetaData

Used to overwrite the screen related metadata of a packet with gaze data.

Will fall back to the current screen if not specified.

Version 0.0.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)
  • data
    Data to process.

    • verbose name: Data
    • default value: None
    • port type: DataPort
    • value type: Packet (can be None)
    • data direction: INOUT
  • screen_index
    Only used when resolution and dimensions are not provided and is used to get resolution and dpi of monitor in current setup. 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. In addition to screen_resolution, screen_dimensions or screen_dpi must be provided, otherwise this value is not used and the dimensions of the current screen at index screen_index is used.

    • verbose name: Screen Resolution
    • default value: None
    • port type: ListPort
    • value type: list (can be None)
  • screen_dimensions
    [X, Y] screen dimensions in meters. 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
    Dots per inch.

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