Skip to main content

bids app using deepMReye to decode eye motion for fMRI time series data

Project description

System tests Test and coverage codecov Documentation Status License PyPI version PyPI - Python Version Sourcery All Contributors paper doi zenodo DOI


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.


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



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


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


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

conda create --name bidsmreye python=3.10
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

ANTsPy installation issues

If installation of ANTsPy fails try to manually install it via:

git clone
cd ANTsPy
pip install CMake
python3 install

Dev install

Clone this repository.

git clone git://

Then install the package:

cd bidsMReye
make install_dev



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.


Type the following for more information:

bidsmreye --help

Preparing the data

--action 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 --action prepare \
          bids_dir \
          output_dir \

Computing the eye movements

--action 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 --action generalize \
          bids_dir \
          output_dir \

Doing it all at once

--action all does "prepare" then "generalize".

bidsmreye --action all \
          bids_dir \
          output_dir \

Group level summary

bidsmreye --action qc


Please look up the documentation

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Pauline Cabee

💻 🤔 🚇

Remi Gau

💻 🤔 ⚠️ 🚧

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bidsmreye-0.3.1.tar.gz (60.2 kB view hashes)

Uploaded Source

Built Distribution

bidsmreye-0.3.1-py3-none-any.whl (48.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page