| Name | eyelinkio JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | A lightweight library for reading Eyelink Data Format files in Python. |
| upload_time | 2024-12-12 18:38:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
neuroscience
eyelink
eyetracking
sr research
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://dl.circleci.com/status-badge/redirect/gh/scott-huberty/eyelinkio/tree/main)
[](https://badge.fury.io/py/eyelinkio)
[](https://pepy.tech/project/eyelinkio)
# EyeLinkIO 👀
A lightweight library to import SR Research EDF files into Python.
**This Software is currenly pre-alpha, meaning it is currently being developed**: Changes to the API (function names, etc.) may occur without warning.
## About the Eyelink Data Format
The EyeLink Data Format (EDF; not to be confused with the
[European Data Format](<https://www.edfplus.info>)) is used for storing eyetracking data
from EyeLink eyetrackers. It was put forward by the company
[SR Research](<https://www.sr-research.com>). SR Research EDF files store data in a
binary format, and reading these files requires interfacing with ``eyelink-edfapi`` C
library that is typically included in the EyeLink Software Development Kit. EyeLinkIO
Includes the necessary binaries to read EDF files, but can also be configured to use the
EDF API library that is installed on your computer.
## Dependencies
Strictly speaking, EyeLinkIO only requires Numpy. For converting data to pandas ``DataFrames`` or MNE-Python ``Raw`` instances, you must have those respective packages installed.
> [!NOTE]
>
> - EyeLinkIO includes the Eyelink EDF API binary files that are needed to read EDF files.
> - [See](#using-the-eyelink-developers-kit-edf-api-to-read-edf-files) If you want to use the EyeLink Developers Kit's EDF API library that is installed on your computer.
## Installation
1. **Stable Installation**
```bash
pip install eyelinkio
```
2. **Development Installation** (For those who need features or bugfixes that aren't released yet):
```bash
pip install git+https://github.com/scott-huberty/eyelinkio.git
```
3. **Editable Installation** (For contributors to EyeLinkIO):
```bash
pip install -e ./eyelinkio
```
> [!IMPORTANT]
> To use the editable installation, you should:
>
>- Fork the repository on GitHub first.
>- Clone your forked repository to your local machine.
>- Make sure you're in the directory *containing* the cloned `eyelinkio` folder when you run the command provided above
This package is not currently available on Conda.
## Example Usage
#### Reading an EDF file
```python
from eyelinkio 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)
```
```console
<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
```python
edf_file.keys()
```
```console
Out: dict_keys(['info', 'discrete', 'times', 'samples'])
```
```python
edf_file["info"].keys()
```
```console
Out: dict_keys(['meas_date', 'version', 'camera', 'serial', 'camera_config', 'sfreq', 'ps_units', 'eye', 'sample_fields', 'edfapi_version', 'screen_coords', 'calibrations', 'filename'])
```
```python
edf_file["discrete"].keys()
```
```console
Out: dict_keys(['messages', 'buttons', 'inputs', 'blinks', 'saccades', 'fixations'])
```
### Exporting an EDF object to Pandas or MNE-Python
```python
# Convert to a pandas DataFrame or an MNE Raw instance
dfs = edf_file.to_pandas()
raw, calibration = edf_file.to_mne()
```
See the [documentation](https://scott-huberty.github.io/eyelinkio/) for more.
#### Using The EyeLink Developers Kit (EDF API) to read EDF files
EyeLinkIO includes the Eyelink EDF API binary files that are needed to read EDF files,
and by default it will rely on these files when reading reading your EDF files. However,
if you have the
[Eyelink Developers Kit](https://www.sr-research.com/support/forum-9.html)
installed on your computer, you can explicitly direct
EyeLinkIO to rely on the EDF API library that is included in the EyeLink Developers Kit,
by setting the environment variable `EYELINKIO_USE_INSTALLED_EDFAPI` to `true` *before*
importing the package:
```python
import os
os.environ["EYELINKIO_USE_INSTALLED_EDFAPI"] = "true"
import eyelinkio
edf = eyelinkio.read_edf("path/to/edf/file")
```
> [!NOTE]
>
> - First download the [EyeLink Software Development Kit](<https://www.sr-research.com/support/forum-3.html>)
> - You must register an account on the forum to access the download (registration is free)
## Acknowledgements
This package was originally adapted from the [pyeparse](<https://github.com/pyeparse/pyeparse>) package (created by several of the core developers of [MNE-Python](<https://mne.tools/dev/index.html>)). It copies much of the EDF (Eyelink Data Format) reading code.
## Limitations
- Reading extra sample fields (velocity, HREF, head position etc.) from the EDF file is not yet supported.
See the [Roadmap](https://scott-huberty.github.io/eyelinkio/roadmap.html) for more details.
Raw data
{
"_id": null,
"home_page": null,
"name": "eyelinkio",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Scott Huberty <seh33@uw.edu>",
"keywords": "neuroscience, eyelink, eyetracking, SR Research",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/50/0e/72e1e260fde7717198501f33ca563083d5a23bff6e7065945692c2af2ff2/eyelinkio-0.3.0.tar.gz",
"platform": null,
"description": "[](https://dl.circleci.com/status-badge/redirect/gh/scott-huberty/eyelinkio/tree/main)\n[](https://badge.fury.io/py/eyelinkio)\n[](https://pepy.tech/project/eyelinkio)\n\n# EyeLinkIO \ud83d\udc40\n\nA lightweight library to import SR Research EDF files into Python.\n\n**This Software is currenly pre-alpha, meaning it is currently being developed**: Changes to the API (function names, etc.) may occur without warning.\n\n## About the Eyelink Data Format\n\nThe EyeLink Data Format (EDF; not to be confused with the\n[European Data Format](<https://www.edfplus.info>)) is used for storing eyetracking data\nfrom EyeLink eyetrackers. It was put forward by the company\n[SR Research](<https://www.sr-research.com>). SR Research EDF files store data in a\nbinary format, and reading these files requires interfacing with ``eyelink-edfapi`` C\nlibrary that is typically included in the EyeLink Software Development Kit. EyeLinkIO\nIncludes the necessary binaries to read EDF files, but can also be configured to use the\nEDF API library that is installed on your computer.\n\n## Dependencies\n\nStrictly speaking, EyeLinkIO only requires Numpy. For converting data to pandas ``DataFrames`` or MNE-Python ``Raw`` instances, you must have those respective packages installed.\n\n> [!NOTE]\n>\n> - EyeLinkIO includes the Eyelink EDF API binary files that are needed to read EDF files.\n> - [See](#using-the-eyelink-developers-kit-edf-api-to-read-edf-files) If you want to use the EyeLink Developers Kit's EDF API library that is installed on your computer.\n\n## Installation\n\n1. **Stable Installation**\n\n```bash\n\npip install eyelinkio\n```\n\n2. **Development Installation** (For those who need features or bugfixes that aren't released yet):\n\n```bash\n\npip install git+https://github.com/scott-huberty/eyelinkio.git\n```\n3. **Editable Installation** (For contributors to EyeLinkIO):\n\n```bash\n\npip install -e ./eyelinkio\n```\n\n> [!IMPORTANT] \n> To use the editable installation, you should:\n>\n>- Fork the repository on GitHub first.\n>- Clone your forked repository to your local machine.\n>- Make sure you're in the directory *containing* the cloned `eyelinkio` folder when you run the command provided above\n\nThis package is not currently available on Conda.\n\n## Example Usage\n\n#### Reading an EDF file\n\n```python\n\nfrom eyelinkio import read_edf\neyelinkio.utils import _get_test_fnames # for demonstration purposes only\n\nfname = _get_test_fnames()[0] # Replace this function with the path to your EDF file\nedf_file = read_edf(fname)\nprint(edf_file)\n```\n\n```console\n<EDF | test_raw.edf> \n Version: EYELINK II 1 \n Eye: LEFT_EYE \n Pupil unit: PUPIL_AREA \n Sampling frequency: 1000.0 Hz \n Calibrations: 1 \n Length: 66.827 seconds \n```\n\n#### Inspecting an EDF object\n\n```python\n\nedf_file.keys()\n```\n\n```console\nOut: dict_keys(['info', 'discrete', 'times', 'samples'])\n```\n\n```python\n\nedf_file[\"info\"].keys()\n```\n\n```console\nOut: dict_keys(['meas_date', 'version', 'camera', 'serial', 'camera_config', 'sfreq', 'ps_units', 'eye', 'sample_fields', 'edfapi_version', 'screen_coords', 'calibrations', 'filename'])\n```\n\n```python\n\nedf_file[\"discrete\"].keys()\n```\n\n```console\nOut: dict_keys(['messages', 'buttons', 'inputs', 'blinks', 'saccades', 'fixations'])\n```\n\n### Exporting an EDF object to Pandas or MNE-Python\n\n```python\n# Convert to a pandas DataFrame or an MNE Raw instance\ndfs = edf_file.to_pandas()\nraw, calibration = edf_file.to_mne()\n```\n\nSee the [documentation](https://scott-huberty.github.io/eyelinkio/) for more.\n\n#### Using The EyeLink Developers Kit (EDF API) to read EDF files\n\nEyeLinkIO includes the Eyelink EDF API binary files that are needed to read EDF files,\nand by default it will rely on these files when reading reading your EDF files. However,\nif you have the\n[Eyelink Developers Kit](https://www.sr-research.com/support/forum-9.html)\ninstalled on your computer, you can explicitly direct\nEyeLinkIO to rely on the EDF API library that is included in the EyeLink Developers Kit,\nby setting the environment variable `EYELINKIO_USE_INSTALLED_EDFAPI` to `true` *before*\nimporting the package:\n\n```python\nimport os\nos.environ[\"EYELINKIO_USE_INSTALLED_EDFAPI\"] = \"true\"\n\nimport eyelinkio\nedf = eyelinkio.read_edf(\"path/to/edf/file\")\n```\n\n> [!NOTE]\n>\n> - First download the [EyeLink Software Development Kit](<https://www.sr-research.com/support/forum-3.html>)\n> - You must register an account on the forum to access the download (registration is free)\n\n## Acknowledgements\n\nThis package was originally adapted from the [pyeparse](<https://github.com/pyeparse/pyeparse>) package (created by several of the core developers of [MNE-Python](<https://mne.tools/dev/index.html>)). It copies much of the EDF (Eyelink Data Format) reading code.\n\n## Limitations\n\n- Reading extra sample fields (velocity, HREF, head position etc.) from the EDF file is not yet supported.\n\nSee the [Roadmap](https://scott-huberty.github.io/eyelinkio/roadmap.html) for more details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight library for reading Eyelink Data Format files in Python.",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/scott-huberty/eyelinkio/issues",
"Documentation": "https://scott-huberty.github.io/eyelinkio/",
"Download": "https://pypi.org/project/eyelinkio/#files",
"Homepage": "https://scott-huberty.github.io/eyelinkio/",
"Source Code": "https://github.com/scott-huberty/eyelinkio"
},
"split_keywords": [
"neuroscience",
" eyelink",
" eyetracking",
" sr research"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6d758883aa125f42c2cf1ac3905627de0ecef1f11b6a391efae0800be68e362",
"md5": "4bed73215eabe19d69e160fbc1c12fd6",
"sha256": "cabc6059c99746dea2184d85844f7ea78ed3070d8cde4a12e4bde9fbfd795e33"
},
"downloads": -1,
"filename": "eyelinkio-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bed73215eabe19d69e160fbc1c12fd6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4243640,
"upload_time": "2024-12-12T18:38:05",
"upload_time_iso_8601": "2024-12-12T18:38:05.173007Z",
"url": "https://files.pythonhosted.org/packages/a6/d7/58883aa125f42c2cf1ac3905627de0ecef1f11b6a391efae0800be68e362/eyelinkio-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "500e72e1e260fde7717198501f33ca563083d5a23bff6e7065945692c2af2ff2",
"md5": "3a5d9d4f6eec54e60200347cef678360",
"sha256": "54f420a243953c84f13f63d29b867e4e2ca8539e827c5f7c383d4dface572503"
},
"downloads": -1,
"filename": "eyelinkio-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "3a5d9d4f6eec54e60200347cef678360",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 4246998,
"upload_time": "2024-12-12T18:38:11",
"upload_time_iso_8601": "2024-12-12T18:38:11.340247Z",
"url": "https://files.pythonhosted.org/packages/50/0e/72e1e260fde7717198501f33ca563083d5a23bff6e7065945692c2af2ff2/eyelinkio-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-12 18:38:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scott-huberty",
"github_project": "eyelinkio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"lcname": "eyelinkio"
}
