Pyxations

Pyxations is a Python library for analyzing eye-tracking data, from raw recordings to processed datasets. It standardizes data into BIDS layout, runs fixation/saccade detection with multiple algorithms, segments recordings into trials, and provides visualization utilities: so researchers can focus on analysis instead of file plumbing.

Who is it for

Cognitive scientists, vision researchers and developers working with eye-tracking recordings (EyeLink, Tobii, Gazepoint, WebGazer) who want a reproducible pipeline in Python.

Quick install

pip install pyxations

For EDF inputs you also need EyeLink's edf2asc tool on your PATH. See Requirements and Installation for details.

60-second example

import pyxations as pyx

# 1) Organize raw recordings into a BIDS-formatted dataset
pyx.dataset_to_bids(
    target_folder_path="path/to/output",
    files_folder_path="path/to/raw/edf/files",
    dataset_name="my_experiment",
)

# 2) Compute derivatives (parse, detect fixations/saccades, split into trials)
pyx.compute_derivatives_for_dataset(
    bids_path="path/to/output/my_experiment",
    dataset_format="eyelink",
    detection_algorithm="remodnav",
    msg_keywords=["begin", "end", "press"],
    start_msgs={"search": ["beginning_of_stimuli"]},
    end_msgs={"search": ["end_of_stimuli"]},
    overwrite=True,
)

See Usage for an end-to-end walkthrough.

Features

• BIDS conversion: organize recordings into a BIDS-compliant layout.
• EDF parsing: extract headers, messages, calibration, events and raw samples from EyeLink EDF files (via edf2asc).
• Multi-vendor support: input formats for EyeLink, Tobii, Gazepoint and WebGazer.
• Trial segmentation: split continuous recordings using start/end messages, fixed durations or explicit timestamps.
• Eye movement detection: fixations and saccades with REMoDNaV, Engbert–Kliegl and other algorithms.
• Saccade direction classification: right / left / up / down based on start–end coordinates.
• Derivatives pipeline: reproducible per-subject derivatives stored next to the BIDS dataset.
• Visualization: plots for samples, events and per-trial inspection.

Where to go next

• Requirements: Python version, edf2asc, dependencies.
• Installation: pip, uv, from source.
• Usage: end-to-end pipeline with output layout.
• API reference: public modules and functions.
• Contributing: dev setup, tests, building the docs.

Citation

If you use Pyxations in academic work, please cite the accompanying paper (see paper.md in the repository).