eyekit.fixation API documentation
Description: Defines the `Fixation` and `FixationSequence` objects, which are used to represent fixation data.

# Module `eyekit.fixation`

Defines the `Fixation` and `FixationSequence` objects, which are used to represent fixation data.

View code on GitHub

## Classes

`class Fixation (x: int, y: int, start: int, end: int, discarded: bool = False)`

  Representation of a single fixation event. It is not usually necessary to create `Fixation` objects manually; they are created automatically during the instantiation of a `FixationSequence`.

  View code on GitHub

  ### Instance variables

  `var x : int`

    X-coordinate of the fixation.

    View code on GitHub
  `var y : int`

    Y-coordinate of the fixation.

    View code on GitHub
  `var xy : tuple`

    XY-coordinates of the fixation.

    View code on GitHub
  `var start : int`

    Start time of the fixation in milliseconds.

    View code on GitHub
  `var end : int`

    End time of the fixation in milliseconds.

    View code on GitHub
  `var duration : int`

    Duration of the fixation in milliseconds.

    View code on GitHub
  `var discarded : bool`

    `True` if the fixation has been discarded, `False` otherwise.

    View code on GitHub
  `var tuple : tuple`

    Tuple representation of the fixation: (X, Y, START, END).

    View code on GitHub
`class FixationSequence (sequence: list = [])`

  Representation of a sequence of consecutive fixations, typically from a single trial.

  Initialized with:

  - `sequence` List of tuples of ints, or something similar, that conforms to the following structure: `[(106, 540, 100, 200), (190, 536, 200, 300), ..., (763, 529, 1000, 1100)]`, where each tuple contains the X-coordinate, Y-coordinate, start time, and end time of a fixation.
  View code on GitHub

  ### Instance variables

  `var start`

    Start time of the fixation sequence (in milliseconds).

    View code on GitHub
  `var end`

    End time of the fixation sequence (in milliseconds).

    View code on GitHub
  `var duration`

    Duration of the fixation sequence, incuding any gaps between fixations (in milliseconds).

    View code on GitHub

  ### Methods

  `def append(self, fixation)`

    Append a fixation to the end of the sequence.

    View code on GitHub
  `def copy(self, include_discards=True)`

    Returns a copy of the fixation sequence.

    View code on GitHub
  `def purge(self)`

    Permanently removes all discarded fixations from the fixation sequence.

    View code on GitHub
  `def iter_with_discards(self)`

    Iterates over the fixation sequence including any discarded fixations. This is also the default behavior when iterating over a `FixationSequence` directly.

    View code on GitHub
  `def iter_without_discards(self)`

    Iterates over the fixation sequence without any discarded fixations.

    View code on GitHub
  `def iter_pairs(self)`

    Iterate over fixations in consecutive pairs. This is useful if you want to compare consecutive fixations in some way. For example, if you wanted to detect when a fixation leaves an interest area, you might do something like this:

        for curr_fxn, next_fxn in seq.iter_pairs():
            if curr_fxn in interest_area and next_fxn not in interest_area:
                print('A fixation has left the interest area')

    View code on GitHub