update

README.md

@@ -10,35 +10,40 @@ A normative dataset can be downloaded from openneuro: https://openneuro.org/data
 
 # Installation
 
+# Note about dependencies
+
+Apart from the python3 dependencies specified in `requirements.txt`, the package uses FSL (see https://fsl.fmrib.ox.ac.uk/fsl/fslwiki).
+If you are using the container solutions below (option 1 and 2), you don't have to worry about installing FSL as the container already has it.
 
 # Option 1: docker (recommended option!)
 
 The easiest way to install `cvrmap` is to use docker:
 
 ```
-docker pull arovai/cvrmap:VERSION
+docker pull arovai/cvrmap:v1.0
 ```
 
-where `VERSION` is the version you wish to use. Check out the docker hub page (https://hub.docker.com/repository/docker/arovai/cvrmap/general) to find more info on the available images.
+where of course `v1.0` can be replaced by any other available version.
+Check out the docker hub page (https://hub.docker.com/repository/docker/arovai/cvrmap/general) to find more info on the available images.
 
-To launch `cvrmap`, you can use for instance
+To test your installation, you can use for instance
 
 ```
-docker run arovai/cvrmap:VERSION --version
+docker run arovai/cvrmap:v1.0 --version
 ```
 
-This will output the version of `cvrmap`. You can also type
+This will output the version and exit. You can also type
 
 ```
-docker run arovai/cvrmap:VERSION --help
+docker run arovai/cvrmap:v1.0 --help
 ```
 
 for help.
 
-Finally, to pass some data to the docker image, you can use something like:
+For the reader not familiar with docker, you can pass some data to the docker image with
 
 ```
-docker run -v /path/to/your/bids/folder:/rawdata -v /path/to/your/derivatives:/derivatives arovai/cvrmap:VERSION /rawdata /derivatives/cvrmap participant
+docker run -v /path/to/your/bids/folder:/rawdata -v /path/to/your/derivatives:/derivatives arovai/cvrmap:v1.0 /rawdata /derivatives/cvrmap participant
 ```
 
 For more information about the command line options, see the **Usage** section.
@@ -48,19 +53,18 @@ For more information about the command line options, see the **Usage** section.
 You can also build a Singularity image file using
 
 ```
-singularity build arovai.cvrmap.VERSION.sif docker://arovai/cvrmap:VERSION
+singularity build arovai.cvrmap.v1.0.sif docker://arovai/cvrmap:v1.0
 ```
 
-You can for instance run this command inside your home directory, and then you'll have a singularity image file named `arovai.cvrmap.VERSION.sif` in there. To run it, still in the folder where the image is located, run
+You can for instance run this command inside your home directory, and then you'll have a singularity image file named `arovai.cvrmap.v1.0.sif` in there. To run it, still in the folder where the image is located, run
 
 ```
-singularity run -B /path/to/your/bids/folder:/rawdata -B /path/to/your/derivatives:/derivatives arovai.cvrmap.VERSION.sif /rawdata /derivatives/cvrmap participant
+singularity run -B /path/to/your/bids/folder:/rawdata -B /path/to/your/derivatives:/derivatives arovai.cvrmap.v1.0.sif /rawdata /derivatives/cvrmap participant
 ```
 
 Make sure that the folder `/path/to/your/derivatives` exists before launching this command.
 
-Of course you are free to place the image where ever suits you; you'll simply have to adapt the path when calling `singularity`.
-
+Of course, you are free to place the image where ever suits you; you'll simply have to adapt the path when calling `singularity`.
 
 # Option 3: python environment (using git)
 
@@ -70,13 +74,15 @@ The most basic way to install `cvrmap` is to clone this git repo, make `cvrmap`
 pip install -r requirements.txt
 ```
 
-In that case, `cvrmap` can be launched by typing `cvrmap` in a terminal, e.g.
+Regarding the FSL binaries used by `cvrmap`, they should be located at `/opt/fsl/bin`.
+ `cvrmap` can then be launched by typing `cvrmap` in a terminal after you moved to your locally copy of the git folder:
 
 ```
+cd /path/to/git/clone/cvrmap/cvrmap
 cvrmap --version
 ```
 
- By the way: in this setup we recommend to use a python3 virtual environment. We can do this using e.g. `conda`:
+By the way: in this setup we recommend to use a python3 virtual environment. We can do this using e.g. `conda`:
 
 ```
 # create empty environment named "cvrmap"
@@ -91,7 +97,7 @@ Note that the docker image is essentially build using this procedure, as you can
 
 # Usage
 
-To run CVRmap, you must first have data to crunch. If you don't have data, and you want to test CVRmap, you can download the publicly available dataset on openneuro (https://openneuro.org/datasets/ds004604) which include compatible rawdata, fmriprep derivatives, as well as CVRmap outputs.
+To run CVRmap, you must first have data to crunch. If you don't have data, and you want to test CVRmap, you can download the publicly available dataset on openneuro (https://openneuro.org/datasets/ds004604) which include compatible rawdata, fmriprep derivatives, as well as `cvrmap` (v1.0) outputs.
 If you have your own data that you want to analyze with CVRmap, make sure to observe the following:
 first of all, the data are supposed to a BIDS (https://bids-specification.readthedocs.io/en/stable/) dataset. For each subject, you must have a T1w image, a BOLD image and a physiological file containing the breathing data (CO2) recorded during the fMRI scan. For instance, for `sub-01`, the data should look like this:
 
@@ -104,7 +110,7 @@ sub-01/func/sub-01_task-gas_physio.tsv.gz
 sub-01/func/sub-01_task-gas_physio.json
 ```
 
-In this example, the taskname BIDS entity is `gas`. If yours differs, that's not a problem and you'll be able to run CVRmap provided you add the option `--taskname your_task_name` when launching the software.
+In this example, the taskname BIDS entity is `gas`. If yours differs, that's not a problem, and you'll be able to run `cvrmap` provided you add the option `--taskname your_task_name` when launching the software.
 
 Note that the `sub-01/func/sub-01_task-gas_physio.json` file must contain a `SamplingFrequency` field as well as a `co2` field to specify the units of measurement of CO2 levels. An example of `sub-01/func/sub-01_task-gas_physio.json` would be:
 
@@ -121,19 +127,17 @@ Note that the `sub-01/func/sub-01_task-gas_physio.json` file must contain a `Sam
 }
 ```
 
-In this example, the `sub-01/func/sub-01_task-gas_physio.tsv.gz` must have only one colunm, giving the CO2 readings at a sampling frequency of 100 Hz, starting at time 0 with respect to the first valid fMRI volume, in the units of mmHg. Note though that the `StartTime` field is not used at all by `cvrmap`, as it explores various time lags by itself. If the CO2 readings are in percentage of co2 concentration (which is also often used), the "Units" field must be "%", and in that case CVRmap will convert percentages to mmHg automatically. Finally, the total duration of the CO2 recording must not necessarily match the duration of the BOLD acquisition: depending on the case, CVRmap trims or uses a baseline extrapolation automatically.
+In this example, the `sub-01/func/sub-01_task-gas_physio.tsv.gz` must have only one column, giving the CO2 readings at a sampling frequency of 100 Hz, starting at time 0 with respect to the first valid fMRI volume, in the units of mmHg.
+Note though that the `StartTime` field is not used at all by `cvrmap`, as it explores various time lags by itself.
+If the CO2 readings are in percentage of co2 concentration (which is also often used), the "Units" field must be "%", and in that case `cvrmap` will convert percentages to mmHg automatically. Finally, the total duration of the CO2 recording must not necessarily match the duration of the BOLD acquisition: depending on the case, CVRmap trims or uses a baseline extrapolation automatically.
 
 The rawdata must also have been processed using fMRIPrep (https://fmriprep.org/en/stable). A minimalistic fMRIPrep call compatible with CVRmap is:
 
 ```
-fmriprep /path/to/bids_dir /path/to/derivatives/fmriprep participant --fs-license-file /path/to/fslicense --use-aroma --output-spaces MNI152NLin6Asym
+fmriprep /path/to/bids_dir /path/to/derivatives/fmriprep participant --fs-license-file /path/to/fslicense --use-aroma
 ```
 
-Note that this includes the AROMA flag of fMRIPrep. If more output spaces are required for the computation of CVRmaps, say in original, participant's space, then the fMRIPrep call must be adapted by modifying the `--spaces` options accordingly. For instance:
-
-```
-fmriprep /path/to/bids_dir /path/to/derivatives/fmriprep participant --fs-license-file /path/to/fslicense --use-aroma --output-spaces MNI152NLin6Asym T1w
-```
+*Warning* the versions of fMRIPrep above 23.1.0 don't support the `--use-aroma` option anymore. For this reason, we *must* use older versions. We will provide a patch to `cvrmap` to handle newer versions of fMRIPrep in the future.
 
 We are now good to go and launch CVRmap with
 
@@ -142,14 +146,14 @@ cvrmap /path/to/bids_dir /path/to/derivatives/cvrmap participant --fmriprep_dir
 ```
 
 Notes:
-- the exact `cvrmap` command might depend on the installation option you choose.
-- the `--fmriprep_dir` option can be ommitted if the fMRIPrep derivatives are located in `/path/to/bids_dir/derivatives/fmriprep`.
+- the exact `cvrmap` command might depend on the installation option you choose (see above, options 1, 2 and 3)
+- the `--fmriprep_dir` option can be omitted if the fMRIPrep derivatives are located in `/path/to/bids_dir/derivatives/fmriprep`.
 - if the BOLD taskname is not `gas`, you must add `--taskname your_task_name`.
-- if you want the outputs in another space, and if this space was included in the fMRIPrep call, you must add `--space your_custom_space`. The default space is `MNI152NLin2009cAsym`.
+- if you want the outputs in another space, and if this space was included in the fMRIPrep call, you must add `--space your_custom_space`. The default space is `MNI152NLin2009cAsym`, which is also the default space of fMRIPrep.
 - if you want to use the ICA-AROMA classification for signal confounds, then add `--use-aroma`. Otherwise, when the flag is omitted, CVRmap will perform non-aggressive denoising itself using a refinement of the ICA-AROMA classification of noise sources (see paper for more details).
 - more info and options can be found when asking politely for help with `cvrmap --help`.
 
-CVRmap will run for about 2 hours on recent computers. The results are stored in `/path/to/derivatives/cvrmap` following BIDS standard for derivatives. The outputs will typically look as follows:
+`cvrmap` will run for about 3 hours per participant on recent computers. The results are stored in `/path/to/derivatives/cvrmap` following BIDS standard for derivatives.  More specifically, the outputs are as follows:
 
 ```
 sub-01/extras/sub-01_desc-etco2_timecourse.tsv.gz
@@ -167,8 +171,8 @@ sub-01/sub-01_space-MNI152NLin2009cAsym_cvr.json
 sub-01_report.html
 ```
 
-The `extras` folder containes the `etco2` file contains the end-tidal timecourse extracted from the original CO2 readings as well as the non-aggressively denoised BOLD series. Some pictures for the report are stored within `figures`. The delay map contains the computed time delays (or time lags) in seconds, and normalized to the global signal delay. The main map of interest is of course the CVR map! For a quick analysis, an html report is also included.
+The `extras` folder contains the `etco2` file with the end-tidal timecourse extracted from the original CO2 readings as well as the non-aggressively denoised BOLD series (the series are also high-pass filtered and smoothed at 5mm FWHM). Some pictures for the report are stored within `figures`. The delay map contains the computed time delays (or time lags) in seconds, and normalized to the global signal delay. The main map of interest is of course the CVR map! For a quick analysis, the html report is also included.
 
 # Bugs or questions
 
-Should you encounter any bug, weird behavior or if you have questions, do not hesitate to open an issue and we'll happily try to answer!
+Should you encounter any bug, weird behavior or if you have questions, do not hesitate to open an issue, and we'll happily try to answer!

cvrmap/cvrmap

@@ -81,8 +81,9 @@ def main():
                 denoised.data_type = preproc.data_type
             else:
                 msg_info("Data denoising in progress")
-                #denoised = denoise(preproc.path, mask.path, melodic_mixing_df, corrected_noise, parameters['fwhm'])
                 denoised = fsl_preprocessing(preproc.path, melodic_mixing_path, corrected_noise, parameters['fwhm'])
+                # experimental denoising:
+                #denoised = denoise(preproc.path, mask.path, melodic_mixing_df, corrected_noise, parameters['fwhm'])
 
             denoised.measurement_type = 'denoised BOLD'
             denoised.units = 'arbitrary'

docker/Dockerfile

@@ -9,7 +9,7 @@ RUN apt-get install -y python3 pip
 
 # Install cvrmap from github
 RUN cd /opt && git clone https://github.com/ln2t/cvrmap.git
-RUN cd /opt/cvrmap && git checkout fslregfilt
+RUN cd /opt/cvrmap && git checkout v1.0
 RUN pip install -r /opt/cvrmap/requirements.txt
 
 # Install FSL
@@ -18,12 +18,5 @@ COPY fslinstaller.py /root/fslinstaller.py
 RUN apt-get install -y python2
 RUN python2 /root/fslinstaller.py < /root/fsl_config.txt
 
-RUN cd /opt
-
-# Re-install cvrmap
-RUN rm -rf /opt/cvrmap
-RUN cd /opt && git clone https://github.com/ln2t/cvrmap.git
-RUN cd /opt/cvrmap && git checkout fslregfilt_nan
-
 # Set entrypoint to entrypoint script
 ENTRYPOINT ["/opt/cvrmap/docker/entrypoint.sh"]

docker/README.md

@@ -11,7 +11,7 @@ We use the `--no-cache` option to ensure it fetches the last version of the git
 Note that in principle the image has been pushed to docker hub and can be installed directely using
 
 ```
-docker pull arovai/cvrmap:TAG
+docker pull arovai/cvrmap:VERSION
 ```
 
-where `TAG` must be replaced by the version tag you wish to install (e.g. `dev`).
+where `VERSION` must be replaced by the version you wish to install (e.g. `v1.0`).