Working with TemplateFlow in neuroatlas

Introduction

TemplateFlow is a repository of curated neuroimaging templates and atlases, accessible via a Python client. The neuroatlas package provides an R interface to TemplateFlow, allowing you to easily discover, download, and use these resources within your R workflows.

This vignette provides a guide to using the TemplateFlow functionalities in neuroatlas.

Getting Started: The `templateflow` Object

The main entry point for interacting with TemplateFlow is by creating a templateflow interface object. This object manages the connection to the Python API and caching configurations.

# Create a templateflow interface object
tf <- create_templateflow()
print(tf)

If Python or the templateflow module are not available, you’ll need to install them first:

# Install the Python templateflow package
install_templateflow()

Running print(tf) (if tf is successfully created) will show you: - The local cache path where TemplateFlow files will be stored. neuroatlas sets this up in a user-specific directory (e.g., ~/.cache/neuroatlas/templateflow on Linux). - The status of the connection to the Python API. - A few examples of available templates and their total count.

Output might look like:

#> <neuroatlas TemplateFlow Interface>
#>   Cache Path:  /Users/youruser/Library/Caches/org.R-project.R/R/neuroatlas/templateflow 
#>   API Status:  Connected (Python API handle initialized) 
#>   Available Templates (Examples):  AMYGDALA, ARA, BRODMANN, CHARITE, Fischer344, ... (Total: 76)

(Note: The exact cache path and template list may vary.)

The underlying Python TemplateFlow library uses the TEMPLATEFLOW_HOME environment variable to determine its storage location. neuroatlas attempts to set this to its managed cache path to centralize downloads.

Discovering Templates and Metadata

Before fetching files, you might want to see what’s available.

Listing Available Template Spaces

Use tflow_spaces() to get a list of all top-level template space identifiers:

# List all available template spaces
all_templates <- tflow_spaces()
print(head(all_templates))
cat("Total templates available:", length(all_templates), "\n")

Example output:

#> [1] "AMYGDALA" "ARA"      "BRODMANN" "CHARITE"  "Fischer344" "GS"
#> Total templates available: 76

You can also filter this list with a pattern (regular expression):

# Find all MNI templates
mni_templates <- tflow_spaces(pattern = "MNI")
print(mni_templates)

Example output:

#> [1] "MNI152Lin"           "MNI152NLin2009cAsym" "MNI152NLin6Asym"    
#> [4] "MNI152NLin6Sym"      "MNIInfant"           "MNIPediatricAsym"

Listing Specific Files (Metadata Query)

To find specific files within a template space based on metadata (like suffix, resolution, description), use tflow_files():

# Find all T1w images for the 'MNI152NLin2009cAsym' space
mni_t1w_files <- tflow_files(
  space = "MNI152NLin2009cAsym",
  query_args = list(suffix = "T1w")
)
print(head(mni_t1w_files))

# Find brain masks for 'MNI152NLin2009cAsym' at 1mm resolution
mni_brain_masks <- tflow_files(
  space = "MNI152NLin2009cAsym",
  query_args = list(suffix = "mask", desc = "brain", resolution = "1")
)
print(mni_brain_masks)

This function returns a character vector of full paths to the files that TemplateFlow would download/has cached.

Fetching Templates with `get_template()`

The primary function for fetching template files is get_template(). It provides a flexible R interface to the TemplateFlow archive.

Basic Retrieval (Volumetric Data)

To get the default MNI T1-weighted brain template (1mm resolution):

# Get the default template (MNI152NLin2009cAsym T1w brain at 1mm)
mni_t1w <- get_template() 
print(mni_t1w)

For this vignette, we’ll simulate the object:

#> [1] "MNI152NLin2009cAsym_T1w"

To fetch a specific template space, suffix, and resolution:

# Get MNI T1w template at 2mm resolution
mni_t1w_res2 <- get_template(
  space = "MNI152NLin2009cAsym", 
  suffix = "T1w", 
  resolution = "2" # or 2
)
print(mni_t1w_res2)

Fetching Other Variants (e.g., Masks)

You can specify other TemplateFlow entities like desc (description) and label.

# Get brain mask for MNI template
mni_brain_mask <- get_template(
  space = "MNI152NLin2009cAsym",
  desc = "brain", # 'brain' for brain masks
  suffix = "mask",
  resolution = "1"
)
print(mni_brain_mask)

Getting File Paths Only

If you only need the path to the file (e.g., for use with other tools), set path_only = TRUE:

# Get just the file path, not the loaded NeuroVol object
mni_t1w_path <- get_template(
  space = "MNI152NLin2009cAsym", 
  suffix = "T1w", 
  path_only = TRUE
)
print(mni_t1w_path)

Example output (path will vary):

[1] "/Users/youruser/Library/Caches/org.R-project.R/R/neuroatlas/templateflow/tpl-MNI152NLin2009cAsym/tpl-MNI152NLin2009cAsym_res-01_T1w.nii.gz"

Vectorized Retrieval

get_template() allows one of space, variant, modality, resolution, or label to be a vector, returning a named list of results.

# Get both 1mm and 2mm resolution templates
t1_multi_res <- get_template(
  space = "MNI152NLin2009cAsym", 
  suffix = "T1w",
  resolution = c("1", "2") # Get both 1mm and 2mm
)
print(names(t1_multi_res))
# Access individual resolutions
print(t1_multi_res[["1"]]) # The 1mm NeuroVol
print(t1_multi_res[["2"]]) # The 2mm NeuroVol

Key Parameters for `get_template()`

