Skip to main content

System tests Test and coverage codecov Documentation Status License PyPI version PyPI - Python Version https://github.com/psf/black Sourcery All Contributors paper doi zenodo DOI

bidsMReye

BIDS app for decoding gaze position from the eyeball MR-signal using deepMReye (1).

To be used on preprocessed BIDS derivatives (e.g. fMRIprep outputs). No eye-tracking data required.

By default, bidsMReye uses a pre-trained version of deepMReye trained on 5 datasets incl. guided fixations (2), smooth pursuit (3,4,5) and free viewing (6). Other pretrained versions are optional. Dedicated model training is recommended.

The pipeline automatically extracts the eyeball voxels. This can be used also for other multivariate pattern analyses in the absence of eye-tracking data. Decoded gaze positions allow computing eye movements.

Some basic quality control and outliers detection is also performed:

  • for each run

  • at the group level

For more information, see the User Recommendations. If you have other questions, please reach out to the developer team.

Install

Better to use the docker image as there are known install issues of deepmreye on Apple M1 for example.

Docker

Build

docker build --tag cpplab/bidsmreye:latest --file docker/Dockerfile .

Pull

Pull the latest docker image:

docker pull cpplab/bidsmreye:latest

Python package

You can also get the package from pypi if you want.

pip install bidsmreye

Conda installation

NOT TESTED YET

To encapsulate bidsMReye in a virtual environment install with the following commands:

conda create --name bidsmreye python=3.11
conda activate bidsmreye
conda install pip
pip install bidsmreye

The tensorflow dependency supports both CPU and GPU instructions.

Note that you might need to install cudnn first

conda install -c conda-forge cudnn

Dev install

Clone this repository.

git clone git://github.com/cpp-lln-lab/bidsmreye

Then install the package:

cd bidsMReye
make install_dev

Usage

Requirements

bidsmreye requires your input fmri data:

  • to be minimally preprocessed (at least realigned),
  • with filenames and structure that conforms to a BIDS derivative dataset.

Two bids apps are available to generate those types of preprocessed data:

Obviousvly your fmri data must include the eyes of your participant for bidsmreye to work.

CLI

Type the following for more information:

bidsmreye --help

Preparing the data

prepapre means that bidsmreye will extract the data coming from the eyes from the fMRI images.

If your data is not in MNI space, bidsmreye will also register the data to MNI.

bidsmreye bids_dir output_dir participant prepare

Computing the eye movements

generalize use the extracted timeseries to predict the eye movements using the default pre-trained model of deepmreye.

This will also generate a quality control report of the decoded eye movements.

bidsmreye bids_dir output_dir participant generalize

Doing it all at once

all does "prepare" then "generalize".

bidsmreye bids_dir output_dir participant all

Group level summary

bidsmreye bids_dir output_dir group qc

Demo

Please look up the documentation

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Pauline Cabee
Pauline Cabee

💻 🤔 🚇
Remi Gau
Remi Gau

💻 🤔 ⚠️ 🚧
Ying Yang
Ying Yang

🐛 📓

This project follows the all-contributors specification. Contributions of any kind welcome!

If you train deepMReye, or if you have eye-tracking training labels and the extracted eyeball voxels, consider sharing it to contribute to the pretrained model pool.

Metadata

Release files for bidsmreye 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bidsmreye 0.6.0
File Size Uploaded Provenance Actions
bidsmreye-0.6.0.tar.gz 9.9 MB Without provenance Details for bidsmreye-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bidsmreye 0.6.0
File Interpreter ABI Platform Actions
bidsmreye-0.6.0-py3-none-any.whl Python 3 none any Details for bidsmreye-0.6.0-py3-none-any.whl

Total release size: 10.0 MB

Release files / bidsmreye-0.6.0.tar.gz

Download URL bidsmreye-0.6.0.tar.gz
Size 9.9 MB
Tags Source
SHA-256 checksum
How to use checksums
5d50aa28354c78790c043e4626e0d82f720a7a5f28b2f23097d3f9a3d12c3ae3
BLAKE2b-256 checksum
How to use checksums
8f77913f4edb5615c334dc3d0b1c912f9391f7d0a58a61419f96e41122a4738e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / bidsmreye-0.6.0-py3-none-any.whl

Download URL bidsmreye-0.6.0-py3-none-any.whl
Size 47.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
934367d5af9cd749bb685ef153e9437873bd7ffdc3b9400b33ab0c495f3a0c46
BLAKE2b-256 checksum
How to use checksums
210c45c2860fefb0a0058a350cd6821b708a55154ffbb373ea27ae41ea7d2b36
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for bidsmreye 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page