Data ¶

Contents

Data
- Experiment
- Trial
- Item
- Region
- Saccade
- Fixation
- Point

The data module contains SideEye’s core data structures - Experiments, Trials, Items, Regions, Saccades, Fixations, and Points. Raw data can be parsed into these objects, and measures can be calculated from them.

Experiment ¶

An Experiment is the highest-level data object in the SideEye module, representing a single participant’s data.

class sideeye.data.Experiment(name: str, trials: List[sideeye.data.trial.Trial], filename: str = '', date: datetime.datetime = None)¶

Represents the data of one participant in an experiment.

name¶

Name of experiment.

Type:	str

trials¶

Dictionary mapping (number, condition) tuples to trials.

Type:	dict

filename¶

Name of file.

Type:	str

date¶

Date of experiment.

Type:	Date

trial_indices¶

A dictionary mapping trial indices to (number, condition) tuples. Used to locate trials.

Type:	dict

Parameters:	name (str) – A string name/identifier for the participant. trials (List[Trial]) – Trials in the experiment. filename (Optional[str]) – Optional name of source file. date (Optional[datetime]) – Optional date.

get_trial(number: str = None, condition: str = None, index: int = None) → sideeye.data.trial.Trial¶

Get a trial by item number and condition, or by index if specified.

Parameters:	number (ItemNum) – Trial number. condition (Condition) – Trial condition. index (int) – Trial index.

Trial ¶

A Trial represents the data from a participant reading one item. An individual Trial is identified by an index, and contains the total time spent reading the Item, lists of Fixations and Saccades associated with the Trial, and a dictionary of trial and region measures calculated for the Trial.

The list of saccades for a Trial is generated using the list of fixations. There are two parameters that affect how saccades are defined: include_fixation and include_saccades. If a Fixation is excluded from calculations, there are several ways to define a saccade. If include_fixation is true, the excluded fixation will be included in the duration of the Saccade. If include_saccades is true, the saccades surrounding an excluded fixation are included in the duration of the Saccade.

In the following example, the excluded fixation and surrounding saccades are included in the Saccade, which has a total duration of 30ms.

include_saccades: True
include_fixations: True

Time:      0        10      20           30      40       50
Fixations: |  fix1  |       | excl. fix. |       |  fix3  |
           ------------------------------------------------
Saccades:  |        |          saccade1          |        |

Trial.fixations = [fix1, fix2]
Trial.saccades = [saccade1]

If the excluded fixation is included in the saccade, but the surrounding saccades are not, the Saccade has a total duration of 10ms.

include_saccades: False
include_fixations: True

Time:      0        10      20           30      40       50
Fixations: |  fix1  |       | excl. fix. |       |  fix3  |
           ------------------------------------------------
Saccades:  |                |  saccade1  |                |

Trial.fixations = [fix1, fix3]
Trial.saccades = [saccade1]

If the surrounding saccades are included, but the excluded fixation is not, the total duration of the Saccade is 20ms - the sum of the durations of the two surrounding saccades.

include_saccades: True
include_fixations: False

Time:      0        10      20           30      40       50
Fixations: |  fix1  |       | excl. fix. |       |  fix3  |
           ------------------------------------------------
Saccades:  |        | sacc1 |  EXCLUDED  | sacc1 |        |

Trial.fixations = [fix1, fix3]
Trial.saccades = [sacc1(both parts combined)]

If the excluded fixation and surrounding saccades are both not included, no Saccade is added to the Trial. This is the default.

include_saccades: False
include_fixations: False

Time:      0        10      20           30      40       50
Fixations: |  fix1  |       | excl. fix. |       |  fix3  |
           ------------------------------------------------
Saccades:  |        |          EXCLUDED          |        |

Trial.fixations = [fix1, fix3]
Trial.saccades = []

The Trial object also contains all measures that have been calculated so far. trial_measures is a dictionary mapping measure names to calculation outputs. region_measures is a dictionary mapping region numbers to dictionaries mapping measure names to calculation outputs. Region measure outputs are in the format {‘value’: output_value, ‘fixations’: fixation_in_calculation}:

trial_measures = {
  'measure_1': False,
  'measure_2': 5000,
  ...
}

region_measures = {
  0: {
    'region_measure_1': {'value': 50, 'fixations': [fix1, fix3]},
    'region_measure_2': {'value': True, 'fixations': [fix4]},
    ...
  },
  1: {
  'region_measure_1': {'value': 148, 'fixations': [fix2, fix5, fix6]},
  'region_measure_2': {'value': False, 'fixations': None},
    ...
  },
  ...
}

class sideeye.data.Trial(index: int, time: int, item: sideeye.data.item.Item, fixations: List[sideeye.data.fixation.Fixation], include_fixation: bool = False, include_saccades: bool = False)¶

Represents an individual Trial in an experiment.

index¶

Trial index.

Type:	int

time¶

Total time of trial in milliseconds.

Type:	int

item¶

Item corresponding to trial data.

Type:	Item

fixations¶

List of fixations in trial.

Type:	List[Fixation]

saccades¶

A list of saccades in the trial.

Type:	List[Saccade]

trial_measures¶

Trial measures that have been calculated for the trial.

Type:	dict

region_measures¶

Region measures that have been calculated for the trial.

Type:	dict

Parameters:

