Merge pull request #21 from marcobarilari/marco_add_mriqc

Add mriqc section

Author: marcobarilari

doc/cpp_fmriprep.slurm

@@ -1,10 +1,10 @@
 #!/bin/bash
 
 #SBATCH --job-name=fMRIprep
-#SBATCH --time=00:05:00 # hh:mm:ss
+#SBATCH --time=9:00:00 # hh:mm:ss
 
 #SBATCH --ntasks=1
-#SBATCH --cpus-per-task=6
+#SBATCH --cpus-per-task=9
 #SBATCH --mem-per-cpu=10000 # megabytes
 #SBATCH --partition=batch,debug
 
@@ -14,33 +14,40 @@
 
 #SBATCH --comment=project-name
 
-#export OMP_NUM_THREADS=1
-#export MKL_NUM_THREADS=1
+#export OMP_NUM_THREADS=9
+#export MKL_NUM_THREADS=9
 
 ## CPP frmiprep script for CECI cluster
 #
 # writtent by CPP people
 #
-# Submission script for Lemaitre3
-#
-# USAGE on cluster:
-#
-#   sbatch cpp_fmriprep.sh <subjID> <TaskName>
-#
+# Submission command for Lemaitre3
+# 
+# sbatch cpp_fmriprep.slurm <subjID> <TaskName>
+# 
 # examples:
-#
 # - 1 subject 1 task
-# sbatch cpp_fmriprep.sh sub-01 visMotLocalizer
-#
+# sbatch cpp_fmriprep.slurm sub-01 visMotLocalizer
+# 
+# - 1 subject all task
+# sbatch cpp_fmriprep.slurm sub-01 ''
+# 
+# - all subjects 1 task
+# sbatch cpp_fmriprep.slurm '' visMotLocalizer
+# 
 # - multiple subjects
-# sbatch cpp_fmriprep.sh 'sub-01 sub-02` visMotLocalizer
+# sbatch cpp_fmriprep.slurm 'sub-01 sub-02' visMotLocalizer
+# 
+# - multiple tasks
+# sbatch cpp_fmriprep.slurm sub-01 'visMotLocalizer audMotLocalizer'
 #
-# - multipple tasks
-# sbatch cpp_fmriprep.sh sub-01 'visMotLocalizer audMotLocalizer'
+# - submit all the subjects (1 per job) all at once
+# read subj list to submit each to a job for all the tasks
+# !!! to run from within `raw` folder
+# ls -d sub* | xargs -n1 -I{} sbatch path/to/cpp_fmriprep.slurm {} ''
 
-# create jobs_report and output folders in case they don't exist
+# create jobs_report folder in case they don't exist
 mkdir -p $HOME/jobs_report/
-mkdir -p "${output_dir}"
 
 # fail whenever something is fishy
 # -e exit immediately
@@ -72,6 +79,9 @@ freesurfer_license_folder="$HOME/tools/freesurfer_license"
 # make the scratch folder, here there is no limit space and fmriprep can store stuff in case of crash and do not start from zero again
 mkdir -p "${scratch_dir}"/work-fmriprep
 
+# create output folder in case it does not exists
+mkdir -p "${output_dir}"
+
 singularity run --cleanenv \
     -B "${scratch_dir}":/scratch_dir \
     -B "${bids_dir}":/bids_dir \

doc/cpp_mriqc.slurm

