[DOC] update FAQ (#121)

* update doc * update faq
cpp-lln-lab · Jan 20, 2023 · c0b3c78 · c0b3c78
1 parent a748afe
commit c0b3c78
Show file tree

Hide file tree

Showing 6 changed files with 121 additions and 55 deletions.
diff --git 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
@@ -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:
 
 <!-- may help on windows ? -->
@@ -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.
+
+<!-- old fmriprep versions may not 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
@@ -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
@@ -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
@@ -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)
 
+<a name="how-i-should-structure-my-input-data"></a>
+## 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)
+
+<a name="is-the-"prepare"-only-suitable-for-the-datasets-that-have-eye-tracking-info"></a>
+## 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.
+
 <a name="should-i-use-the-automatically-generated-methods-section"></a>
 ## Should I use the automatically generated methods section?
 

diff --git 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
 ```