Skip to content

Commit d6f823d

Browse files
oestebanoesteban
committed
DOC: Substantial update and re-structuring to the documentation
Deep revision of the documentation site.
1 parent 7997e7d commit d6f823d

File tree

12 files changed

+228
-1362
lines changed

12 files changed

+228
-1362
lines changed

‎README.rst‎

Lines changed: 59 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,69 @@
11
A Python client to query TemplateFlow
22
=====================================
33

4-
|DOI| |CircleCI| |Build Status| |Pypi|
5-
6-
Group inference and reporting of neuroimaging studies require that
7-
individual’s features are spatially aligned into a common frame where
8-
their location can be called standard. To that end, a multiplicity of
9-
brain templates with anatomical annotations (i.e., atlases) have been
10-
published. However, a centralized resource that allows programmatic
11-
access to templates is lacking. TemplateFlow is a modular,
12-
version-controlled resource that allows researchers to use templates
13-
“off-the-shelf” and share new ones.
14-
15-
.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.2583289.svg
4+
|Zenodo| |preprint| |CircleCI| |Build Status| |Pypi|
5+
6+
Reference anatomies of the brain and corresponding atlases play a central role in experimental
7+
neuroimaging workflows and are the foundation for reporting standardized results.
8+
The choice of such references —i.e., templates— and atlases is one relevant source of methodological
9+
variability across studies, which has recently been brought to attention as an important challenge
10+
to reproducibility in neuroscience.
11+
*TemplateFlow* is a publicly available framework for human and nonhuman brain models.
12+
The framework combines an open database with software for access, management, and vetting,
13+
allowing scientists to distribute their resources under *FAIR* —findable, accessible, interoperable,
14+
reusable— principles.
15+
*TemplateFlow* supports a multifaceted insight into brains across species, and enables multiverse
16+
analyses testing whether results generalize across standard references, scales, and in the long term,
17+
species, thereby contributing to increasing the reliability of neuroimaging results.
18+
19+
Publishing resources in the *TemplateFlow* Archive
20+
--------------------------------------------------
21+
Please check the `Contributing section of the TemplateFlow website
22+
<https://www.templateflow.org/contributing/submission/>`__.
23+
24+
License information
25+
-------------------
26+
*TemplateFlow* adheres to the
27+
`general licensing guidelines <https://www.nipreps.org/community/licensing/>`__
28+
of the *NiPreps framework*.
29+
30+
License
31+
~~~~~~~
32+
Copyright (c) 2021, the *NiPreps* Developers.
33+
34+
The *TemplateFlow* Python Client is
35+
licensed under the Apache License, Version 2.0 (the "License");
36+
you may not use this file except in compliance with the License.
37+
You may obtain a copy of the License at
38+
`http://www.apache.org/licenses/LICENSE-2.0
39+
<http://www.apache.org/licenses/LICENSE-2.0>`__.
40+
41+
Unless required by applicable law or agreed to in writing, software
42+
distributed under the License is distributed on an "AS IS" BASIS,
43+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
44+
See the License for the specific language governing permissions and
45+
limitations under the License.
46+
47+
Acknowledgements
48+
----------------
49+
This work is steered and maintained by the `NiPreps Community <https://www.nipreps.org>`__.
50+
The development of this resource was supported by
51+
the Laura and John Arnold Foundation (RAP and KJG),
52+
the NIBIB (R01EB020740, SSG; 1P41EB019936-01A1SSG, YOH),
53+
the NIMH (RF1MH121867, RAP, OE; R24MH114705 and R24MH117179, RAP; 1RF1MH121885 SSG),
54+
NINDS (U01NS103780, RAP), and NSF (CRCNS 1912266, YOH).
55+
OE acknowledges financial support from the SNSF Ambizione project
56+
“*Uncovering the interplay of structure, function, and dynamics of
57+
brain connectivity using MRI*” (grant number
58+
`PZ00P2_185872 <http://p3.snf.ch/Project-185872>`__).
59+
60+
.. |Zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.2583289.svg
1661
:target: https://doi.org/10.5281/zenodo.2583289
1762
.. |CircleCI| image:: https://circleci.com/gh/templateflow/python-client/tree/master.svg?style=shield
1863
:target: https://circleci.com/gh/templateflow/python-client/tree/master
1964
.. |Build Status| image:: https://github.com/templateflow/python-client/workflows/Python%20package/badge.svg
2065
:target: https://github.com/templateflow/python-client/actions?query=workflow%3A%22Python+package%22
2166
.. |Pypi| image:: https://img.shields.io/pypi/v/templateflow.svg
2267
:target: https://pypi.python.org/pypi/templateflow/
68+
.. |preprint| image:: https://img.shields.io/badge/doi-10.1101%2F2021.02.10.430678-blue.svg
69+
:target: https://doi.org/10.1101/2021.02.10.430678