@@ -0,0 +1,76 @@
+#!/bin/bash
+
+#SBATCH --job-name=MRIqc
+#SBATCH --time=4:00:00 # hh:mm:ss
+
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=9
+#SBATCH --mem-per-cpu=10000 # megabytes
+#SBATCH --partition=batch,debug
+
+#SBATCH --mail-user=marco.barilari@uclouvain.be
+#SBATCH --mail-type=ALL
+#SBATCH --output=/home/ucl/irsp/marcobar/jobs_report/mriqc_job-%j.txt
+
+#SBATCH --comment=project-name
+
+#export OMP_NUM_THREADS=9
+#export MKL_NUM_THREADS=9
+
+## CPP MRIqc script for CECI cluster
+#
+# writtent by CPP people
+#
+# Submission command for Lemaitre3
+# 
+# sbatch cpp_mriqc.slurm <subjID>
+# 
+# examples:
+# - 1 subject
+# sbatch cpp_mriqc.slurm sub-01 
+# 
+# - all subjects
+# sbatch cpp_mriqc.slurm ''
+# 
+# - multiple subjects
+# sbatch cpp_mriqc.slurm 'sub-01 sub-02' 
+#
+# - submit all the subjects (1 per job) all at once
+# read subj list to submit each to a job
+# !!! to run from within `raw` folder
+# ls -d sub* | xargs -n1 -I{} sbatch path/to/cpp_mriqc.slurm {}
+
+# create jobs_report folder in case they don't exist
+mkdir -p $HOME/jobs_report/
+
+# fail whenever something is fishy
+# -e exit immediately
+# -x to get verbose logfiles
+# -u to fail when using undefined variables
+# https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
+set -e -x -u -o pipefail
+
+module --force purge
+
+subjID=$1
+
+# "latest" or procide specific version number
+MRIQC_VERSION="23.1.0"
+
+# set username to locate scratch folder
+ceci_username="marcobar"
+
+path_to_singularity_image="$HOME/tools/containers/images/bids/bids-mriqc--${MRIQC_VERSION}.sing"
+bids_dir="$HOME/mriqc_trial/raw"
+output_dir="$HOME/mriqc_trial/derivatives/mriqc"
+
+# create output folder in case it does not exists
+mkdir -p "${output_dir}"
+
+singularity run --cleanenv \
+    -B "${bids_dir}":/data \
+    -B "${output_dir}":/out \
+        "${path_to_singularity_image}" \
+            /data \
+            /out \
+            participant --participant-label "${subjID}" 

doc/cpp_mriqc_group.slurm

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+#SBATCH --job-name=MRIqc
+#SBATCH --time=9:00:00 # hh:mm:ss
+
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=9
+#SBATCH --mem-per-cpu=10000 # megabytes
+#SBATCH --partition=batch,debug
+
+#SBATCH --mail-user=marco.barilari@uclouvain.be
+#SBATCH --mail-type=ALL
+#SBATCH --output=/home/ucl/irsp/marcobar/jobs_report/mriqc_job-%j.txt
+
+#SBATCH --comment=project-name
+
+#export OMP_NUM_THREADS=9
+#export MKL_NUM_THREADS=9
+
+## CPP MRIqc script for CECI cluster
+#
+# writtent by CPP people
+#
+# Submission command for Lemaitre3 after running mriqc for each participant
+# 
+# sbatch cpp_mriqc_group.slurm
+
+# create jobs_report folder in case they don't exist
+mkdir -p $HOME/jobs_report/
+
+# fail whenever something is fishy
+# -e exit immediately
+# -x to get verbose logfiles
+# -u to fail when using undefined variables
+# https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
+set -e -x -u -o pipefail
+
+module --force purge
+
+# "latest" or procide specific version number
+MRIQC_VERSION="23.1.0"
+
+# set username to locate scratch folder
+ceci_username="marcobar"
+
+path_to_singularity_image="$HOME/tools/containers/images/bids/bids-mriqc--${MRIQC_VERSION}.sing"
+bids_dir="$HOME/mriqc_trial/raw"
+output_dir="$HOME/mriqc_trial/derivatives/mriqc"
+
+# create mriqc output folder in case they don't exist
+mkdir -p "${output_dir}"
+
+singularity run --cleanenv \
+    -B "${bids_dir}":/data \
+    -B "${output_dir}":/out \
+        "${path_to_singularity_image}" \
+            /data \
+            /out \
+            group

doc/run_fmriprep.md

@@ -1,4 +1,4 @@
-# Run fmriprep and mriQC on the cluster
+# Run fmriprep on the cluster
 
 Written by CPP lab people
 
@@ -24,9 +24,20 @@ here the example is with `fmriprp version 21.0.1` but check for newer version, l
 ```bash
 datalad install https://github.com/ReproNim/containers.git
 
-datalad get containers/images/bids/bids-fmriprep--21.0.1.sing
+cd containers
+
+datalad get images/bids/bids-fmriprep--21.0.1.sing
 ```
 
+In case you have installe the repo a while a ago and you want to use a new version of fmriprep., update the `containers` repo via:
+
+```bash
+# go to the repo folder
+cd path/to/containers
+
+datald update --merge
+``````
+
 Depending on the cluster “unlock” is needed or not. No need for `lemaitre3`.
 
 ```bash
@@ -144,9 +155,7 @@ should consider as `bold` as `T1w`.
 The one below corresponds to the fMRIprep default (also available inside this
 repo).
 
