Skip to content

Commit 4cb3385

Browse files
oestebanoesteban
authored
Merge pull request #1969 from oesteban/docs/custom-templates
DOC: Better describe utilization of custom templates
2 parents e514b74 + 7195cf3 commit 4cb3385

File tree

2 files changed

+80
-77
lines changed

2 files changed

+80
-77
lines changed

‎docs/faq.rst

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -164,15 +164,51 @@ In any case, if you can find your release listed as *flagged* in `this file
164164
of our repo <https://github.com/poldracklab/fmriprep/blob/master/.versions.json>`__,
165165
then please update as soon as possible.
166166

167+
I'm running *fMRIPrep* via Singularity containers - how can I troubleshoot problems?
168+
------------------------------------------------------------------------------------
169+
We have extended `this documentation <singularity.html>`__ to cover some of the most
170+
frequent issues other Singularity users have been faced with.
171+
Generally, users have found it hard to `get TemplateFlow and Singularity to work
172+
together <singularity.html#singularity-tf>`__.
173+
167174
What is *TemplateFlow* for?
168175
---------------------------
169176
*TemplateFlow* enables *fMRIPrep* to generate preprocessed outputs spatially normalized to
170177
a number of different neuroimaging templates (e.g. MNI).
171178
For further details, please check `its documentation section <spaces.html#templateflow>`__.
172179

173-
I'm running *fMRIPrep* via Singularity containers - how can I troubleshoot problems?
174-
------------------------------------------------------------------------------------
175-
We have extended `this documentation <singularity.html>`__ to cover some of the most
176-
frequent issues other Singularity users have been faced with.
177-
Generally, users have found it hard to `get TemplateFlow and Singularity to work
178-
together <singularity.html#singularity-tf>`__.
180+
.. _tf_no_internet:
181+
182+
How do you use TemplateFlow in the absence of access to the Internet?
183+
---------------------------------------------------------------------
184+
This is a fairly common situation in :abbr:`HPCs (high-performance computing)`
185+
systems, where the so-called login nodes have access to the Internet but
186+
compute nodes are isolated, or in PC/laptop enviroments if you are travelling.
187+
*TemplateFlow* will require Internet access the first time it receives a
188+
query for a template resource that has not been previously accessed.
189+
If you know what are the templates you are planning to use, you could
190+
prefetch them using the Python client.
191+
To do so, follow the next steps.
192+
193+
1. By default, a mirror of *TemplateFlow* to store the resources will be
194+
created in ``$HOME/.cache/templateflow``.
195+
You can modify such a configuration with the ``TEMPLATEFLOW_HOME``
196+
environment variable, e.g.::
197+
198+
$ export TEMPLATEFLOW_HOME=$HOME/.templateflow
199+
200+
2. Install the client within your favorite Python 3 environment (this can
201+
be done in your login-node, or in a host with Internet access,
202+
without need for Docker/Singularity)::
203+
204+
$ python -m pip install -U templateflow
205+
206+
3. Use the ``get()`` utility of the client to pull down all the templates you'll
207+
want to use. For example::
208+
209+
$ python -c "from templateflow.api import get; get(['MNI152NLin2009cAsym', 'MNI152NLin6Asym', 'OASIS30ANTs', 'MNIPediatricAsym', 'MNIInfant'])"
210+
211+
After getting the resources you'll need, you will just need to make sure your
212+
runtime environment is able to access the filesystem, at the location of your
213+
*TemplateFlow home* directory.
214+
If you are a Singularity user, please check out :ref:`singularity_tf`.

‎docs/spaces.rst

Lines changed: 38 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,22 @@ nonstandard spaces can be inserted.
1313
*fMRIPrep* will reduce the amount of output spaces to just spaces listed in ``--output-spaces``,
1414
even if other options require resampling the preprocessed data into intermediary spaces.
1515

