<languages/>
[[Category:Software]]

= Load fMRIPrep =
[https://fmriprep.org/en/stable/ fMRIPrep] is an [https://www.nipreps.org NiPreps] app for preprocessing MRI data in [https://bids.neuroimaging.io BIDS] format.  To use this on Alliance resources, first

<pre>
module load apptainer fmriprep
</pre>

= A note about Apptainer =
When you use fMRIPrep on the command line it's using Apptainer under the hood to invoke a container with fMRIPrep set up inside it.  Command line options will be passed along to the fMRIPrep command in the container but you'll also want to affect the Apptainer context.  To do this you'll have to use [https://apptainer.org/docs/user/main/appendix.html Apptainer environment variables].  See the example a few paragraphs down.

= Setup and download TemplateFlow =
Further, fMRIPrep within the container will try to download [https://www.templateflow.org TemplateFlow] templates but will fail.  We have to download this data ourselves in advance

<pre>
module load python git-annex
pip3 install datalad
datalad install -r ///templateflow
</pre>

Load Python and git-annex, install DataLad (you may want to do this in a virtualenv), and then install the TemplateFlow metadataset.  This will be downloaded into a shared directory of the default project you're a part of.  The directory should look something like <code>/lustre03/project/GROUPNAME/shared/templateflow</code>.  You'll have to change into this directory and download actual template subsets like

<pre>
cd /lustre03/project/GROUPNAME/shared/templateflow
datalad get -r tpl-MNI152NLin2009cAsym tpl-OASIS30ANTs 
</pre>

Do the same for all templates you want to make available but the above is a good start.  '''NOTE''' that these templates may take a while to download and that you only have to do these DataLad steps '''once''' and they will be available to you and the rest of your project group until deleted. See [https://www.templateflow.org/usage/archive/ accessing the TemplatFlow archive] for more information.
 
= Define Apptainer environment variables = 

Now we can set up our Apptainer and fMRIPrep environment variables

<pre>
export APPTAINERENV_TEMPLATEFLOW_HOME=/lustre03/project/GROUPNAME/shared/templateflow
export APPTAINER_BIND=/path/to/input,/path/to/output,/path/to/output/logs,$APPTAINERENV_TEMPLATEFLOW_HOME
</pre>

With <code>APPTAINERENV_TEMPLATEFLOW_HOME</code> we tell the fMRIPrep app where to find the TemplateFlow templates.  With <code>APPTAINER_BIND</code> we tell Apptainer where the input, output, and logs will be so that it can mount those directories and make them available to the fMRIprep app within the container. '''NOTE''' that fMRIPrep does not accept very long paths, so keep these directory and filenames short.

= Run like they're chasing you =
Finally, we can run

<pre>
fmriprep /path/to/input /path/to/output participant --work-dir /path/to/output
</pre>

And all should be well in the world. Except ...

= It's a bit more complicated with FreeSurfer =
If you want to run fMRIPrep using FreeSurfer, you'll have to [https://surfer.nmr.mgh.harvard.edu/registration.html register with FreeSurfer], download the license file, copy it to one of the directories in <code>APPTAINER_BIND</code> and use the [https://fmriprep.org/en/20.2.0/usage.html?highlight=freesurfer#Specific%20options%20for%20FreeSurfer%20preprocessing <code>--fs-license-file</code> option].  This is left as an exercise to the reader ... You can do it!

= Thanks =
Thanks to Pierre Rioux for the voluminous input on the instructions on this page!