index (int) – An identifier for the Trial. Must be greater than or equal to 0.
time (int) – Total time of the Trial in milliseconds.
item (Item) – An Item corresponding to the Trial.
fixations (List[Fixation]) – A list of Fixations in the Trial.
include_fixation (bool) – Boolean indicating whether an excluded fixation should be included in a saccade.
include_saccades (bool) – Boolean indicating whether saccades surrounding an excluded fixation should be included in a saccade.

fixation_count() → int¶: Return the number of fixations in the item.

Item ¶

An Item represents the text that is displayed to a participant during a trial. A number and condition identify the item, which consists of a list of regions, and optionally a list of labels for the regions.

class sideeye.data.Item(number: str, condition: str, regions: List[sideeye.data.region.Region], labels: Sequence[Union[int, str]] = None)¶

Represents an Item in an experiment.

number¶

An identifier for the Item.

Type:	int

condition¶

An identifier for the condition of the Item.

Type:	int

regions¶

A list of Regions in the Item.

Type:	List[Region]

labels¶

A list of labels for the regions. If labels are not provided, integer indices are used. All labels are unique.

Type:	List[Union[int, str]]

Parameters:	number (ItemNum) – An identifier for the Item. condition (Condition) – An identifier for the condition of the Item. regions (List[Region]) – A list of Region objects in the Item. All regions must be unique. labels (List[Union[int, str]]) – A list of labels for regions. If not provided, integer indices will be used. All labels must be unique.

find_region(x_pos: int, y_pos: int) → sideeye.data.region.Region¶

Get the region containing position (x_pos, y_pos).

Parameters:	x_pos (int) – X (character) position of a location. y_pos (int) – Y (line) position of a location.

get_region(label: Union[str, int]) → sideeye.data.region.Region¶

Get Region with matching label.

Parameters:	label (Union[str, int]) – A region label.

region_count() → int¶: Get the number of Regions in the Item.

Region ¶

A Region represents the boundaries of a region in an Item as (character, line) points in the text of the Item. A region also has a label, number, and optionally the text contained in the region.

class sideeye.data.Region(start: sideeye.data.point.Point, end: sideeye.data.point.Point, length: int = None, text: str = '', label: Union[str, int] = 'undefined', number: int = None)¶

Represents a Region as x and y coordinates for character positions of the beginning and end of the Region.

start¶

The character and line position of the beginning of the Region.

Type:	Point

end¶

The character and line position of the end of the Region.

Type:	Point

length¶

Length of region in characters.

Type:	Optional[int]

text¶

Text contained in the region.

Type:	Optional[str]

label¶

A label for the region.

Type:	Optional[Union[str, int]]

number¶

A number identifier for the region.

Type:	Optional[int]

Parameters:

start (Point) – The character and line position of the beginning of the Region.
end (Point) – The character and line position of the end of the Region.
length (Optional[int]) – Length of region in characters.
text (Optional[str]) – Text contained in the region.
label (Optional[Union[str, int]]) – A label for the region.
number (Optional[int]) – A number identifier for the region.

Saccade ¶

A Saccade is the period of time between two fixations. The start of the Saccade is the Fixation before the Saccade, and the end is the Fixation after the Saccade. If the location of the end Fixation is earlier in the Item the location of the start Fixation, the Saccade is a regression.

class sideeye.data.Saccade(duration: int, regression: bool, start: sideeye.data.fixation.Fixation, end: sideeye.data.fixation.Fixation)¶

Represents a saccade as the time in milliseconds between two fixations.

Parameters:	duration (int) – Duration in milliseconds of the saccade. regression (bool) – True if the saccade is a regression, false otherwise. start (Fixation) – The fixation before the saccade. end (Fixation) – The fixation after the saccade.

Fixation ¶

A Fixation represents a period of time where a participant fixated on an item in a trial. Fixation position is represented by character and line position in the item. A Fixation can also hold information about the region of the item it occurred in, and whether or not it has been excluded by fixation cutoff parameters.

class sideeye.data.Fixation(position: sideeye.data.point.Point, start: int, end: int, index: int, region: sideeye.data.region.Region, excluded: bool = False)¶

Represents a single Fixation by location, start time, and end time.

char¶

Character position of the fixation. None of position is negative.

Type:	Optional[int]

line¶

Line position of the fixation. None if position is negative.

Type:	Optional[int]

start¶

Start time of Fixation in milliseconds since trial start.

Type:	int

end¶

End time of Fixation in milliseconds since trial start.

Type:	int

index¶

Index of where the Fixation occurred in a trial.

Type:	int

region¶

Region the Fixation occurred in.

Type:	Region

excluded¶

Whether or not the fixation will be excluded from calculations.

Type:	bool

Parameters:

position (Point) – The character and line position of the Fixation, zero-indexed.
start (int) – Start time for the Fixation, in milliseconds.
end (int) – End time for the Fixation, in milliseconds.
index (int) – An index of where the fixation occurred in a trial.
region (Region) – Region the Fixation occurs in.
excluded (Optional[boolean]) – Whether the fixation should be excluded from calculations.

assign_region(region: sideeye.data.region.Region)¶

Assign a Region object to the Fixation.

Parameters:	region (Region) – Region to assign to the fixation.

duration() → int¶: Fixation duration in ms.

Point ¶

A Point represents an (x, y) location. It is used to represent fixation positions and region boundaries.

class sideeye.data.Point(x: int, y: int)¶

An (x, y) location.

x¶

x location.

Type:	int

y¶

y location.

Type:	int