16+
17+
.. _TemplateFlow:
18+
19+
*TemplateFlow*
20+
""""""""""""""
21+
*TemplateFlow* is a software library and a repository of neuroimaging templates
22+
that allows end-user applications such as *fMRIPrep* to flexibly query and pull
23+
template and atlas information.
24+
In other words, *TemplateFlow* enables *fMRIPrep* to access a wide range
25+
of templates (and also custom templates, see below).
26+
Therefore, *TemplateFlow* is central to define *fMRIPrep*'s interface regarding
27+
template and atlas prior-knowledge.
28+
For more general information about *TemplateFlow*, visit
29+
`TemplateFlow.org <https://www.templateflow.org>`__.
30+
31+
1632
Standard spaces
1733
"""""""""""""""
1834
When using *fMRIPrep* in a workflow that will investigate effects that span across
@@ -23,7 +39,7 @@ For instance, to instruct *fMRIPrep* to use the MNI template brain distributed w
2339
FSL as coordinate reference the option will read as follows: ``--output-spaces MNI152NLin6Asym``.
2440
By default, *fMRIPrep* uses ``MNI152NLin2009cAsym`` as spatial-standardization reference.
2541
Valid template identifiers (``MNI152NLin6Asym``, ``MNI152NLin2009cAsym``, etc.) come from
26-
the `TemplateFlow project <https://github.com/templateflow/templateflow>`__.
42+
the `TemplateFlow repository <https://github.com/templateflow/templateflow>`__.
2743

2844
Therefore, *fMRIPrep* will run nonlinear registration processes against the template
2945
T1w image corresponding to all the standard spaces supplied with the argument
@@ -69,21 +85,27 @@ selecting ``fsLR`` surface space without a density label, ``fsLR:den-32k`` will
6985

7086
Custom standard spaces
7187
""""""""""""""""""""""
72-
Although the functionality is not available yet, the interface of the
73-
``--output-spaces`` permits providing paths to custom templates that
74-
follow TemplateFlow's naming conventions
75-
(e.g., ``/path/to/custom/templates/tpl-MyCustom:res-2``).
76-
Following the example, at least the following files
77-
must be found under under ``/path/to/custom/templates/tpl-MyCustom``::
78-
79-
tpl-MyCustom/
80-
template_description.json
81-
tpl-MyCustom_res-1_T1w.nii.gz
82-
tpl-MyCustom_res-1_desc-brain_mask.nii.gz
83-
tpl-MyCustom_res-2_T1w.nii.gz
84-
tpl-MyCustom_res-2_desc-brain_mask.nii.gz
85-
86-
Although a more comprehensive coverage of standard files would be advised.
88+
To make your custom templates visible by *fMRIPrep*, and usable via
89+
the ``--output-spaces`` argument, please store your template under
90+
*TemplateFlow*'s home directory.
91+
The default *TemplateFlow*'s home directory is ``$HOME/.cache/templateflow``
92+
and that can path can be arbitrarily changed by setting
93+
the ``$TEMPLATEFLOW_HOME`` environment variable.
94+
A minimal example of the necessary files for a template called
95+
``MyCustom`` (and therefore callable via, e.g., ``--output-spaces MyCustom``)
96+
follows::
97+
98+
$TEMPLATEFLOW_HOME/
99+
tpl-MyCustom/
100+
template_description.json
101+
tpl-MyCustom_res-1_T1w.nii.gz
102+
tpl-MyCustom_res-1_desc-brain_mask.nii.gz
103+
tpl-MyCustom_res-2_T1w.nii.gz
104+
tpl-MyCustom_res-2_desc-brain_mask.nii.gz
105+
106+
For further information about how custom templates must be organized and
107+
corresponding naming, please check `the TemplateFlow tutorials
108+
<https://www.templateflow.org/python-client/tutorials.html>`__.
87109

88110
Nonstandard spaces
89111
""""""""""""""""""
@@ -118,58 +140,3 @@ identifier not be found within the ``--output-spaces`` list already.
118140
In other words, running *fMRIPrep* with ``--output-spaces MNI152NLin6Asym:res-2
119141
--use-syn-sdc`` will expand the list of output spaces to be
120142
``MNI152NLin6Asym:res-2 MNI152NLin2009cAsym``.
121-
122-
.. _TemplateFlow:
123-
124-
*TemplateFlow*
125-
""""""""""""""
126-
Group inference and reporting of neuroimaging studies require that individual's
127-
features are spatially aligned into a common frame where their location can be
128-
called *standard*.
129-
To that end, a multiplicity of brain templates with anatomical annotations
130-
(i.e., atlases) have been published.
131-
However, a centralized resource that allows programmatic access to templates
132-
was lacking.
133-
*TemplateFlow* is a modular, version-controlled resource that allows researchers
134-
to use templates "off-the-shelf" and share new ones.
135-
136-
In addition to the repository from which neuroimaging templates are redistributed,
137-
*TemplateFlow* also comprehends a Python client tool to access them programmatically
138-
when used as a library by other software, or interactively by humans.
139-
Therefore *TemplateFlow* is the software module that allows *fMRIPrep* to flexibly
140-
change, and dynamically pull down, new standardized template information.
141-
142-
.. _tf_no_internet:
143-
144-
**How do you use TemplateFlow in the absence of access to the Internet?**.
145-
This is a fairly common situation in :abbr:`HPCs (high-performance computing)`
146-
systems, where the so-called login nodes have access to the Internet but
147-
compute nodes are isolated, or in PC/laptop enviroments if you are travelling.
148-
*TemplateFlow* will require Internet access the first time it receives a
149-
query for a template resource that has not been previously accessed.
150-
If you know what are the templates you are planning to use, you could
151-
prefetch them using the Python client.
152-
To do so, follow the next steps.
153-
154-
1. By default, a mirror of *TemplateFlow* to store the resources will be
155-
created in ``$HOME/.cache/templateflow``.
156-
You can modify such a configuration with the ``TEMPLATEFLOW_HOME``
157-
environment variable, e.g.::
158-
159-
$ export TEMPLATEFLOW_HOME=$HOME/.templateflow
160-
161-
2. Install the client within your favorite Python 3 environment (this can
162-
be done in your login-node, or in a host with Internet access,
163-
without need for Docker/Singularity)::
164-
165-
$ python -m pip install -U templateflow
166-
167-
3. Use the ``get()`` utility of the client to pull down all the templates you'll
168-
want to use. For example::
169-
170-
$ python -c "from templateflow.api import get; get(['MNI152NLin2009cAsym', 'MNI152NLin6Asym', 'OASIS30ANTs', 'MNIPediatricAsym', 'MNIInfant'])"
171-
172-
After pulling down the resources you'll need, you will just need to make sure your
173-
runtime environment is able to access the filesystem, at the location of your
174-
*TemplateFlow home* directory.
175-
If you are a Singularity user, please check out :ref:`singularity_tf`.

0 commit comments

Comments
 (0)