Skip to content

Commit b242518

Browse files
oestebanoesteban
committed
doc: move TF question to FAQ, restructure spaces
1 parent 0a8153c commit b242518

File tree

2 files changed

+59
-64
lines changed

2 files changed

+59
-64
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 pulling down 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: 17 additions & 58 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* affords *fMRIPrep* with access to 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
@@ -90,8 +106,6 @@ follows::
90106
For further information about how custom templates must be organized and
91107
corresponding naming, please check `the TemplateFlow tutorials
92108
<https://www.templateflow.org/python-client/tutorials.html>`__.
93-
For more general information about *TemplateFlow*, visit
94-
`TemplateFlow.org <https://www.templateflow.org>`__.
95109

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

0 commit comments

Comments
 (0)