‎docs/changes.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
What's new
2+
==========
3+
.. include:: ../CHANGES.rst

‎docs/datalad.rst‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
DataLad
2+
=======
3+
The *TemplateFlow* Archive is an infrastructure reliant on DataLad.
4+
Therefore, it is possible (and recommended for those who want to
5+
leverage the power of DataLad) to access the Archive using just
6+
DataLad.
7+
8+
Installing the Archive
9+
----------------------
10+
The archive is indexed by a superdataset, which can be installed with::
11+
12+
$ datalad install -r https://github.com/templateflow/templateflow.git
13+
14+
or just::
15+
16+
$ datalad install -r ///templateflow
17+
18+
Please note the ``-r`` modifier, which will automatically install all the
19+
subdatasets.
20+
In this case, subdatasets (sub-folders) are the individual templates
21+
(signified by the ``tpl-`` prefix).
22+
If the operation finished successfully, you should be able to change directories
23+
into templateflow and see something like::
24+
25+
$ cd templateflow/
26+
$ ls -lh
27+
total 76K
28+
-rw-rw-r-- 1 oesteban oesteban 122 Sep 8 10:42 dataset_description.json
29+
drwxrwxr-x 4 oesteban oesteban 4.0K Sep 8 10:43 tpl-fsaverage
30+
drwxrwxr-x 5 oesteban oesteban 4.0K Sep 8 10:43 tpl-fsLR
31+
drwxrwxr-x 5 oesteban oesteban 4.0K Sep 8 10:42 tpl-MNI152Lin
32+
drwxrwxr-x 5 oesteban oesteban 16K Sep 8 10:42 tpl-MNI152NLin2009cAsym
33+
drwxrwxr-x 5 oesteban oesteban 4.0K Sep 8 10:42 tpl-MNI152NLin2009cSym
34+
drwxrwxr-x 5 oesteban oesteban 12K Sep 8 10:42 tpl-MNI152NLin6Asym
35+
drwxrwxr-x 5 oesteban oesteban 4.0K Sep 8 10:42 tpl-MNI152NLin6Sym
36+
drwxrwxr-x 16 oesteban oesteban 4.0K Sep 8 10:43 tpl-MNIInfant
37+
drwxrwxr-x 11 oesteban oesteban 4.0K Sep 8 10:43 tpl-MNIPediatricAsym
38+
drwxrwxr-x 5 oesteban oesteban 4.0K Sep 8 10:43 tpl-NKI
39+
drwxrwxr-x 4 oesteban oesteban 4.0K Sep 8 10:43 tpl-OASIS30ANTs
40+
drwxrwxr-x 4 oesteban oesteban 4.0K Sep 8 10:43 tpl-PNC
41+
drwxrwxr-x 5 oesteban oesteban 4.0K Sep 8 10:43 tpl-WHS
42+
43+
.. important ::
44+
45+
The DataLad install operation DOES NOT download the data.
46+
Please see how to get the data below.
47+
48+
Accessing templates
49+
-------------------
50+
Before going ahead, make sure you understand how DataLad works.
51+
Once the TemplateFlow superdataset has been installed, as well as all or
52+
some of the subdatasets, it is possible to access data.
53+
For example, pulling down all T1-weighted NIfTI images of all datasets
54+
would look like::
55+
56+
$ find . -name "*_T1w.nii.gz" -exec datalad get {} +
57+
58+
Let's unpack what happened.
59+
DataLad (or more precisely, the *git-annex* working under the hood)
60+
replaces large files with symbolic links which point to files that
61+
permit the location of the actual resource.
62+
This technique ("annexing" to git) permits keeping the actual files
63+
outside the version control system that (unless set up with some
64+
special extension such as LFS) is not adequate to track large data
65+
files.
66+
Because annexed files are indeed in the file tree, it is possible to
67+
search with tools like ``find`` or ``tree``::
68+
69+
$ tree tpl-MNI152Lin
70+
tpl-MNI152Lin
71+
├── CHANGES
72+
├── LICENSE
73+
├── scripts
74+
│ ├── headmask.py
75+
│ ├── normalize.py
76+
│ └── sanitize.py
77+
├── template_description.json
78+
├── tpl-MNI152Lin_res-01_desc-brain_mask.nii.gz -> .git/annex/objects/J4/J9/URL-s131839--https&c%%files.osf.io%v1%resourc-4a92beb360af57cc397642c99e4f34ee/URL-s131839--https&c%%files.osf.io%v1%resourc-4a92beb360af57cc397642c99e4f34ee
79+
├── tpl-MNI152Lin_res-01_desc-head_mask.nii.gz -> .git/annex/objects/j3/Jw/URL-s168509--https&c%%files.osf.io%v1%resourc-2e366aff039e485ce73875dd1fc912fd/URL-s168509--https&c%%files.osf.io%v1%resourc-2e366aff039e485ce73875dd1fc912fd
80+
├── tpl-MNI152Lin_res-01_PD.nii.gz -> .git/annex/objects/5m/4z/URL-s10250635--https&c%%files.osf.io%v1%resourc-d38cc6938c26e9389a1a9acf03f5a4b6/URL-s10250635--https&c%%files.osf.io%v1%resourc-d38cc6938c26e9389a1a9acf03f5a4b6
81+
├── tpl-MNI152Lin_res-01_T1w.nii.gz -> .git/annex/objects/pM/Fm/URL-s10669511--https&c%%files.osf.io%v1%resourc-2e59511114a1686f937e0127af887b83/URL-s10669511--https&c%%files.osf.io%v1%resourc-2e59511114a1686f937e0127af887b83
82+
├── tpl-MNI152Lin_res-01_T2w.nii.gz -> .git/annex/objects/63/jK/URL-s10096230--https&c%%files.osf.io%v1%resourc-7ee9c493542a55d96d28d55d57a3ee52/URL-s10096230--https&c%%files.osf.io%v1%resourc-7ee9c493542a55d96d28d55d57a3ee52
83+
├── tpl-MNI152Lin_res-02_desc-brain_mask.nii.gz -> .git/annex/objects/vj/pW/URL-s25649--https&c%%files.osf.io%v1%resourc-ebe0f869bd33c9dd7d983a73f7704326/URL-s25649--https&c%%files.osf.io%v1%resourc-ebe0f869bd33c9dd7d983a73f7704326
84+
├── tpl-MNI152Lin_res-02_desc-head_mask.nii.gz -> .git/annex/objects/7q/gF/URL-s32857--https&c%%files.osf.io%v1%resourc-4c79972ef82dfaa9070522b558a8411c/URL-s32857--https&c%%files.osf.io%v1%resourc-4c79972ef82dfaa9070522b558a8411c
85+
├── tpl-MNI152Lin_res-02_PD.nii.gz -> .git/annex/objects/1m/jq/URL-s1411464--https&c%%files.osf.io%v1%resourc-95c7dabef32603e9f1d4f3f9cb92b800/URL-s1411464--https&c%%files.osf.io%v1%resourc-95c7dabef32603e9f1d4f3f9cb92b800
86+
├── tpl-MNI152Lin_res-02_T1w.nii.gz -> .git/annex/objects/Wf/Fx/URL-s1448817--https&c%%files.osf.io%v1%resourc-2ba5a81206dff8bbf84fb319ed1d7201/URL-s1448817--https&c%%files.osf.io%v1%resourc-2ba5a81206dff8bbf84fb319ed1d7201
87+
└── tpl-MNI152Lin_res-02_T2w.nii.gz -> .git/annex/objects/X8/Fv/URL-s1375781--https&c%%files.osf.io%v1%resourc-6f1f3ad0441ef1200307a70b32b4f303/URL-s1375781--https&c%%files.osf.io%v1%resourc-6f1f3ad0441ef1200307a70b32b4f303
88+
89+
1 directory, 16 files
90+
91+
If your terminal has advanced coloring, you will also see that only the two
92+
links ending with ``_T1w.nii.gz`` are not "broken" links.
93+
This is because we did ``datalad get`` on both of them in the previous step.
94+
DataLad only pulls the actual file objects when they are requested.

