Gaze movement
=============

## Definition

!!! note

        *"The act of classifying eye movements into distinct events is, on a general level, driven by a desire to isolate different intervals of the data stream strongly correlated with certain oculomotor or cognitive properties."* 

        Citation from ["One algorithm to rule them all? An evaluation and discussion of ten eye movement event-detection algorithms"](https://link.springer.com/article/10.3758/s13428-016-0738-9) article.

[GazeFeatures](../../../argaze/#argaze.GazeFeatures) defines abstract [GazeMovement](../../../argaze/#argaze.GazeFeatures.GazeMovement) class, then abstract [Fixation](../../../argaze/#argaze.GazeFeatures.Fixation) and [Saccade](../../../argaze/#argaze.GazeFeatures.Saccade) classes which inherit from [GazeMovement](../../../argaze/#argaze.GazeFeatures.GazeMovement).

The **positions** [GazeMovement](../../../argaze/#argaze.GazeFeatures.GazeMovement) attribute contain all [GazePositions](../../../argaze/#argaze.GazeFeatures.GazePosition) belonging to itself.

![Fixation and Saccade](../../img/fixation_and_saccade.png)

## Identification

[GazeFeatures](../../../argaze/#argaze.GazeFeatures) defines abstract [GazeMovementIdentifier](../../../argaze/#argaze.GazeFeatures.GazeMovementIdentifier) classe to let add various identification algorithms.

Some gaze movement identification algorithms are available thanks to [GazeAnalysis](../../../argaze/#argaze.GazeAnalysis) submodule:

* [Dispersion threshold identification (I-DT)](../../../argaze/#argaze.GazeAnalysis.DispersionThresholdIdentification)
* [Velocity threshold identification (I-VT)](../../../argaze/#argaze.GazeAnalysis.VelocityThresholdIdentification)

### Identify method

[GazeMovementIdentifier.identify](../../../argaze/#argaze.GazeFeatures.GazeMovementIdentifier.identify) method allows to fed its identification algorithm with successive gaze positions to output Fixation, Saccade or any kind of GazeMovement instances.

Here is a sample of code based on [I-DT](../../../argaze/#argaze.GazeAnalysis.DispersionThresholdIdentification) algorithm to illustrate how to use it:

``` python
from argaze import GazeFeatures
from argaze.GazeAnalysis import DispersionThresholdIdentification

# Create a gaze movement identifier based on dispersion algorithm with 50px max deviation 200 ms max duration thresholds
gaze_movement_identifier = DispersionThresholdIdentification.GazeMovementIdentifier(50, 200)

# Assuming that timestamped gaze positions are provided through live stream or later data reading
...:

        gaze_movement = gaze_movement_identifier.identify(timestamp, gaze_position)

        # Fixation identified
        if GazeFeatures.is_fixation(gaze_movement):

                # Access to first gaze position of identified fixation
                start_ts, start_position = gaze_movement.positions.first

                # Access to fixation duration
                print('duration: {gaze_movement.duration}')

                # Iterate over all gaze positions of identified fixation
                for ts, position in gaze_movement.positions.items():

                        # Do something with each fixation position
                        ...

        # Saccade identified
        elif GazeFeatures.is_saccade(gaze_movement):

                # Access to first gaze position of identified saccade
                start_ts, start_position = gaze_movement.positions.first

                # Access to saccade amplitude
                print('amplitude: {gaze_movement.amplitude}')

                # Iterate over all gaze positions of identified saccade
                for ts, position in gaze_movement.positions.items():

                        # Do something with each saccade position
                        ...

        # No gaze movement identified
        else:

                continue

```

### Browse method

[GazeMovementIdentifier.browse](../../../argaze/#argaze.GazeFeatures.GazeMovementIdentifier.browse) method allows to pass a [TimeStampedGazePositions](../../../argaze/#argaze.GazeFeatures.TimeStampedGazePositions) buffer to apply identification algorithm on all gaze positions inside.

Identified gaze movements are returned through:

* [TimeStampedGazeMovements](../../../argaze/#argaze.GazeFeatures.TimeStampedGazeMovements) instance where all fixations are stored by starting gaze position timestamp.
* [TimeStampedGazeMovements](../../../argaze/#argaze.GazeFeatures.TimeStampedGazeMovements) instance where all saccades are stored by starting gaze position timestamp.
* [TimeStampedGazeStatus](../../../argaze/#argaze.GazeFeatures.TimeStampedGazeStatus) instance where all gaze positions are linked to a fixation or saccade index.

``` python
# Assuming that timestamped gaze positions are provided through data reading

ts_fixations, ts_saccades, ts_status = gaze_movement_identifier.browse(ts_gaze_positions)

```

* ts_fixations would look like:

|timestamp|positions                                                     |duration|dispersion|focus    |
|:--------|:-------------------------------------------------------------|:-------|:---------|:--------|
|60034    |{"60034":[846,620], "60044":[837,641], "60054":[835,649], ...}|450     |40        |(840,660)|
|60504    |{"60504":[838,667], "60514":[838,667], "60524":[837,669], ...}|100     |38        |(834,651)|
|...      |...                                                           |...     |..        |...      |

* ts_saccades would look like:

|timestamp|positions                               |duration|
|:--------|:---------------------------------------|:-------|
|60484    |{"60484":[836, 669], "60494":[837, 669]}|10      |
|60594    |{"60594":[833, 613], "60614":[927, 601]}|20      |
|...      |...                                     |...     |

* ts_status would look like:

|timestamp|position  |type    |index|
|:--------|:---------|:-------|:----|
|60034    |(846, 620)|Fixation|1    |
|60044    |(837, 641)|Fixation|1    |
|...      |...       |...     |.    |
|60464    |(836, 668)|Fixation|1    |
|60474    |(836, 668)|Fixation|1    |
|60484    |(836, 669)|Saccade |1    |
|60494    |(837, 669)|Saccade |1    |
|60504    |(838, 667)|Fixation|2    |
|60514    |(838, 667)|Fixation|2    |
|...      |...       |...     |.    |
|60574    |(825, 629)|Fixation|2    |
|60584    |(829, 615)|Fixation|2    |
|60594    |(833, 613)|Saccade |2    |
|60614    |(927, 601)|Saccade |2    |
|60624    |(933, 599)|Fixation|3    |
|60634    |(934, 603)|Fixation|3    |
|...      |...       |...     |.    |


!!! note
        [TimeStampedGazeMovements](../../../argaze/#argaze.GazeFeatures.TimeStampedGazeMovements), [TimeStampedGazeMovements](../../../argaze/#argaze.GazeFeatures.TimeStampedGazeMovements) and [TimeStampedGazeStatus](../../../argaze/#argaze.GazeFeatures.TimeStampedGazeStatus) classes inherit from [TimeStampedBuffer](../../../argaze/#argaze.DataStructures.TimeStampedBuffer) class. 

        Read [Timestamped data](../timestamped_data/introduction.md) section to understand all features it provides.

### Generator method

[GazeMovementIdentifier](../../../argaze/#argaze.GazeFeatures.GazeMovementIdentifier) can be called with a [TimeStampedGazePositions](../../../argaze/#argaze.GazeFeatures.TimeStampedGazePositions) buffer in argument to generate gaze movement each time one is identified.

``` python
# Assuming that timestamped gaze positions are provided through data reading

for ts, gaze_movement in gaze_movement_identifier(ts_gaze_positions):

        # Fixation identified
        if GazeFeatures.is_fixation(gaze_movement):

                # Do something with each fixation
                ...

        # Saccade identified
        elif GazeFeatures.is_saccade(gaze_movement):

                # Do something with each saccade
                ...
```