User Guide#

Installation#

Note

This package is not yet available on conda-forge.

1. Stable Installation#

You can install the latest stable version of the package from PyPI using pip:

pip install eyelinkio

2. Development Installation (Static)#

For those who need features or bugfixes that aren’t released yet:

pip install git+https://github.com/scott-huberty/eyelinkio

3. Development Installation (Dynamic)#

For contributors to EyeLinkIO:

pip install --editable ./eyelinkio

Important

To install the package in editable mode, you must:

  • Fork the repository on GitHub first.

  • Clone your forked repository to your computer.

  • Make sure you’re in the directory containing the cloned eyelinkio folder when you run the command provided above.

Example Usage#

Reading an EDF file#

You can read EyeLink EDF files using the read_edf() function, which returns an EDF instance.

from eyelinkio.io import read_edf
eyelinkio.utils import _get_test_fnames  # for demonstration purposes only

fname = _get_test_fnames()[0]  # Replace this function with the path to your EDF file
edf_file = read_edf(fname)
print(edf_file)

<EDF | test_raw.edf>
Version: EYELINK II 1
Eye: LEFT_EYE
Pupil unit: PUPIL_AREA
Sampling frequency: 1000.0 Hz
Calibrations: 1
Length: 66.827 seconds

Inspecting an EDF object#

An EDF object inherits from a dictionary, so you can index it like a dictionary, and inspect its keys.

# Inspect the EDF object
edf_file.keys()

dict_keys(['info', 'discrete', 'times', 'samples'])

# Inspect the info
edf_file['info'].keys()

dict_keys(['meas_date', 'version', 'camera', 'serial', 'camera_config', 'sfreq', 'ps_units', 'eye', 'sample_fields', 'edfapi_version', 'screen_coords', 'calibrations', 'filename'])

# Inspect the events
edf_file["discrete"].keys()

dict_keys(['messages', 'buttons', 'inputs', 'blinks', 'saccades', 'fixations'])

# Inspect the calibrations
edf_file['info']['calibrations']

Converting to a DataFrame or MNE Raw instance#

You can convert an instance of EDF to a pandas DataFrame or an MNE Raw instance using the to_pandas() and to_mne() methods, respectively.

# Convert to a pandas DataFrame or an MNE Raw instance
dfs = edf_file.to_pandas()
raw, calibrations = edf_file.to_mne()

See also

Working with eyetracking data in MNE

Using the EDF API Library installed on your system#

If you have the EDF API Library installed on your system, you can explicitly direct EyeLinkIO to rely on it when reading your EDF files. This can be done by setting the EYELINKIO_USE_INSTALLED_EDFAPI parameter to true before importing EyeLinkIO.

import os
os.environ["EYELINKIO_USE_INSTALLED_EDFAPI"] = "true"

from eyelinkio.io import read_edf

fname = _get_test_fnames()[0]  # Replace this function with the path to your EDF file
edf_file = read_edf(fname)
print(edf_file)

Otherwise, EyeLinkIO will rely on the EDF API Library that comes with the package.

Note

If you want to install the EyeLink Developers Kit, you can download it from the SR Research website. You will need to register an account to access the download page (registration is free).