Skip to contents

Why are resources downloaded separately?

R packages are not allowed to be very large, so ggbrat ships with only a few example datasets. Premade atlases, annotations, surfaces, meshes, and NIfTI files are downloaded on demand and then cached locally, ready to be used again whenever you need them.

The package includes a catalog describing the available resources:

list_resources()
list_resources(type = "atlas")

The returned citation column gives the recommended source citation for every resource. The aliases column contains familiar alternative names. Derived forms of the same atlas—such as its annotation, mesh, and premade ggbrat RDS—share the citation of the atlas from which they were made.

[!NOTE] Provenance and licensing metadata are still being audited for the resource catalog. Check the original source before redistributing a resource.

Use resource_info() when you want metadata for a particular item:

resource_info("Melbourne_S1")

Resource names can be abbreviated when the partial match is unambiguous:

download_surface("inflated")
resource_info("melbourne_s1")

Common alternative names are also understood:

load_atlas("glasser")   # HCP-MMP1
load_atlas("dk")        # aparc / Desikan-Killiany
load_atlas("destrieux") # aparc.a2009s

Aliases are matched exactly before fuzzy partial matching. Very short aliases, such as "dk", only participate in exact matching so that short searches do not produce a pile of accidental matches.

When several resources match in an interactive R session, ggbrat displays a numbered menu:

load_atlas("yeo")

In scripts, package checks, and CI, ambiguous matching stops and lists the candidates instead of waiting for input or silently choosing one.

Premade atlases

download_atlas() returns the path to a cached RDS file. load_atlas() reads the atlas directly (and downloads if necessary):

atlas_path <- download_atlas("Yeo2011_7Networks_N1000")
yeo <- load_atlas("Yeo2011_7Networks_N1000")

Builder resources

Different builder workflows need different source files:

annotation <- download_annotation("aparc")
cortical_surface <- download_surface("fsaverage_inflated")
subcortical_mesh <- download_surface("Melbourne_S1")
volume <- download_volume_atlas("Melbourne_S1")

download_annotation() and cortical download_surface() calls generally return named left/right paths. A volume resource contains its NIfTI path or paths and, where available, a lookup table.

Use "all" to download a complete category:

Cache location

Inspect the cache location with:

Set a different location before downloading:

options(ggbrat.cache_dir = "/path/to/another/cache")

Individual resources can be removed with remove_resource(). To remove the complete ggbrat resource cache, use clear_resource_cache():

remove_resource("aparc", type = "annotation")
clear_resource_cache()

The prerelease catalog is mutable. If a resource has been replaced upstream, refresh the catalog and force a fresh download:

atlas <- load_atlas(
  "Schaefer2018_1000Parcels_7Networks_order",
  refresh = TRUE,
  force = TRUE
)