space: Template identifier (e.g., “MNI152NLin2009cAsym”).
variant: High-level type (e.g., “brain”, “mask”, “probseg”). Used to infer desc and suffix for common cases.
modality: Image type (e.g., “T1w”, “T2w”). Used to infer suffix.
resolution: Resolution (e.g., “1”, “2”, “01”).
desc: Specific TemplateFlow desc field.
suffix: Specific TemplateFlow suffix field.
label: E.g., for variant="probseg", tissue labels like “GM”, “CSF”.
atlas: E.g., “Schaefer2018” if fetching an atlas file.
...: Other BIDS-like entities (e.g., hemi="L", den="32k") can be passed.

The function performs pre-flight validation checks for space and resolution against information available from TemplateFlow.

Typed Helper Functions

For common tasks, neuroatlas provides convenient wrappers:

Volumetric Data with `get_volume_template()`

# Get T1-weighted volume using the convenience function
t1_vol <- get_volume_template(
  template = "MNI152NLin2009cAsym", 
  type = "T1w", 
  resolution = "1"
)
print(t1_vol)

Supported types include “T1w”, “T2w”, “bold”, “probseg”, “dseg”.

Surface Data with `get_surface_template()`

This helper typically returns file paths, as surfaces are often handled by specialized geometry software.

# Get fsLR left hemisphere pial surface
fslr_pial_L_path <- get_surface_template(
  template_id = "fsLR",       # e.g., "fsaverage", "fsLR"
  surface_type = "pial",      # e.g., "pial", "white", "inflated"
  hemi = "L",                 # "L" or "R"
  density = "32k"             # e.g., "32k", "164k" (for fsLR)
)
print(fslr_pial_L_path)

Example output (path will vary):

[1] "/Users/youruser/Library/Caches/org.R-project.R/R/neuroatlas/templateflow/tpl-fsLR/tpl-fsLR_den-32k_hemi-L_desc-pial_surf.gii"

Caching Behavior

neuroatlas and TemplateFlow employ multiple layers of caching: 1. R-level Memoisation: get_template() memoises the file paths it resolves. If you request the same template with identical parameters multiple times in an R session, the path is retrieved from this memory cache. If path_only=FALSE, as_neurovol() (which loads the NIfTI file) is also memoised, so the NeuroVol object itself is cached in memory for the session if the same path is read again. 2. Python Disk Cache: The underlying Python templateflow library maintains a disk cache for downloaded files. neuroatlas configures this to use a directory like ~/.cache/neuroatlas/templateflow (path varies by OS). Once a file is downloaded, subsequent requests (even in new R sessions) will use the disk-cached version if TEMPLATEFLOW_HOME remains consistent.

You can inspect and manage the neuroatlas-specific TemplateFlow cache:

# Show the path to the cache directory
cache_loc <- show_templateflow_cache_path()
print(cache_loc)

# Clear the disk cache and R-level memoisation for TemplateFlow paths
# clear_templateflow_cache()                 # Asks for confirmation if interactive
# clear_templateflow_cache(confirm = FALSE)  # Clears without asking

Integration with Other `neuroatlas` Functions

The outspace argument in functions like get_schaefer_atlas() can accept TemplateFlow identifiers:

# Load Schaefer atlas resampled to a TemplateFlow space
schaefer_in_mni <- get_schaefer_atlas(
  parcels = "100", 
  networks = "7",
  outspace = "MNI152NLin2009cAsym" # Resolves to default 1mm T1w brain
)

# Or be more specific with a list:
schaefer_in_mni_res2 <- get_schaefer_atlas(
  parcels = "100",
  networks = "7",
  outspace = list(space = "MNI152NLin2009cAsym", resolution = "2")
)
print(schaefer_in_mni_res2)

This uses an internal helper .resolve_template_input() to fetch the template and extract its NeuroSpace information.

Summary

The neuroatlas package provides a comprehensive R interface to TemplateFlow:

Easy Setup: Use create_templateflow() to initialize the interface
Discovery: Find templates with tflow_spaces() and tflow_files()
Flexible Retrieval: Use get_template() with various parameters
Integration: Use TemplateFlow spaces directly in atlas functions
Caching: Automatic caching at both R and Python levels

Further Information

For more details on TemplateFlow itself, including the full range of available templates and BIDS-inspired naming conventions, please visit the TemplateFlow website.

neuroatlas Dev Team

2025-06-06

Introduction

Getting Started: The `templateflow` Object

Discovering Templates and Metadata

Listing Available Template Spaces

Listing Specific Files (Metadata Query)

Fetching Templates with `get_template()`

Basic Retrieval (Volumetric Data)

Fetching Other Variants (e.g., Masks)

Getting File Paths Only

Vectorized Retrieval

Key Parameters for `get_template()`

Typed Helper Functions

Volumetric Data with `get_volume_template()`

Surface Data with `get_surface_template()`

Caching Behavior

Integration with Other `neuroatlas` Functions

Summary

Further Information

Working with TemplateFlow in neuroatlas

neuroatlas Dev Team

2025-06-06

Introduction

Getting Started: The templateflow Object

Discovering Templates and Metadata

Listing Available Template Spaces

Listing Specific Files (Metadata Query)

Fetching Templates with get_template()

Basic Retrieval (Volumetric Data)

Fetching Other Variants (e.g., Masks)

Getting File Paths Only

Vectorized Retrieval

Key Parameters for get_template()

Typed Helper Functions

Volumetric Data with get_volume_template()

Surface Data with get_surface_template()

Caching Behavior

Integration with Other neuroatlas Functions

Summary

Further Information

Getting Started: The `templateflow` Object

Fetching Templates with `get_template()`

Key Parameters for `get_template()`

Volumetric Data with `get_volume_template()`

Surface Data with `get_surface_template()`

Integration with Other `neuroatlas` Functions