diff --git a/Makefile b/Makefile index f1d0759..a019fcc 100644 --- a/Makefile +++ b/Makefile @@ -97,12 +97,14 @@ lint/mypy: ## check style with mypy lint: lint/black lint/mypy lint/flake8 ## check style ## DOC -.PHONY: docs +.PHONY: docs docs/source/FAQ.md -docs: ## generate Sphinx HTML documentation, including API docs +docs/source/FAQ.md: + faqtory build + +docs: docs/source/FAQ.md ## generate Sphinx HTML documentation, including API docs rm -f docs/source/bidsmreye.rst rm -f docs/source/modules.rst - faqtory build sphinx-apidoc -o docs/source bidsmreye $(MAKE) -C docs clean $(MAKE) -C docs html diff --git a/README.md b/README.md index 48d9d17..32d1d68 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,6 @@ For more information, see the [User Recommendations](https://deepmreye.slite.com/p/channel/MUgmvViEbaATSrqt3susLZ/notes/kKdOXmLqe). If you have other questions, please reach out to the developer team. -## Requirements - -At the moment bidsmreye only supports python 3.8 and 3.9. - ## Install Better to use the docker image as there are known install issues @@ -83,7 +79,7 @@ pip install bidsmreye To encapsulate bidsMReye in a virtual environment install with the following commands: ```bash -conda create --name bidsmreye python=3.9 +conda create --name bidsmreye python=3.10 conda activate bidsmreye conda install pip pip install bidsmreye @@ -97,6 +93,8 @@ Note that you might need to install cudnn first conda install -c conda-forge cudnn ``` +#### ANTsPy installation issues + If installation of [ANTsPy](https://github.com/ANTsX/ANTsPy) fails try to manually install it via: @@ -125,6 +123,22 @@ 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: + +- [fmriprep](https://fmriprep.org/en/stable/) +- [bidspm](https://bidspm.readthedocs.io/en/latest/general_information.html) + +Obviousvly your fmri data must include the eyes of your participant for bidsmreye to work. + + + ### CLI Type the following for more information: @@ -133,26 +147,34 @@ 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. + ```bash bidsmreye --action prepapre \ bids_dir \ output_dir ``` -`--action generalize` means that the extracted data will be used as input and -that bidsmeye will use it to predict what were the eye movements of your -participants. +## 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. ```bash bidsmreye --action generalize \ bids_dir \ output_dir ``` +## Doing it all at once -"all" does "prepare" then "generalize". +`--action all` does "prepare" then "generalize". ```bash bidsmreye --action all \ diff --git a/docs/questions/prepare.question.md b/docs/questions/prepare.question.md new file mode 100644 index 0000000..2666a91 --- /dev/null +++ b/docs/questions/prepare.question.md @@ -0,0 +1,18 @@ +--- +title: Is the "prepare" only suitable for the datasets that have eye-tracking info? +alt_titles: + - If want to only guess the eye position, should I use "generalize"? +--- + +No the `prepare` action is necessary for all datasets, +whether they have eye-tracking info or not. + +This action: + +- registers the data to MNI if this is not the case already +- registers the data the the deepmreye template +- extracts data from the eyes mask + +In future versions of bidsmreye, this action should also be able to combine +the extracted data with the eye gaze position coming +from preprocessed eyetracking data. diff --git a/docs/questions/validation.question.md b/docs/questions/validation.question.md new file mode 100644 index 0000000..7c7e9c3 --- /dev/null +++ b/docs/questions/validation.question.md @@ -0,0 +1,16 @@ +--- +title: "How I should structure my input data?" +alt_titles: + - bidsmreye gives me an error saying that the dataset must in bids format. + - "What input format does bidsmreye expect?" +--- + +bidsmreye requires your input fmri data: + + - to be minimally preprocessed + - with filenames and structure that conforms to a BIDS derivative dataset. + +Two bids apps are available to generate those types of preprocessed data: + +- [fmriprep](https://fmriprep.org/en/stable/) +- [bidspm](https://bidspm.readthedocs.io/en/latest/general_information.html) diff --git a/docs/source/FAQ.md b/docs/source/FAQ.md index 086dab6..f306bdb 100644 --- a/docs/source/FAQ.md +++ b/docs/source/FAQ.md @@ -1,7 +1,38 @@ # Frequently Asked Questions +- [How I should structure my input data?](#how-i-should-structure-my-input-data) +- [Is the "prepare" only suitable for the datasets that have eye-tracking info?](#is-the-"prepare"-only-suitable-for-the-datasets-that-have-eye-tracking-info) - [Should I use the automatically generated methods section?](#should-i-use-the-automatically-generated-methods-section) + +## How I should structure my input data? + +bidsmreye requires your input fmri data: + + - to be minimally preprocessed + - with filenames and structure that conforms to a BIDS derivative dataset. + +Two bids apps are available to generate those types of preprocessed data: + +- [fmriprep](https://fmriprep.org/en/stable/) +- [bidspm](https://bidspm.readthedocs.io/en/latest/general_information.html) + + +## Is the "prepare" only suitable for the datasets that have eye-tracking info? + +No the `prepare` action is necessary for all datasets, +whether they have eye-tracking info or not. + +This action: + +- registers the data to MNI if this is not the case already +- registers the data the the deepmreye template +- extracts data from the eyes mask + +In future versions of bidsmreye, this action should also be able to combine +the extracted data with the eye gaze position coming +from preprocessed eyetracking data. + ## Should I use the automatically generated methods section? diff --git a/docs/source/demo.md b/docs/source/demo.md index c97a60c..83f738e 100644 --- a/docs/source/demo.md +++ b/docs/source/demo.md @@ -1,7 +1,8 @@ # Demo -This will run bidsMReye on the fmriprep preprocessed data of the SPM MOAE -dataset (that you can find on the open science framework). +This deom will run the docker image of bidsMReye +on the fmriprep preprocessed data of the SPM MOAE dataset +(that you can find on the open science framework). For Linux or MacOS you can use `make` to get the data of the demo. @@ -19,8 +20,6 @@ For Windows you will have to download the data manually. The directory where you want to run the demo should look like this: ```bash -├── models -│ └── dataset1_guided_fixations.h5 └── tests └── data └── moae_fmriprep @@ -31,57 +30,35 @@ The directory where you want to run the demo should look like this: └── func ``` -## Using docker +## Preparing the data -For Linux or MacOS you can use `make` to get run all the steps of the demo. - -```bash -make docker_demo -``` +Extracts the timeseries from the eye mask in the preprocessed fMRI images. ```bash docker run --rm -it \ --user "$(id -u):$(id -g)" \ -v $PWD/tests/data/moae_fmriprep:/home/neuro/data \ -v $PWD/outputs/moae_fmriprep/derivatives:/home/neuro/outputs/ \ - cpplab/bidsmreye:latest \ - /home/neuro/data/ \ - /home/neuro/outputs/ \ - participant \ - --action prepare + cpplab/bidsmreye:latest \ + /home/neuro/data/ \ + /home/neuro/outputs/ \ + participant \ + --action prepare ``` +## Computing the eye movements + +This step will use the extracted timeseries to predict the eye movements +using the default pre-trained model of deepmreye. + ```bash docker run --rm -it \ --user "$(id -u):$(id -g)" \ -v $PWD/tests/data/moae_fmriprep:/home/neuro/data \ -v $PWD/outputs/moae_fmriprep/derivatives:/home/neuro/outputs/ \ - cpplab/bidsmreye:latest \ - /home/neuro/data/ \ - /home/neuro/outputs/ \ - participant \ - --action generalize -``` - -## After installing the package locally - -For Linux or MacOS you can use `make` to get run all the steps of the demo. - -```bash -make demo -``` - -This will run the different steps of the demo: - -```bash -bids_dir="$PWD/tests/data/moae_fmriprep " -output_dir="$PWD/outputs " - -bidsmreye --action prepare \ - $bids_dir \ - $output_dir - -bidsmreye --action generalize \ - $bids_dir \ - $output_dir + cpplab/bidsmreye:latest \ + /home/neuro/data/ \ + /home/neuro/outputs/ \ + participant \ + --action generalize ```