pyxations 0.3.0

Pyxations: a Python-based toolbox to organize, parse, and analyse eye-movement data

Pyxations

Pyxations is a Python library designed to analyze eye-tracking data, whether you are working with raw eye-tracking data or processed datasets. It helps researchers and developers extract useful insights from complex eye movements using Python's robust ecosystem.

📘 Documentation

Features

• BIDS Conversion: Convert your dataset to BIDS format, automatically organizing files according to BIDS standards.
• EDF to ASCII Conversion: Convert EDF files to ASCII format using edf2asc, a tool provided by EyeLink.
• EDF Parsing: Parse EDF files generated by the EyeLink system to extract various data structures, including header information, messages, calibration data, events, and raw samples.
• Trial Segmentation: Segment continuous eye-tracking data into trials using flexible methods, including start/end messages, fixed durations, or explicit start/end times.
• Derivative Computation: Compute derivatives for a dataset by parsing EDF files and storing the results in an organized manner.
• Processing Derivatives: Process the derivatives by performing eye movement detection, classifying saccades, splitting them into trials, and visualizing the results.
• Eye Movement Detection: Detect fixations and saccades using multiple algorithms like REMoDNaV, Engbert–Kliegl, among others.
• Saccades Direction Classification: Classify saccades based on their start and end coordinates into four primary directions: right, left, up, and down.

Requirements

• Python 3.10 or newer is required.
• The edf2asc software from EyeLink is required for converting EDF files to ASCII format. Please ensure that the EyeLink software is installed and accessible in your system's PATH. The program is provided with the lastest version of the EyeLink Developers Kit

Dependencies

Pyxations relies on several scientific computing and visualization libraries, including:

• numpy
• pandas
• matplotlib
• seaborn
• scipy
• statsmodels
• pyarrow
• remodnav
• multimatch-gaze

The full list of dependencies is specified in pyproject.toml.

Installation

You can install Pyxations using uv (recommended for modern workflows):

uv pip install pyxations

Or directly with pip:

pip install pyxations

Documentation

Full documentation and API reference are available at https://neuroliaa.github.io/pyxations

Usage

Minimal example

import pyxations as pyx

# 1) Convert raw files to BIDS
pyx.dataset_to_bids(
    target_folder_path=" Path/to/the/folder/where/the/BIDS/dataset/will/be/created", 
    files_folder_path="Path/to/the/folder/containing/the/EDF/files",  
    dataset_name="dataset_name",
)

# 2) Compute derivatives using REMoDNaV
msg_keywords = ["begin", "end", "press"]
start_msgs   = {"search": ["beginning_of_stimuli"]}
end_msgs     = {"search": ["end_of_stimuli"]}

pyx.compute_derivatives_for_dataset(
    bids_path,
    dataset_format="eyelink",
    detection_algorithm="remodnav",
    msg_keywords=msg_keywords,
    start_msgs=start_msgs,
    end_msgs=end_msgs,
    overwrite=True,
)

Contributing

Contributions are welcome! Please check out the issues and submit a pull request if you'd like to help.

To develop locally

# Clone repository
git clone https://github.com/NeuroLIAA/pyxations.git
cd pyxations

# Create virtual environment and install
uv venv
uv pip install -e '.[dev]'

# To work on documentation
uv pip install -e '.[docs]'

License

This project is licensed under the MIT License.