‎docs/index.rst‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,7 @@ Contents
1010
.. toctree::
1111
:maxdepth: 3
1212

13-
naming
14-
tutorials
13+
installation
14+
datalad
1515
api
16-
17-
What's new
18-
----------
19-
.. include:: ../CHANGES.rst
16+
changes

‎docs/installation.rst‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
Installation
2+
============
3+
*TemplateFlow Client* is distributed via *Pypi* and can easily be installed
4+
within your Python distribution with::
5+
6+
python -m pip install templateflow
7+
8+
Alternatively, you can install the bleeding-edge version of the software
9+
directly from the GitHub repo with::
10+
11+
python -m pip install git+https://github.com/templateflow/python-client.git@master
12+
13+
To verify the installation, you can run the following command::
14+
15+
python -c "import templateflow as tf; print(tf.__version__)"
16+
17+
You should see the version number.
18+
19+
Settings
20+
--------
21+
The *TemplateFlow Client* has two modes of operation: (a) based on
22+
`DataLad <https://datalad.org>`__, or (b) direct downloads from Amazon S3.
23+
24+
By default, the client will operate in direct download mode (b) which is
25+
more lightweight and comes with some limitations, as all the advanced
26+
version control management afforded by DataLad will not be available.
27+
28+
For the most part, and considering that templates/atlases do not substantially
29+
change over time, the direct download mode should be sufficient to anyone
30+
developing new pipelines and tools, as it will provided the latest version
31+
of any available template set.
32+
33+
**TemplateFlow "home" folder**.
34+
The lazy-loading implementation of the client requires some folder on the host
35+
where template resources can be stored (therefore, write permissions are
36+
required). By default, the home folder will be ``$HOME/.cache/templateflow``.
37+
This setting can be overriden by defining the environment variable ``TEMPLATEFLOW_HOME``
38+
before running the client, for example::
39+
40+
$ export TEMPLATEFLOW_HOME=$DATA/.templateflow
41+
42+
**Configuring the operation mode**.
43+
By default, the client will operate without DataLad (and hence, without version control).
44+
To set up the DataLad mode, make sure DataLad is installed and functioning on your host,
45+
and then::
46+
47+
$ export TEMPLATEFLOW_USE_DATALAD=on
48+
49+
It is recommended that the ``$TEMPLATEFLOW_HOME`` folder is wiped out before running the
50+
client again, in case the tool has already been operated in direct download mode::
51+
52+
$ rm -r ${TEMPLATEFLOW_HOME:-$HOME/.cache/templateflow}
53+
54+
**Naming conventions**.
55+
Naming conventions for templates and atlases are available within the
56+
`Contributing section of the TemplateFlow website
57+
<https://www.templateflow.org/contributing/naming/>`__.
58+
59+
Developers
60+
----------
61+
Advanced users and developers who plan to contribute with bugfixes, documentation,
62+
etc. can first clone our Git repository::
63+
64+
git clone https://github.com/templateflow/python-client.git templateflow
65+
66+
and install the tool in *editable* mode::
67+
68+
cd templateflow
69+
python -m pip install -e .

‎docs/naming.rst‎

Lines changed: 0 additions & 52 deletions
This file was deleted.

0 commit comments

Comments
 (0)