{"id":13676454,"url":"https://github.com/cpp-lln-lab/bidsMReye","last_synced_at":"2025-04-29T07:32:21.683Z","repository":{"id":37953735,"uuid":"450515570","full_name":"cpp-lln-lab/bidsMReye","owner":"cpp-lln-lab","description":"BIDS app using deepMReye to decode eye motion for fMRI time series data.","archived":false,"fork":false,"pushed_at":"2025-04-21T06:12:49.000Z","size":10371,"stargazers_count":7,"open_issues_count":12,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-21T07:33:57.719Z","etag":null,"topics":["bids","bidsapp","closember","eye-tracking"],"latest_commit_sha":null,"homepage":"https://bidsmreye.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cpp-lln-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-01-21T14:08:19.000Z","updated_at":"2025-04-21T06:12:52.000Z","dependencies_parsed_at":"2023-09-26T13:02:49.937Z","dependency_job_id":"b7997a87-ca7f-4e2f-b30e-a1e3406c1af6","html_url":"https://github.com/cpp-lln-lab/bidsMReye","commit_stats":{"total_commits":323,"total_committers":8,"mean_commits":40.375,"dds":0.2538699690402477,"last_synced_commit":"2128fd34fe1f9f705116a58a113d7ce909aaa954"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cpp-lln-lab%2FbidsMReye","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cpp-lln-lab%2FbidsMReye/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cpp-lln-lab%2FbidsMReye/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cpp-lln-lab%2FbidsMReye/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cpp-lln-lab","download_url":"https://codeload.github.com/cpp-lln-lab/bidsMReye/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251455956,"owners_count":21592265,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bids","bidsapp","closember","eye-tracking"],"created_at":"2024-08-02T13:00:27.424Z","updated_at":"2025-04-29T07:32:21.675Z","avatar_url":"https://github.com/cpp-lln-lab.png","language":"Python","funding_links":[],"categories":["BIDS Apps"],"sub_categories":["others"],"readme":"[![System tests](https://github.com/cpp-lln-lab/bidsMReye/actions/workflows/system_tests.yml/badge.svg?branch=main)](https://github.com/cpp-lln-lab/bidsMReye/actions/workflows/system_tests.yml)\n[![Test and coverage](https://github.com/cpp-lln-lab/bidsMReye/actions/workflows/test_and_coverage.yml/badge.svg)](https://github.com/cpp-lln-lab/bidsMReye/actions/workflows/test_and_coverage.yml)\n[![codecov](https://codecov.io/gh/cpp-lln-lab/bidsMReye/branch/main/graph/badge.svg?token=G5fm2kaloM)](https://codecov.io/gh/cpp-lln-lab/bidsMReye)\n[![Documentation Status](https://readthedocs.org/projects/bidsmreye/badge/?version=latest)](https://bidsmreye.readthedocs.io/en/latest/?badge=latest)\n[![License](https://img.shields.io/badge/license-GPL3-blue.svg)](./LICENSE)\n[![PyPI version](https://badge.fury.io/py/bidsmreye.svg)](https://badge.fury.io/py/bidsmreye)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bidsmreye)\n![https://github.com/psf/black](https://img.shields.io/badge/code%20style-black-000000.svg)\n[![Sourcery](https://img.shields.io/badge/Sourcery-enabled-brightgreen)](https://sourcery.ai)\n[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg)](#contributors)\n[![paper doi](https://img.shields.io/badge/paper-10.1038%2Fs41593--021--00947--w-blue)](https://doi.org/10.1038/s41593-021-00947-w)\n[![zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7493322.svg)](https://doi.org/10.5281/zenodo.7493322)\n\n\n\n# bidsMReye\n\nBIDS app for decoding gaze position from the eyeball MR-signal using\n[deepMReye](https://github.com/DeepMReye/DeepMReye)\n([1](https://doi.org/10.1038/s41593-021-00947-w)).\n\nTo be used on preprocessed BIDS derivatives (e.g.\n[fMRIprep](https://github.com/nipreps/fmriprep) outputs).\nNo eye-tracking data required.\n\nBy default, bidsMReye uses a [pre-trained version](https://osf.io/mrhk9/) of\n[deepMReye](https://github.com/DeepMReye/DeepMReye) trained on 5 datasets incl.\nguided fixations ([2](https://doi.org/10.1038/sdata.2017.181)), smooth pursuit\n([3](https://doi.org/10.1016/j.neuroimage.2018.04.012),[4](https://doi.org/10.1101/2021.08.03.454928),[5](https://doi.org/10.1038/s41593-017-0050-8))\nand free viewing ([6](https://doi.org/10.1038/s41593-017-0049-1)). Other\npretrained versions are optional. Dedicated model training is recommended.\n\nThe pipeline automatically extracts the eyeball voxels.\nThis can be used also for other multivariate pattern\nanalyses in the absence of eye-tracking data.\nDecoded gaze positions allow computing eye movements.\n\nSome basic quality control and outliers detection is also performed:\n\n- for each run\n\n![](https://github.com/cpp-lln-lab/bidsMReye/blob/main/docs/source/images/sub-01_task-auditory_space-MNI152NLin6Asym_desc-bidsmreye_eyetrack.png)\n\n\n- at the group level\n\n![](https://github.com/cpp-lln-lab/bidsMReye/blob/main/docs/source/images/group_eyetrack.png)\n\nFor more information, see the\n[User Recommendations](https://deepmreye.slite.com/p/channel/MUgmvViEbaATSrqt3susLZ/notes/kKdOXmLqe).\nIf you have other questions, please reach out to the developer team.\n\n## Install\n\nBetter to use the docker image as there are known install issues\nof deepmreye on Apple M1 for example.\n\n### Docker\n\n#### Build\n\n```bash\ndocker build --tag cpplab/bidsmreye:latest --file docker/Dockerfile .\n```\n\n#### Pull\n\nPull the latest docker image:\n\n```bash\ndocker pull cpplab/bidsmreye:latest\n```\n\n### Python package\n\nYou can also get the package from pypi if you want.\n\n```bash\npip install bidsmreye\n```\n\n#### Conda installation\n\n**NOT TESTED YET**\n\nTo encapsulate bidsMReye in a virtual environment install with the following commands:\n\n```bash\nconda create --name bidsmreye python=3.10\nconda activate bidsmreye\nconda install pip\npip install bidsmreye\n```\n\nThe tensorflow dependency supports both CPU and GPU instructions.\n\nNote that you might need to install cudnn first\n\n```bash\nconda install -c conda-forge cudnn\n```\n\n### Dev install\n\nClone this repository.\n\n```bash\ngit clone git://github.com/cpp-lln-lab/bidsmreye\n```\n\nThen install the package:\n\n```bash\ncd bidsMReye\nmake install_dev\n```\n\n## Usage\n\n## Requirements\n\nbidsmreye requires your input fmri data:\n\n - to be minimally preprocessed (at least realigned),\n - with filenames and structure that conforms to a BIDS derivative dataset.\n\nTwo bids apps are available to generate those types of preprocessed data:\n\n- [fmriprep](https://fmriprep.org/en/stable/)\n- [bidspm](https://bidspm.readthedocs.io/en/latest/general_information.html)\n\nObviousvly your fmri data must include the eyes of your participant for bidsmreye to work.\n\n\u003c!-- old fmriprep versions may not work --\u003e\n\n### CLI\n\nType the following for more information:\n\n```bash\nbidsmreye --help\n```\n\n## Preparing the data\n\n`prepapre` means that bidsmreye will extract the data coming from the\neyes from the fMRI images.\n\nIf your data is not in MNI space, bidsmreye will also register the data to MNI.\n\n```bash\nbidsmreye bids_dir output_dir participant prepare\n```\n\n## Computing the eye movements\n\n`generalize` use the extracted timeseries to predict the eye movements\nusing the default pre-trained model of deepmreye.\n\nThis will also generate a quality control report of the decoded eye movements.\n\n```bash\nbidsmreye bids_dir output_dir participant generalize\n```\n## Doing it all at once\n\n`all` does \"prepare\" then \"generalize\".\n\n```bash\nbidsmreye bids_dir output_dir participant all\n```\n\n## Group level summary\n\n```\nbidsmreye bids_dir output_dir group qc\n```\n\n## Demo\n\nPlease look up the [documentation](https://bidsmreye.readthedocs.io/en/latest/demo.html)\n\n## Contributors ✨\n\nThanks goes to these wonderful people\n([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://weexee.github.io/Portfolio/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/91776803?v=4?s=100\" width=\"100px;\" alt=\"Pauline Cabee\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ePauline Cabee\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cpp-lln-lab/bidsMReye/commits?author=WeeXee\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#ideas-WeeXee\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#infra-WeeXee\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://remi-gau.github.io/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/6961185?v=4?s=100\" width=\"100px;\" alt=\"Remi Gau\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRemi Gau\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cpp-lln-lab/bidsMReye/commits?author=Remi-Gau\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#ideas-Remi-Gau\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/cpp-lln-lab/bidsMReye/commits?author=Remi-Gau\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"#maintenance-Remi-Gau\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/yyang1234\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/59220868?v=4?s=100\" width=\"100px;\" alt=\"Ying Yang\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eYing Yang\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cpp-lln-lab/bidsMReye/issues?q=author%3Ayyang1234\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"#userTesting-yyang1234\" title=\"User Testing\"\u003e📓\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the\n[all-contributors](https://github.com/all-contributors/all-contributors)\nspecification. Contributions of any kind welcome!\n\nIf you train [deepMReye](https://github.com/DeepMReye/DeepMReye), or if you have\neye-tracking training labels and the extracted eyeball voxels, consider sharing\nit to contribute to the [pretrained model pool](https://osf.io/mrhk9/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpp-lln-lab%2FbidsMReye","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcpp-lln-lab%2FbidsMReye","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpp-lln-lab%2FbidsMReye/lists"}