-See this part of the FAQ for more info:
-
-https://fmriprep.org/en/21.0.2/faq.html#how-do-I-select-only-certain-files-to-be-input-to-fMRIPrep
+See this part of the FAQ for more info [here](https://fmriprep.org/en/21.0.2/faq.html#how-do-I-select-only-certain-files-to-be-input-to-fMRIPrep)
 
 ```json
 {% include "bids_filter_file.json" %}

doc/run_mriqc.md

@@ -1,3 +1,127 @@
-# WIP
+# WIP# Run MRIqc on the cluster
+
+Written by CPP lab people
+
+To contribute see [here](https://cpp-lln-lab.github.io/CPP_HPC/contributing/)
+
+!!! Warning
+
+    Space problem since the `work` folder is not set in the script. Marco is working on it.
+
+
+## General tips
+
+- The more resources required, the faster it can be but the more waiting time
+
+- To try things, set `--time=00:05:00` and `--partition=debug` so it starts
+  right away and you can check if it at least starts without problems (eg the
+  singularity images is running, data are bids compatible or data folders are
+  loaded proprerly). See below in the section [Submit a MRIqc job via sbatch command](#submit-a-MRIqc-job-via-sbatch-command-without-a-script-mainly-for-debug-purposes)
+
+## Prepare to run MRIqc on the cluster
+
+- have your data on the cluster
+- install datalad on your user (see [here](https://github.com/cpp-lln-lab/CPP_HPC/install_datalad))
+- get the fmriprep singularity image as follow:
+
+here the example is with `MRIqc version 23.1.0` but check for newer version, list of fmriprep version available [here](https://hub.docker.com/r/nipreps/fmriprep/tags/)
+
+```bash
+datalad install https://github.com/ReproNim/containers.git
+
+cd containers
+
+datalad get images/bids/bids-mriqc--23.1.0.sing
+```
+
+In case you have installe the repo a while a ago and you want to use a new version of fmriprep., update the `containers` repo via:
+
+```bash
+# go to the repo folder
+cd path/to/containers
+
+datald update --merge
+``````
+
+Depending on the cluster “unlock” is needed or not. No need for `lemaitre3`.
+
+```bash
+datalad unlock containers/images/bids/bids-mriqc--23.1.0.sing
+```
+
+## Submit a MRIqc job via a `slurm` script
+
+- pros:
+    - easy to run for multiple subject
+- cons:
+    - the `slurm` script can be hard to edit from within the cluster in case of error or a change of mind with fmriprep
+    options. You can edit via `vim` or locally and then
+    uploading a newversion.
+
+### Participants level
+
+Content of the `cpp_mriqc.slurm` file (download and edit from [here](cpp_mriqc.slurm))
+
+!!! Warning
+
+    1. Read the MRIqc documentation to know what you are doing and how the arguments of the run call effects the results
+    2. All the paths and email are set afte Marco's users for demosntration. 
+    3. Edit the scripts with the info you need to make it run for your user from top to buttom of the script, do not over look the first "commented" chunk cause it is not a real commented section (check the email and job report path, data paths and the `username` etc.). 
+
+```bash
+{% include "cpp_mriqc.slurm" %}
+```
+
+On the cluster prompt, submit the jobs as:
+
+```bash
+# Submission command for Lemaitre3
+
+# USAGE on cluster:
+
+sbatch cpp_mriqc.slurm <subjID>
+
+# examples:
+# - 1 subject
+
+sbatch cpp_mriqc.slurm sub-01
+
+# submit all the subjects (1 per job) all at once
+# read subj list to submit each to a job for all the tasks
+# !!! to run from within `raw` folder
+ls -d sub* | xargs -n1 -I{} sbatch path/to/cpp_mriqc.slurm {}
+```
+
+### Group level 
+
+Content of the `cpp_mriqc_group.slurm` file (download and edit from [here](cpp_mriqc_group.slurm))
+
+!!! Warning
+
+    1. Read the MRIqc documentation to know what you are doing and how the arguments of the run call effects the results
+    2. All the paths and email are set afte Marco's users for demosntration. 
+    3. Edit the scripts with the info you need to make it run for your user from top to buttom of the script, do not over look the first "commented" chunk cause it is not a real commented section (check the email and job report path, data paths and the `username` etc.). 
+
+```bash
+{% include "cpp_mriqc_group.slurm" %}
+```
+
+On the cluster prompt, submit the jobs as:
+
+```bash
+# Submission command for Lemaitre3
+
+# USAGE on cluster:
+
+# no need to priovide any input
+
+sbatch cpp_mriqc_group.slurm
+```
+
+## TIPS
+
+### check your job
+
+see [here](https://github.com/cpp-lln-lab/CPP_HPC/cluster_code_snippets/#check-your-running-jobs)
 
 To contribute see [here](https://cpp-lln-lab.github.io/CPP_HPC/contributing/)