{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "## Quick start with _TemplateFlow Client_ API\n", "\n", "This notebook showcases elementary functionality of the _TemplateFlow_ API. We begin by importing the _TemplateFlow_ Python client." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Using TemplateFlow Client version 0.7.1\n" ] } ], "source": [ "import templateflow\n", "import templateflow.api as tflow\n", "\n", "print(f'Using TemplateFlow Client version {templateflow.__version__}')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Finding templates\n", "\n", "At the time of writing, there are 15 templates available in the _TemplateFlow Archive_. We can use the `templates()` function to obtain the unique resource identifiers for all currently available templates." ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "16 templates:\n", "-------------------\n", "Fischer344\n", "MNI152Lin\n", "MNI152NLin2009cAsym\n", "MNI152NLin2009cSym\n", "MNI152NLin6Asym\n", "MNI152NLin6Sym\n", "MNIInfant\n", "MNIPediatricAsym\n", "NKI\n", "OASIS30ANTs\n", "PNC\n", "RESILIENT\n", "UNCInfant\n", "WHS\n", "fsLR\n", "fsaverage\n" ] } ], "source": [ "templates = tflow.templates()\n", "\n", "# Print template identifiers\n", "ident_fmt = '\\n'.join(templates)\n", "print(f\"{len(templates)} templates:\\n-------------------\\n{ident_fmt}\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Accessing metadata\n", "\n", "We can query metadata associated with individual data files (e.g., a volume or a surface) or general metadata of the template. For example, the method `get_metadata()` returns the general metadata as a dictionary:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "{'Authors': ['Goerzen, D',\n", " 'Fowler, C',\n", " 'Devenyi, GA',\n", " 'Germann, J',\n", " 'Madularu, D',\n", " 'Chakravarty, MM',\n", " 'Near, J'],\n", " 'BIDSVersion': '1.1.0',\n", " 'Curators': ['MacNicol E', 'Esteban O'],\n", " 'Identifier': 'Fischer344',\n", " 'License': 'CC-by-nc-sa-4.0 International',\n", " 'Name': 'MRI-Derived Neuroanatomical Atlas of the Fischer 344 Rat Brain',\n", " 'ReferencesAndLinks': ['https://doi.org/10.5281/zenodo.3555555',\n", " 'https://doi.org/10.1038/s41598-020-63965-x'],\n", " 'TemplateFlowVersion': '1.0.0'}" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Get the full, general metadata dictionary for the Fischer344 rodent template\n", "tflow.get_metadata('Fischer344')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Accordingly, to obtain the usage license for any template, we can select the relevant field from the template's metadata dictionary." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'CC BY 4.0'" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Get the usage license for the OASIS30ANTs template\n", "tflow.get_metadata('OASIS30ANTs')['License']" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Similarly, we can compile desired metadata from all templates. Below, we retrieve for each template its full name, the list of contributing authors, and the usage license." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
NameAuthorsLicense
Fischer344MRI-Derived Neuroanatomical Atlas of the Fisch...[Goerzen, D, Fowler, C, Devenyi, GA, Germann, ...CC-by-nc-sa-4.0 International
MNI152LinLinear ICBM Average Brain (ICBM152) Stereotaxi...[Evans AC, Fox PT, Lancaster J, Zilles K, Wood...See LICENSE file
MNI152NLin2009cAsymICBM 152 Nonlinear Asymmetrical template versi...[Fonov V, Evans AC, Botteron K, Almli CR, McKi...See LICENSE file
MNI152NLin2009cSymICBM 152 Nonlinear Symmetrical template versio...[Fonov V, Evans AC, Botteron K, Almli CR, McKi...See LICENSE file
MNI152NLin6AsymFSL's MNI ICBM 152 non-linear 6th Generation A...[Janke AL]See LICENSE file
MNI152NLin6SymICBM 152 non-linear 6th Generation Symmetric A...[Grabner G, Janke AL, Budge MM, Smith D, Prues...See LICENSE file
MNIInfantMNI Unbiased nonlinear Infant Atlases 0-4.5yr.[Fonov V, Evans AC, Botteron K, Almli CR, McKi...See LICENSE file
MNIPediatricAsymMNI's unbiased standard MRI template for pedia...[Fonov V, Evans AC, Botteron K, Almli CR, McKi...MIT-derived. See LICENSE file
NKIANTs' NKI-1 template[Avants BB, Tustison NJ, Song G, Cook PA, Klei...CC BY 4.0
OASIS30ANTsOASIS30 - Generated with ANTs for MICCAI 2016[Avants BB, Tustison NJ, Song G, Cook PA, Klei...CC BY 4.0
PNCPhiladelphia Neurodevelopmental Cohort template[Satterthwaite TD, Connolly JJ, Ruparel K, Cal...CC BY 4.0
RESILIENTAge-specific adult rat brain MRI templates and...[MacNicol, E, Wright, P, Kim, E, Brusini, I, E...CC-BY-4.0 International
UNCInfantUNC Infant 0-1-2 Atlases[Feng Shi, Pew-Thian Yap, Guorong Wu, Hongjun ...CC-BY
WHSWaxholm Space atlas of the Sprague Dawley rat ...[Papp EA, Leergaard TB, Calabrese E, Johnson G...CC-by-nc-sa-4.0 International
fsLRHCP Pipelines' fsLR template[Tim Coalson, Matt Glasser, Mike Harms, David ...See LICENSE file
fsaverageFreeSurfer's fsaverage template[]See LICENSE file
\n", "
" ], "text/plain": [ " Name \\\n", "Fischer344 MRI-Derived Neuroanatomical Atlas of the Fisch... \n", "MNI152Lin Linear ICBM Average Brain (ICBM152) Stereotaxi... \n", "MNI152NLin2009cAsym ICBM 152 Nonlinear Asymmetrical template versi... \n", "MNI152NLin2009cSym ICBM 152 Nonlinear Symmetrical template versio... \n", "MNI152NLin6Asym FSL's MNI ICBM 152 non-linear 6th Generation A... \n", "MNI152NLin6Sym ICBM 152 non-linear 6th Generation Symmetric A... \n", "MNIInfant MNI Unbiased nonlinear Infant Atlases 0-4.5yr. \n", "MNIPediatricAsym MNI's unbiased standard MRI template for pedia... \n", "NKI ANTs' NKI-1 template \n", "OASIS30ANTs OASIS30 - Generated with ANTs for MICCAI 2016 \n", "PNC Philadelphia Neurodevelopmental Cohort template \n", "RESILIENT Age-specific adult rat brain MRI templates and... \n", "UNCInfant UNC Infant 0-1-2 Atlases \n", "WHS Waxholm Space atlas of the Sprague Dawley rat ... \n", "fsLR HCP Pipelines' fsLR template \n", "fsaverage FreeSurfer's fsaverage template \n", "\n", " Authors \\\n", "Fischer344 [Goerzen, D, Fowler, C, Devenyi, GA, Germann, ... \n", "MNI152Lin [Evans AC, Fox PT, Lancaster J, Zilles K, Wood... \n", "MNI152NLin2009cAsym [Fonov V, Evans AC, Botteron K, Almli CR, McKi... \n", "MNI152NLin2009cSym [Fonov V, Evans AC, Botteron K, Almli CR, McKi... \n", "MNI152NLin6Asym [Janke AL] \n", "MNI152NLin6Sym [Grabner G, Janke AL, Budge MM, Smith D, Prues... \n", "MNIInfant [Fonov V, Evans AC, Botteron K, Almli CR, McKi... \n", "MNIPediatricAsym [Fonov V, Evans AC, Botteron K, Almli CR, McKi... \n", "NKI [Avants BB, Tustison NJ, Song G, Cook PA, Klei... \n", "OASIS30ANTs [Avants BB, Tustison NJ, Song G, Cook PA, Klei... \n", "PNC [Satterthwaite TD, Connolly JJ, Ruparel K, Cal... \n", "RESILIENT [MacNicol, E, Wright, P, Kim, E, Brusini, I, E... \n", "UNCInfant [Feng Shi, Pew-Thian Yap, Guorong Wu, Hongjun ... \n", "WHS [Papp EA, Leergaard TB, Calabrese E, Johnson G... \n", "fsLR [Tim Coalson, Matt Glasser, Mike Harms, David ... \n", "fsaverage [] \n", "\n", " License \n", "Fischer344 CC-by-nc-sa-4.0 International \n", "MNI152Lin See LICENSE file \n", "MNI152NLin2009cAsym See LICENSE file \n", "MNI152NLin2009cSym See LICENSE file \n", "MNI152NLin6Asym See LICENSE file \n", "MNI152NLin6Sym See LICENSE file \n", "MNIInfant See LICENSE file \n", "MNIPediatricAsym MIT-derived. See LICENSE file \n", "NKI CC BY 4.0 \n", "OASIS30ANTs CC BY 4.0 \n", "PNC CC BY 4.0 \n", "RESILIENT CC-BY-4.0 International \n", "UNCInfant CC-BY \n", "WHS CC-by-nc-sa-4.0 International \n", "fsLR See LICENSE file \n", "fsaverage See LICENSE file " ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import pandas as pd\n", "\n", "metadata_fields = ['Name', 'Authors', 'License']\n", "pd.DataFrame({col: [tflow.get_metadata(tpl)[col] for tpl in templates]\n", " for col in metadata_fields}, index=templates)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `get_citations` method allows for easy retrieval and formatting of references. By default, the method gives DOIs for each citation, but it can also be configured to return citations in BibTeX format. (This additionally requires the `doi2bib` package.)" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "@article{2011,\n", "\tdoi = {10.1371/journal.pone.0018746},\n", "\turl = {https://doi.org/10.1371%2uncinfant1.pone.0018746},\n", "\tyear = 2011,\n", "\tmonth = {apr},\n", "\tpublisher = {Public Library of Science ({PLoS})},\n", "\tvolume = {6},\n", "\tnumber = {4},\n", "\tpages = {e18746},\n", "\tauthor = {Feng Shi and Pew-Thian Yap and Guorong Wu and Hongjun Jia and John H. Gilmore and Weili Lin and Dinggang Shen},\n", "\teditor = {Hitoshi Okazawa},\n", "\ttitle = {Infant Brain Atlases from Neonates to 1- and 2-Year-Olds}\n", "}\n" ] } ], "source": [ "print(tflow.get_citations('UNCInfant', bibtex=True)[0])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Accessing data\n", "\n", "To retrieve the template resources themselves, we use the `get` method. This method accepts as arguments the unique template identifier together with any BIDS-like entities: key-value pairs specifying the resource to retrieve. It returns a path to the requested resource, which can (for example) be used with `nibabel` to read the resource into memory. The table below details valid entities for the API.\n", "\n", "|Data entity|API query example|Description|\n", "|:-|:-|:-|\n", "|Template|`\"MNI152Lin\"`|The template dataset to which an image or other data file belongs.|\n", "|Resolution|`resolution=1`|The image resolution. Each resolution is assigned a key, which is defined in the `res` field of `template_description.json`.|\n", "|Mask|`desc=\"brain\", suffix=\"mask\"`|Indicates that the image is a binary-valued annotation, where voxels labelled 1 are part of the mask.|\n", "|Discrete segmentation|`desc=\"malf\", suffix=\"dseg\"`|Indicates that the image is an integer-valued annotation. Each segmentation image file (`.nii.gz` format) is paired with a dictionary of segment names (`.tsv` format).|\n", "|Probabilistic segmentation|`label=\"CSF\", suffix=\"probseg\"`|Indicates that the image is a probabilistic annotation, wherein the value of each voxel indicates the probability of that voxel belonging to the specified label.|\n", "|Atlas|`atlas=\"Schaefer\", desc=\"7Network\"`|The atlas to which a segmentation file belongs.|\n", "|Transformation|`from=\"MNI152Lin\", suffix=\"xfm\"`|File containing a mapping between 2 stereotaxic coordinate spaces. The source space is defined in the `from` field, while the target space is defined in the `tpl` field.|\n", "|Image modality|`suffix=\"T1w\"`|For non-annotation brain images, the suffix indicates whether the image is T1-weighted (`T1w`), T2-weighted (`T2w`), proton density-weighted (`PD`), or T2*-weighted (`T2star`).|\n", "|Template cohort|`cohort=1`|Subsample of a dataset used to generate an average template.|\n", "\n", "_TemplateFlow_ uses a lazy loading scheme for resource retrieval: at installation, the local copy of the archive tree contains only pointers to cloud-based resources. As data resources are requested (for instance using the `get` method), they are synced from the cloud to the local file system. If the data have already been downloaded, they can be retrieved from the local system cache without repeating the download.\n", "\n", "As an example, we can use the `get` method to retrieve a path to the 100-node Schaefer atlas." ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "/Users/rastko/.cache/templateflow/tpl-MNI152NLin2009cAsym/tpl-MNI152NLin2009cAsym_res-01_atlas-Schaefer2018_desc-100Parcels7Networks_dseg.nii.gz\n" ] } ], "source": [ "print(tflow.get(\n", " 'MNI152NLin2009cAsym',\n", " resolution=1,\n", " atlas='Schaefer2018',\n", " desc='100Parcels7Networks',\n", "))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "...or the T1-weighted `MNI152NLin6Asym` template." ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "/Users/rastko/.cache/templateflow/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_T1w.nii.gz\n" ] } ], "source": [ "print(tflow.get(\n", " \"MNI152NLin6Asym\",\n", " desc=None,\n", " resolution=1,\n", " suffix=\"T1w\"\n", "))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "By omitting arguments, we retrieve any data that match the remaining (specified) arguments." ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "[PosixPath('/Users/rastko/.cache/templateflow/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOCPA_probseg.nii.gz'),\n", " PosixPath('/Users/rastko/.cache/templateflow/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOCPAL_probseg.nii.gz'),\n", " PosixPath('/Users/rastko/.cache/templateflow/tpl-MNI152NLin6Asym/tpl-MNI152NLin6Asym_res-01_atlas-HOSPA_probseg.nii.gz')]" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "tflow.get(\"MNI152NLin6Asym\", resolution=1, suffix='probseg')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Integrating _TemplateFlow_ into processing workflows\n", "\n", "\n", "#### Motivation\n", "\n", "_TemplateFlow_ maximizes the accessibility and reuse potential of templates and atlases. For example, let's reuse the base configuration file for FSL FEAT we proposed in our paper (Esteban et al., 2019). The design file `design.fsf` specifies a simple preprocessing workflow with FSL tools. The simplified code listing below shows that, just to make non-default templates available to FSL using the graphical user interface (GUI), at least five steps are necessary:\n", "```bash\n", "# 1. User determines two nondefault templates they want to spatially normalize into\n", "# 2. User manually downloads templates, extracts the required files from packages\n", "$ curl -sSL | tar zxv --no-same-owner -C /data/templates/\n", "# 3. User opens FSL's GUI, edits the target template box content pointing to the appropriate files\n", "# 4. User generates FSL configuration files to permit batch execution on the command line\n", "# 5. For the default and the two nondefault templates, execute FSL's feat:\n", "$ feat design_