pymovements.datasets.GazeBase#

class pymovements.datasets.GazeBase(root: str | Path, download: bool = False, extract: bool = False, remove_finished: bool = False, dataset_dirname: str = 'GazeBase', downloads_dirname: str = 'downloads', raw_dirname: str = 'raw', preprocessed_dirname: str = 'preprocessed', events_dirname: str = 'events')[source]#

GazeBase dataset [Griffith et al., 2021].

This dataset includes monocular (left eye) eye tracking data from 322 participants captured over a period of 37 months. Participants attended up to 9 rounds during this time frame, with each round consisting of two contiguous sessions.

Eye movements are recorded at a sampling frequency of 1000 Hz using an EyeLink 1000 video-based eye tracker and are provided as positional data in degrees of visual angle.

In each of the two sessions per round, participants are instructed to complete a series of tasks, including a fixation task (FIX), a horizontal saccade task (HSS), a random saccade task (RAN), a reading task (TEX), two free viewing video tasks (VD1 and VD2) and a gaze-driven gaming task (BLG).

Check the respective paper for details [Griffith et al., 2021].

Change to download=True and extract=True for downloading and extracting the dataset.

>>> dataset = GazeBase(
...     root='data/',
...     download=False,
...     extract=False,
...     remove_finished=False,
... )
>>> dataset.load()  

__init__(root: str | Path, download: bool = False, extract: bool = False, remove_finished: bool = False, dataset_dirname: str = 'GazeBase', downloads_dirname: str = 'downloads', raw_dirname: str = 'raw', preprocessed_dirname: str = 'preprocessed', events_dirname: str = 'events')[source]

Initialize the GazeBase dataset object.

If desired, dataset resources are downloaded with download=True and extracted with extract=True. To save space on your device you can remove the archive files after successful extraction with remove_finished=True.

Downloaded archives are automatically checked for integrity by comparing MD5 checksums.

You can set up a custom directory structure by populating the particular dirname attributes. See dataset_dirname, raw_dirname, preprocessed_dirname and events_dirname and downloads_dirname for details.

Parameters:

root (str, Path) – Path to the root directory of the dataset.
download (bool) – Download all dataset resources.
extract (bool) – Extract dataset archive files.
remove_finished (bool) – Remove archive files after extraction.
dataset_dirname (str, optional) – Dataset directory name under root path. Can be . if dataset is located in root path. Default: .
downloads_dirname (str, optional) – Name of directory to store downloaded data.Default: downloads
str (raw_dirname ;) – Name of directory under dataset path that contains raw data. Can be . if raw data is located in dataset path. We advise the user to keep the original raw data separate from the preprocessed / event data. Default: raw
optional – Name of directory under dataset path that contains raw data. Can be . if raw data is located in dataset path. We advise the user to keep the original raw data separate from the preprocessed / event data. Default: raw
preprocessed_dirname (str, optional) – Name of directory under dataset path that will be used to store preprocessed data. We advise the user to keep the preprocessed data separate from the original raw data. Default: preprocessed
events_dirname (str, optional) – Name of directory under dataset path that will be used to store event data. We advise the user to keep the event data separate from the original raw data. Default: events

Methods

`__init__`(root[, download, extract, ...])	Initialize the GazeBase dataset object.
`clear_events`()	Clear event DataFrame.
`compute_event_properties`(event_properties[, ...])	Calculate an event property for and add it as a column to the event dataframe.
`detect_events`(method[, eye, clear, verbose])	Detect events by applying a specific event detection method.
`download`()	Download dataset.
`extract`([remove_finished])	Extract dataset archives.
`infer_fileinfo`()	Infer information from filepaths and filenames.
`load`([events, preprocessed, subset, ...])	Parse file information and load all gaze files.
`load_event_files`([events_dirname, extension])	Load all available event files.
`load_gaze_files`([preprocessed, ...])	Load all available gaze data files.
`pix2deg`([verbose])	Compute gaze positions in degrees of visual angle from pixel coordinates.
`pos2vel`([method, verbose])	Compute gaze velocites in dva/s from dva coordinates.
`save`([events_dirname, preprocessed_dirname, ...])	Save preprocessed gaze and event files.
`save_events`([events_dirname, verbose, extension])	Save events to files.
`save_preprocessed`([preprocessed_dirname, ...])	Save preprocessed gaze files.
`take_subset`(fileinfo[, subset])	Take a subset of the dataset.

Attributes

`downloads_rootpath`	The path to the directory of the raw data.
`events_rootpath`	The path to the directory of the event data.
`path`	Get the path to the dataset directory.
`preprocessed_rootpath`	The path to the directory of the preprocessed gaze data.
`raw_rootpath`	The path to the directory of the raw data.
`root`	The root path to your dataset.