pyxations 0.2.10
Pyxations: a Python-based toolbox to organize, parse, and analyse eye-movement data
License: MIT
Requires Python: >=3.10

# Pyxations

<div>
  <table>
    <tr>
       <td>
          <img src="https://raw.githubusercontent.com/NeuroLIAA/pyxations/main/docs/images/pyxations_improved_logo.png" alt="pyxations logo" width="180">
       </td>
    </tr>
</table>
 
  <p>
    <strong>Pyxations</strong> 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.
  </p>
</div>

[📘 Documentation](https://neuroliaa.github.io/pyxations/)  
## 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):

```bash
uv pip install pyxations
```

Or directly with `pip`:

```bash
pip install pyxations
```

## Documentation

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

## Usage
### Minimal example
```python
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](https://github.com/NeuroLIAA/pyxations/issues) and submit a pull request if you'd like to help.

### To develop locally

```bash
# 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.