Resources and caching
resources-and-caching.RmdWhy 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.a2009sAliases 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:
download_annotation("all")
download_atlas("all")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
)