| Title: | Neuroimaging Atlases and Parcellations |
|---|---|
| Description: | Provides a unified interface to access and work with various neuroimaging atlases and parcellations including Schaefer, Brainnetome, Glasser, FreeSurfer ASEG, and Olsen MTL atlases. Integrates with TemplateFlow for standardized template access and supports interactive brain surface visualisation via triangle-mesh rendering with 'ggplot2' and 'ggiraph'. |
| Authors: | Bradley Buchsbaum [aut, cre] (ORCID: <https://orcid.org/0000-0002-1108-4866>) |
| Maintainer: | Bradley Buchsbaum <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0.9000 |
| Built: | 2026-06-05 19:59:31 UTC |
| Source: | https://github.com/bbuchsbaum/neuroatlas |
A concise infix operator for filtering atlas regions by metadata attributes.
Equivalent to calling filter_atlas but allows a more fluent
pipe-friendly syntax.
atlas %where% expratlas %where% expr
atlas |
An atlas object. |
expr |
An unquoted filter expression using column names from
|
A new atlas object containing only the matching ROIs.
filter_atlas for the underlying function,
roi_metadata for available filter columns
## Not run: atlas <- get_schaefer_atlas(parcels = "200", networks = "7") # Filter to left-hemisphere Default network sub <- atlas %where% (network == "Default" & hemi == "left") # Filter by label pattern vis <- atlas %where% grepl("Vis", label) ## End(Not run)## Not run: atlas <- get_schaefer_atlas(parcels = "200", networks = "7") # Filter to left-hemisphere Default network sub <- atlas %where% (network == "Default" & hemi == "left") # Filter by label pattern vis <- atlas %where% grepl("Vis", label) ## End(Not run)
Convert Atlas Connectivity to igraph
as_igraph(x, ...) ## S3 method for class 'atlas_connectivity' as_igraph(x, weighted = TRUE, ...)as_igraph(x, ...) ## S3 method for class 'atlas_connectivity' as_igraph(x, weighted = TRUE, ...)
x |
An |
... |
Additional arguments (currently ignored). |
weighted |
Logical. If |
Dispatches to methods.
Convert an Object to 'parcel_data'
as_parcel_data(x, ...) ## S3 method for class 'parcel_data' as_parcel_data(x, ...) ## S3 method for class 'atlas' as_parcel_data( x, values = NULL, value_col = "value", atlas_id = NULL, atlas_version = NULL, atlas_space = NULL, schema_version = "1.0.0", ... ) ## Default S3 method: as_parcel_data(x, ...)as_parcel_data(x, ...) ## S3 method for class 'parcel_data' as_parcel_data(x, ...) ## S3 method for class 'atlas' as_parcel_data( x, values = NULL, value_col = "value", atlas_id = NULL, atlas_version = NULL, atlas_space = NULL, schema_version = "1.0.0", ... ) ## Default S3 method: as_parcel_data(x, ...)
x |
Object to convert. |
... |
Additional arguments passed to methods. |
values |
Optional values to attach to parcel rows. - numeric/integer vector of length 'length(x$ids)' - data frame/tibble with join column 'id' or 'label' and one or more value columns |
value_col |
Column name used when 'values' is a vector. |
atlas_id |
Optional canonical atlas id override. |
atlas_version |
Optional atlas version. |
atlas_space |
Optional atlas space/template identifier. |
schema_version |
Schema version for the returned object. |
An object of class '"parcel_data"'.
Returns a structured compatibility/alignment summary between two atlas representations based on atlas provenance metadata.
atlas_alignment(x, y)atlas_alignment(x, y)
x |
Source atlas object. |
y |
Target atlas object. |
For same family/model/representation comparisons across templates, this function consults the space transform registry when available.
A list of class '"atlas_alignment"' with fields: 'from', 'to', 'compatible', 'relation', 'method', 'confidence', 'status', 'requires_transform', and 'notes'.
ref <- new_atlas_ref( family = "schaefer", model = "Schaefer2018", representation = "volume", template_space = "MNI152NLin6Asym", coord_space = "MNI152", confidence = "high" ) a <- structure(list(atlas_ref = ref), class = c("schaefer", "atlas")) b <- structure(list(atlas_ref = ref), class = c("schaefer", "atlas")) atlas_alignment(a, b)$relationref <- new_atlas_ref( family = "schaefer", model = "Schaefer2018", representation = "volume", template_space = "MNI152NLin6Asym", coord_space = "MNI152", confidence = "high" ) a <- structure(list(atlas_ref = ref), class = c("schaefer", "atlas")) b <- structure(list(atlas_ref = ref), class = c("schaefer", "atlas")) atlas_alignment(a, b)$relation
Get Atlas Artifact Metadata
atlas_artifacts(x, ...)atlas_artifacts(x, ...)
x |
An atlas object. |
... |
Additional arguments passed to methods. |
A tibble with one row per upstream artifact used to construct the atlas.
Extracts mean time-series for each atlas region from a 4D NeuroVec and computes pairwise correlations to produce a connectivity matrix.
atlas_connectivity( data_vol, atlas, method = c("pearson", "spearman", "partial"), threshold = NULL, stat_func = mean, ... )atlas_connectivity( data_vol, atlas, method = c("pearson", "spearman", "partial"), threshold = NULL, stat_func = mean, ... )
data_vol |
A |
atlas |
An atlas object defining the parcellation. |
method |
Character string specifying the correlation method:
|
threshold |
Optional numeric value. If supplied, entries with
|
stat_func |
Function used to summarise voxel values within each
parcel (default: |
... |
Additional arguments passed to |
A symmetric matrix of class c("atlas_connectivity", "matrix")
with region labels as dimnames.
reduce_atlas for the underlying extraction,
as_igraph.atlas_connectivity for graph conversion
## Not run: atlas <- get_schaefer_atlas(parcels = "100", networks = "7") # data_vol is a 4D NeuroVec from an fMRI run conn <- atlas_connectivity(data_vol, atlas) conn_sparse <- atlas_connectivity(data_vol, atlas, threshold = 0.3) ## End(Not run)## Not run: atlas <- get_schaefer_atlas(parcels = "100", networks = "7") # data_vol is a 4D NeuroVec from an fMRI run conn <- atlas_connectivity(data_vol, atlas) conn_sparse <- atlas_connectivity(data_vol, atlas, threshold = 0.3) ## End(Not run)
Atlas Coordinate-Space Convenience Accessor
atlas_coord_space(x)atlas_coord_space(x)
x |
An atlas object. |
Character scalar (or 'NA_character_').
Atlas Family Convenience Accessor
atlas_family(x)atlas_family(x)
x |
An atlas object. |
Character scalar.
Builds a region adjacency graph from a volumetric atlas. Two parcels are considered adjacent when at least one pair of their voxels are neighbours under the chosen connectivity scheme.
atlas_graph( atlas, connectivity = c("6", "18", "26"), as = c("matrix", "igraph", "tibble"), include_weight = TRUE )atlas_graph( atlas, connectivity = c("6", "18", "26"), as = c("matrix", "igraph", "tibble"), include_weight = TRUE )
atlas |
An atlas object (must contain |
connectivity |
Character. Neighbourhood type: |
as |
Character. Output format: |
include_weight |
Logical. If |
Depending on as:
A symmetric integer matrix of dimension K x K with row/column names set to region labels.
An undirected igraph graph (requires the igraph package).
A data.frame (tibble if available) with columns
from, to, and weight.
## Not run: atlas <- get_schaefer_atlas(100) adj <- atlas_graph(atlas) adj_b <- atlas_graph(atlas, include_weight = FALSE) el <- atlas_graph(atlas, as = "tibble") ## End(Not run)## Not run: atlas <- get_schaefer_atlas(100) adj <- atlas_graph(atlas) adj_b <- atlas_graph(atlas, include_weight = FALSE) el <- atlas_graph(atlas, as = "tibble") ## End(Not run)
Extracts hierarchical level information from an atlas, describing how parcels map to higher-level groupings (networks, hemispheres).
atlas_hierarchy(atlas)atlas_hierarchy(atlas)
atlas |
An atlas object. |
A list of class "atlas_hierarchy" with components:
Character vector of hierarchy level names, from finest
to coarsest (e.g., c("parcel", "network", "hemisphere")).
Named list of named character vectors. Each element
maps parcel labels to the corresponding grouping at that level.
Names of the list correspond to levels[-1] (all levels
above parcel).
## Not run: atlas <- get_schaefer_atlas(parcels = "200", networks = "7") h <- atlas_hierarchy(atlas) h$levels # [1] "parcel" "network" "hemisphere" h$mappings$network[1:5] ## End(Not run)## Not run: atlas <- get_schaefer_atlas(parcels = "200", networks = "7") h <- atlas_hierarchy(atlas) h$levels # [1] "parcel" "network" "hemisphere" h$mappings$network[1:5] ## End(Not run)
Get Atlas Processing History
atlas_history(x, ...)atlas_history(x, ...)
x |
An atlas object. |
... |
Additional arguments passed to methods. |
A tibble with one row per processing step tracked by
neuroatlas.
Computes spatial overlap between regions of two atlases using Dice and/or Jaccard similarity coefficients. This is useful for comparing parcellations, assessing correspondence between atlases, or mapping regions from one atlas to another.
atlas_overlap(atlas1, atlas2, metrics = c("dice", "jaccard"), min_overlap = 0)atlas_overlap(atlas1, atlas2, metrics = c("dice", "jaccard"), min_overlap = 0)
atlas1 |
An atlas object (with |
atlas2 |
An atlas object (with |
metrics |
Character vector of overlap metrics to compute. One or more of
|
min_overlap |
Integer. Minimum number of overlapping voxels for a pair to be included in the results. Default is 0 (include all pairs with any overlap). |
A tibble with columns:
Integer region ID from atlas1
Character label from atlas1
Integer region ID from atlas2
Character label from atlas2
Dice similarity coefficient (if requested)
Jaccard similarity coefficient (if requested)
Number of overlapping voxels
Total voxels in the atlas1 region
Total voxels in the atlas2 region
Rows are sorted by Dice coefficient descending (or Jaccard if Dice was not requested).
## Not run: atlas_a <- get_schaefer_atlas(parcels = "100", networks = "7") atlas_b <- get_schaefer_atlas(parcels = "200", networks = "7") overlap <- atlas_overlap(atlas_a, atlas_b) head(overlap) ## End(Not run)## Not run: atlas_a <- get_schaefer_atlas(parcels = "100", networks = "7") atlas_b <- get_schaefer_atlas(parcels = "200", networks = "7") overlap <- atlas_overlap(atlas_a, atlas_b) head(overlap) ## End(Not run)
Access structured provenance metadata for atlas objects, including the canonical atlas identity, upstream artifacts, and processing history.
atlas_provenance(x, ...) ## S3 method for class 'atlas' atlas_provenance(x, ...) ## Default S3 method: atlas_provenance(x, ...) ## S3 method for class 'atlas' atlas_artifacts(x, ...) ## Default S3 method: atlas_artifacts(x, ...) ## S3 method for class 'atlas' atlas_history(x, ...) ## Default S3 method: atlas_history(x, ...)atlas_provenance(x, ...) ## S3 method for class 'atlas' atlas_provenance(x, ...) ## Default S3 method: atlas_provenance(x, ...) ## S3 method for class 'atlas' atlas_artifacts(x, ...) ## Default S3 method: atlas_artifacts(x, ...) ## S3 method for class 'atlas' atlas_history(x, ...) ## Default S3 method: atlas_history(x, ...)
x |
An atlas object. |
... |
Additional arguments passed to methods. |
A list of class '"atlas_provenance"' with fields:
Canonical atlas_ref() identity metadata.
A tibble describing upstream files/resources.
A tibble describing processing steps applied in
neuroatlas.
Returns the canonical atlas reference metadata for an atlas object.
atlas_ref(x, ...) ## S3 method for class 'atlas' atlas_ref(x, ...) ## Default S3 method: atlas_ref(x, ...)atlas_ref(x, ...) ## S3 method for class 'atlas' atlas_ref(x, ...) ## Default S3 method: atlas_ref(x, ...)
x |
An atlas object. |
... |
Additional arguments passed to methods. |
An object of class '"atlas_ref"'.
Bridge between an atlas object and the roi_colors_*() family of
colour algorithms. Extracts ROI centroids, assembles a metadata tibble, and
dispatches to the requested algorithm.
atlas_roi_colors(atlas, method = "rule_hcl", ...)atlas_roi_colors(atlas, method = "rule_hcl", ...)
atlas |
An S3 atlas object (any type: Schaefer, ASEG, Olsen, etc.). |
method |
One of |
... |
Additional arguments passed to the underlying
|
When method is a character vector of hex colours (named by region ID
or in the same order as atlas$ids), no colour algorithm is invoked
and the colours are returned directly.
A tibble with columns id (integer) and
color (hex string), one row per region in the atlas.
atlas <- get_aseg_atlas() cols <- atlas_roi_colors(atlas) head(cols)atlas <- get_aseg_atlas() cols <- atlas_roi_colors(atlas) head(cols)
Atlas Template-Space Convenience Accessor
atlas_space(x)atlas_space(x)
x |
An atlas object. |
Character scalar (or 'NA_character_').
Returns currently known cross-representation alignment routes and their implementation status.
atlas_transform_manifest(scope = c("alignment", "space"))atlas_transform_manifest(scope = c("alignment", "space"))
scope |
Manifest scope. '"alignment"' returns family/model alignment routes. '"space"' returns template/space transform routes. |
A data frame manifest. For 'scope = "alignment"' this is a tibble of atlas-family representation routes. For 'scope = "space"' this is the space transform registry returned by [space_transform_manifest()].
# Atlas-family alignment routes atlas_transform_manifest("alignment") # Space-to-space routes atlas_transform_manifest("space")# Atlas-family alignment routes atlas_transform_manifest("alignment") # Space-to-space routes atlas_transform_manifest("space")
Computes a direct or two-hop transform plan between spaces using the packaged transform registry.
atlas_transform_plan( from_space, to_space, data_type = c("parcel", "vertex", "voxel"), mode = c("auto", "strict") )atlas_transform_plan( from_space, to_space, data_type = c("parcel", "vertex", "voxel"), mode = c("auto", "strict") )
from_space |
Source space identifier. |
to_space |
Target space identifier. |
data_type |
Data type being transformed ('"parcel"', '"vertex"', '"voxel"'). Used for advisory warnings. |
mode |
Planning mode. '"auto"' returns 'NULL' if no route exists, '"strict"' errors. |
Space identifiers are normalized internally, so aliases such as '"fslr32k"' are accepted.
A list of class '"atlas_transform_plan"' with fields: 'from_space', 'to_space', 'steps', 'n_steps', 'status', 'confidence', and 'warnings'.
'steps' is a data frame with one row per transform step and registry columns. In 'mode = "auto"', returns 'NULL' (with warning) if no route exists.
# Direct route p1 <- atlas_transform_plan("MNI305", "MNI152") # Alias normalization + planned route p2 <- atlas_transform_plan("fsaverage", "fslr32k") p2$status# Direct route p1 <- atlas_transform_plan("MNI305", "MNI152") # Alias normalization + planned route p2 <- atlas_transform_plan("fsaverage", "fslr32k") p2$status
Applies reduce_atlas to multiple input volumes (or file
paths) and combines the results into a single tibble with a
subject column identifying each input.
batch_reduce( inputs, atlas, stat_func = mean, ..., format = "long", parallel = FALSE, .progress = TRUE )batch_reduce( inputs, atlas, stat_func = mean, ..., format = "long", parallel = FALSE, .progress = TRUE )
inputs |
A named list of inputs. Each element can be:
If unnamed, subjects are auto-named |
atlas |
An atlas object. |
stat_func |
Function to apply within each ROI (default: |
... |
Additional arguments passed to |
format |
Character, output format passed to |
parallel |
Logical. If |
.progress |
Logical. If |
A tibble with a subject column prepended to the
reduce_atlas output for each input.
reduce_atlas for single-volume extraction
## Not run: # With NeuroVol objects vols <- list(sub01 = vol1, sub02 = vol2, sub03 = vol3) results <- batch_reduce(vols, atlas, mean) # With file paths files <- list(sub01 = "path/to/sub01.nii.gz", sub02 = "path/to/sub02.nii.gz") results <- batch_reduce(files, atlas, mean, parallel = TRUE) ## End(Not run)## Not run: # With NeuroVol objects vols <- list(sub01 = vol1, sub02 = vol2, sub03 = vol3) results <- batch_reduce(vols, atlas, mean) # With file paths files <- list(sub01 = "path/to/sub01.nii.gz", sub02 = "path/to/sub02.nii.gz") results <- batch_reduce(files, atlas, mean, parallel = TRUE) ## End(Not run)
Downloads (if needed) and returns the Brainnetome 246-region label table used
by get_brainnetome_atlas().
brainnetome_labels(use_cache = TRUE)brainnetome_labels(use_cache = TRUE)
use_cache |
Logical. Use cached Brainnetome files when available. |
Brainnetome assets are downloaded on demand and cached locally. They are not bundled with neuroatlas; use is governed by the legal agreement on the Brainnetome download page.
A tibble with one row per parcel and columns for parcel id, label, hemisphere, lobe/gyrus, Yeo network membership, RGB colour, and cytoarchitectonic description.
https://atlas.brainnetome.org/download.html
Projects surface atlas geometry into 2D polygon panels for each hemisphere and view. Results are memoised so repeated calls with identical arguments return cached data.
build_brain_polygon_data(surfatlas, views, surface, projection_smooth = 0L)build_brain_polygon_data(surfatlas, views, surface, projection_smooth = 0L)
surfatlas |
A surfatlas object (e.g. from |
views |
Character vector of views to render
(e.g. |
surface |
Character: surface type ( |
projection_smooth |
Integer: number of Laplacian smoothing iterations
on projected coordinates (default |
A list with two elements:
polygonsTibble of 2D projected polygon vertices with
columns x, y, poly_id, parcel_id, label, hemi, view, panel.
boundariesTibble of boundary edges with columns
x, y, xend, yend, panel.
Compute sign-aware volumetric connected components from a statistic map, annotate them with atlas parcels, and extract cluster-level 4D signal summaries aligned to sample rows.
build_cluster_explorer_data( data_source, atlas, stat_map, sample_table = NULL, threshold = 3, min_cluster_size = 20, connectivity = c("26-connect", "18-connect", "6-connect"), tail = c("two_sided", "positive", "negative"), signal_fun = mean, signal_fun_args = list(na.rm = TRUE), series_fun = NULL, prefetch = TRUE, prefetch_max_clusters = Inf, prefetch_max_voxels = Inf, series_cache_env = NULL )build_cluster_explorer_data( data_source, atlas, stat_map, sample_table = NULL, threshold = 3, min_cluster_size = 20, connectivity = c("26-connect", "18-connect", "6-connect"), tail = c("two_sided", "positive", "negative"), signal_fun = mean, signal_fun_args = list(na.rm = TRUE), series_fun = NULL, prefetch = TRUE, prefetch_max_clusters = Inf, prefetch_max_voxels = Inf, series_cache_env = NULL )
data_source |
A sample-wise data source supporting
|
atlas |
A volumetric |
stat_map |
A |
sample_table |
Optional data frame with one row per sample. If
|
threshold |
Numeric threshold used for cluster formation. |
min_cluster_size |
Minimum number of voxels required to keep a cluster. |
connectivity |
Connectivity passed to |
tail |
Clustering mode: |
signal_fun |
Function used to summarize cluster signal per sample. |
signal_fun_args |
Named list of additional arguments passed to
|
series_fun |
Optional function override for extracting voxel-wise sample
series. Must accept |
prefetch |
Logical; if |
prefetch_max_clusters |
Maximum clusters allowed for eager prefetch. Prefetch is skipped when exceeded. |
prefetch_max_voxels |
Maximum total cluster voxels allowed for eager prefetch. Prefetch is skipped when exceeded. |
series_cache_env |
Optional environment used to memoize voxel-coordinates-to-series extraction across cluster computations. |
A list with:
cluster_tableCluster summary tibble.
cluster_parcelsCluster-parcel overlap tibble.
cluster_tsSample-level cluster signal tibble.
cluster_voxelsNamed list of voxel coordinate matrices by cluster ID.
cluster_indexA NeuroVol of global cluster IDs.
sample_tableNormalized sample table with
.sample_index.
prefetch_infoList describing whether eager signal prefetch was requested/applied and the effective guard thresholds.
Constructs a sparse, symmetric edge list describing which ROIs are likely to collide visually across common slice views. The resulting tibble records the ROI indices, names, and a normalised conflict weight in \[0, 1\].
build_conflict_edges( rois, id_col = "roi", xyz_cols = c("x", "y", "z"), k = 12, sigma_3d = NULL, views = c("axial", "coronal", "sagittal"), view_weights = c(axial = 1, coronal = 1, sagittal = 1), sigma_xy = 25, sigma_slice = 10, hemi_col = NULL, cross_hemi_factor = 0.85, network_col = NULL, diff_network_factor = 1.15, weight_transform = NULL )build_conflict_edges( rois, id_col = "roi", xyz_cols = c("x", "y", "z"), k = 12, sigma_3d = NULL, views = c("axial", "coronal", "sagittal"), view_weights = c(axial = 1, coronal = 1, sagittal = 1), sigma_xy = 25, sigma_slice = 10, hemi_col = NULL, cross_hemi_factor = 0.85, network_col = NULL, diff_network_factor = 1.15, weight_transform = NULL )
rois |
Tibble with ROI metadata. Must contain 'id_col' and the three columns listed in 'xyz_cols'. |
id_col |
Column containing ROI IDs. |
xyz_cols |
Character vector of length three giving the coordinates to use for distance calculations. |
k |
Number of nearest neighbours to evaluate when forming edges. |
sigma_3d |
Spatial decay parameter in millimetres. Defaults to the median neighbour distance. |
views |
Character vector of anatomical views to consider. Supported: '"axial"', '"coronal"', and '"sagittal"'. |
view_weights |
Named numeric vector of weights for the supplied views. |
sigma_xy |
In-plane decay (mm) for slice visibility. |
sigma_slice |
Through-slice decay (mm) for slice visibility. |
hemi_col |
Optional hemisphere column to down-weight cross-hemisphere conflicts. |
cross_hemi_factor |
Multiplicative factor (< 1) applied to conflicts involving opposite hemispheres. |
network_col |
Optional network column to up-weight cross-network conflicts. |
diff_network_factor |
Multiplicative factor (> 1) applied to conflicts involving different networks. |
weight_transform |
Optional function 'function(edges, rois)' that can modify the weights before returning. |
Tibble with columns 'from_idx', 'to_idx', 'from', 'to', and 'w'.
rois <- data.frame( roi = 1:6, x = c(10, 12, 50, 52, 10, 50), y = c(20, 22, 20, 22, 60, 60), z = c(30, 32, 30, 32, 30, 30) ) edges <- build_conflict_edges(rois, xyz_cols = c("x", "y", "z"))rois <- data.frame( roi = 1:6, x = c(10, 12, 50, 52, 10, 50), y = c(20, 22, 20, 22, 60, 60), z = c(30, 32, 30, 32, 30, 30) ) edges <- build_conflict_edges(rois, xyz_cols = c("x", "y", "z"))
Build 2D projected polygon/boundary data from a surfatlas for custom
rendering workflows. This exposes the mesh-projection data pipeline used
internally by plot_brain().
build_surface_polygon_data( surfatlas, views = c("lateral", "medial"), surface = "inflated", merged = TRUE, projection_smooth = 0L, use_cache = TRUE )build_surface_polygon_data( surfatlas, views = c("lateral", "medial"), surface = "inflated", merged = TRUE, projection_smooth = 0L, use_cache = TRUE )
surfatlas |
A surface atlas object inheriting from class
|
views |
Character vector of views to include. Any combination of
|
surface |
Character scalar identifying the surface type label. |
merged |
Logical. If |
projection_smooth |
Non-negative integer controlling Laplacian-like
smoothing iterations applied to projected vertex coordinates before
polygon and boundary construction. |
use_cache |
Logical. If |
A list with components:
polygonsA tibble of projected polygon vertices.
boundariesA tibble of projected boundary segments.
Checks whether the TemplateFlow R package is installed and provides cache information.
check_templateflow()check_templateflow()
Invisible NULL. Prints status information to the console.
check_templateflow()check_templateflow()
Removes cached files and clears in-memory memoisation.
clear_templateflow_cache(confirm = TRUE)clear_templateflow_cache(confirm = TRUE)
confirm |
Logical. If 'TRUE' (the default), asks for interactive confirmation. |
Invisibly returns 'TRUE' if the cache was cleared, 'FALSE' if aborted.
## Not run: clear_templateflow_cache() clear_templateflow_cache(confirm = FALSE) ## End(Not run)## Not run: clear_templateflow_cache() clear_templateflow_cache(confirm = FALSE) ## End(Not run)
Interactive explorer linking a cluster summary table, parcel brain map, and
design-aware signal plots. Clusters are formed volumetrically from
stat_map; visualization is parcel-level on surfatlas.
cluster_explorer( data_source = NULL, atlas = NULL, stat_map = NULL, surfatlas = NULL, sample_table = NULL, design = NULL, threshold = 3, min_cluster_size = 20, connectivity = c("26-connect", "18-connect", "6-connect"), tail = c("two_sided", "positive", "negative"), series_fun = NULL, overlay_space = NULL, overlay_density = NULL, overlay_resolution = NULL, overlay_fun = c("avg", "nn", "mode"), overlay_sampling = c("midpoint", "normal_line", "thickness"), prefetch = TRUE, prefetch_max_clusters = 200, prefetch_max_voxels = 1e+05, palette = "vik", selection_engine = c("cluster", "parcel", "sphere", "custom"), parcel_ids = NULL, sphere_centers = NULL, sphere_radius = 6, sphere_units = c("mm", "voxels"), sphere_combine = c("separate", "union"), selection_provider = NULL, analysis_plugins = NULL, default_analysis_plugin = "none" )cluster_explorer( data_source = NULL, atlas = NULL, stat_map = NULL, surfatlas = NULL, sample_table = NULL, design = NULL, threshold = 3, min_cluster_size = 20, connectivity = c("26-connect", "18-connect", "6-connect"), tail = c("two_sided", "positive", "negative"), series_fun = NULL, overlay_space = NULL, overlay_density = NULL, overlay_resolution = NULL, overlay_fun = c("avg", "nn", "mode"), overlay_sampling = c("midpoint", "normal_line", "thickness"), prefetch = TRUE, prefetch_max_clusters = 200, prefetch_max_voxels = 1e+05, palette = "vik", selection_engine = c("cluster", "parcel", "sphere", "custom"), parcel_ids = NULL, sphere_centers = NULL, sphere_radius = 6, sphere_units = c("mm", "voxels"), sphere_combine = c("separate", "union"), selection_provider = NULL, analysis_plugins = NULL, default_analysis_plugin = "none" )
data_source |
A sample-wise data source supporting
|
atlas |
A volumetric |
stat_map |
A |
surfatlas |
A surface atlas object used by |
sample_table |
Optional data frame with one row per sample. If
|
design |
Optional design table (one row per sample). When provided, it
is column-bound to |
threshold |
Numeric threshold used for cluster formation. |
min_cluster_size |
Minimum number of voxels required to keep a cluster. |
connectivity |
Connectivity passed to |
tail |
Clustering mode: |
series_fun |
Optional function override for extracting voxel-wise sample
series. Must accept |
overlay_space |
Optional surface space override used to fetch white/pial
meshes for volumetric cluster projection. Defaults to
|
overlay_density |
Optional TemplateFlow density override for overlay surface loading. |
overlay_resolution |
Optional TemplateFlow resolution override for overlay surface loading. |
overlay_fun |
Reduction used by |
overlay_sampling |
Sampling strategy for |
prefetch |
Logical default for eager cluster signal prefetch. |
prefetch_max_clusters |
Default max cluster count allowed for prefetch. |
prefetch_max_voxels |
Default max total cluster voxels allowed for prefetch. |
palette |
Continuous palette passed to |
selection_engine |
Selection backend. |
parcel_ids |
Optional parcel ids used when
|
sphere_centers |
Optional sphere centers used when
|
sphere_radius |
Sphere radius used when
|
sphere_units |
Units for |
sphere_combine |
How to combine multiple spheres:
|
selection_provider |
Optional function used when
|
analysis_plugins |
Optional list of analysis plugin definitions. Plugins can transform extracted time-series/design data before plotting. |
default_analysis_plugin |
Optional default plugin id. Defaults to
|
Calling cluster_explorer() with no arguments launches a synthetic demo
dataset so the UI can be explored immediately.
A shiny.appobj.
Character constants for standard neuroimaging coordinate spaces.
coord_spacescoord_spaces
A named list with the following elements:
FreeSurfer/Talairach space (fsaverage native)
ICBM 2009c space (common fMRI template)
Native scanner space (subject-specific)
Unknown or unspecified space
coord_spaces$MNI305 coord_spaces$MNI152coord_spaces$MNI305 coord_spaces$MNI152
Functions and constants for transforming coordinates between standard neuroimaging coordinate spaces, particularly MNI305 (fsaverage) and MNI152 (common fMRI template space).
FreeSurfer's fsaverage surfaces are defined in MNI305 (Talairach-like) space, while most modern fMRI pipelines output data in MNI152 space. The difference is approximately 4mm, which matters for accurate volume-to-surface projections.
FreeSurfer/Talairach space. Native space for fsaverage, fsaverage5, and fsaverage6 surfaces. Based on 305 subjects with linear registration to approximate Talairach space.
ICBM 2009c space. The de facto standard for volumetric fMRI analysis. Used by FSL, SPM, fMRIPrep, and TemplateFlow's MNI152NLin2009cAsym template.
FreeSurfer CoordinateSystems documentation: https://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems
Wu et al. (2018). Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate systems. Human Brain Mapping, 39(9), 3793-3808. doi:10.1002/hbm.24213
**DEPRECATED:** TemplateFlow is now accessed via the pure R 'templateflow' package. No initialization is needed. Use [get_template()], [tflow_spaces()], and [tflow_files()] directly.
create_templateflow(cache_dir = NULL, verbosity = 0, default_template = NULL)create_templateflow(cache_dir = NULL, verbosity = 0, default_template = NULL)
cache_dir |
Ignored. Kept for backward compatibility. |
verbosity |
Ignored. Kept for backward compatibility. |
default_template |
Ignored. Kept for backward compatibility. |
An S3 object of class templateflow (deprecated stub).
## Not run: # Deprecated. Use get_template(), tflow_spaces(), etc. directly. ## End(Not run)## Not run: # Deprecated. Use get_template(), tflow_spaces(), etc. directly. ## End(Not run)
Expands the boundaries of brain atlas parcels by dilating them into adjacent unassigned voxels within a specified mask. This is useful for filling small gaps between parcels or extending parcels into neighboring regions.
dilate_atlas(atlas, mask, radius = 4, maxn = 50)dilate_atlas(atlas, mask, radius = 4, maxn = 50)
atlas |
An object of class "atlas" containing the parcellation to be dilated |
mask |
A binary mask (NeuroVol object) specifying valid voxels for dilation. Dilation will only occur within non-zero mask values. May also be a TemplateFlow space identifier (string) or list of 'get_template()' arguments, which will be resolved to a NeuroVol via '.resolve_template_input()'. |
radius |
Numeric. The maximum distance (in voxels) to search for neighboring parcels when dilating. Default: 4 |
maxn |
Integer. Maximum number of neighboring voxels to consider when determining parcel assignment. Default: 50 |
The dilation process:
Identifies unassigned voxels within the mask that are adjacent to existing parcels
For each unassigned voxel, finds nearby assigned voxels within the specified radius
Assigns the unassigned voxel to the nearest parcel
Respects mask boundaries to prevent dilation into unwanted regions
The function uses a k-d tree implementation (via Rnanoflann) for efficient nearest neighbor searches in 3D space.
A ClusteredNeuroVol object containing the dilated parcellation.
The object maintains the original label mappings but may include additional
voxels in existing parcels.
The algorithm uses efficient k-d tree based nearest neighbor searches for spatial queries in 3D voxel space.
get_template_brainmask for creating appropriate masks from TemplateFlow
## Not run: # Load an atlas atlas <- get_aseg_atlas() # Create or load a brain mask mask <- get_template_brainmask() # Dilate the atlas within the mask dilated <- dilate_atlas(atlas, mask, radius = 4) # More conservative dilation with fewer neighbors dilated_conservative <- dilate_atlas(atlas, mask, radius = 2, maxn = 20) ## End(Not run)## Not run: # Load an atlas atlas <- get_aseg_atlas() # Create or load a brain mask mask <- get_template_brainmask() # Dilate the atlas within the mask dilated <- dilate_atlas(atlas, mask, radius = 4) # More conservative dilation with fewer neighbors dilated_conservative <- dilate_atlas(atlas, mask, radius = 2, maxn = 20) ## End(Not run)
Subsets an atlas object to include only ROIs matching specified criteria.
Uses non-standard evaluation (NSE) similar to dplyr::filter().
filter_atlas(x, ..., .dots = NULL) ## S3 method for class 'atlas' filter_atlas(x, ..., .dots = NULL)filter_atlas(x, ..., .dots = NULL) ## S3 method for class 'atlas' filter_atlas(x, ..., .dots = NULL)
x |
An atlas object |
... |
Filter expressions using column names from |
.dots |
A list of quosures for standard evaluation (advanced use) |
The filter operation creates a new atlas containing only the specified ROIs. For volume atlases, voxels belonging to excluded ROIs are set to zero. ROI IDs are preserved (not renumbered) to maintain consistency with the original atlas labeling.
A new atlas object of the same class containing only the matching ROIs.
The returned atlas has updated ids, labels, hemi,
orig_labels, cmap, network (if present), and
roi_metadata fields. The underlying volume/surface data is also subset.
roi_metadata for viewing available filter columns,
roi_attributes for listing available attributes,
get_roi for extracting ROI data
## Not run: # Filter Schaefer atlas to left hemisphere visual network atlas <- get_schaefer_atlas(parcels = "200", networks = "7") left_vis <- filter_atlas(atlas, hemi == "left", network == "Vis") # Filter ASEG to left hemisphere structures aseg <- get_aseg_atlas() left_aseg <- filter_atlas(aseg, hemi == "left") # Filter by label pattern hippo <- filter_atlas(aseg, grepl("Hippocampus", label)) ## End(Not run)## Not run: # Filter Schaefer atlas to left hemisphere visual network atlas <- get_schaefer_atlas(parcels = "200", networks = "7") left_vis <- filter_atlas(atlas, hemi == "left", network == "Vis") # Filter ASEG to left hemisphere structures aseg <- get_aseg_atlas() left_aseg <- filter_atlas(aseg, hemi == "left") # Filter by label pattern hippo <- filter_atlas(aseg, grepl("Hippocampus", label)) ## End(Not run)
A list including left and right hemispheres for the orig, white, inflated, and pial surfaces.
data(fsaverage)data(fsaverage)
A named list with elements lh and rh, each containing
surface geometry objects for orig, white, inflated, and pial surfaces.
data(fsaverage) names(fsaverage)data(fsaverage) names(fsaverage)
Loads and returns the FreeSurfer subcortical segmentation (ASEG) atlas, which provides probabilistic labels for key subcortical structures in the brain. The atlas includes bilateral structures such as the thalamus, caudate, putamen, and limbic regions, as well as midline structures like the brainstem.
get_aseg_atlas(outspace = NULL)get_aseg_atlas(outspace = NULL)
outspace |
Optional |
The ASEG atlas is derived from FreeSurfer's automatic subcortical segmentation algorithm and has been transformed into standard space. Each voxel contains an integer ID corresponding to a specific anatomical structure. The atlas includes major subcortical structures for both hemispheres:
Bilateral deep gray structures (thalamus, caudate, putamen, pallidum)
Limbic structures (hippocampus, amygdala)
Ventral structures (nucleus accumbens, ventral diencephalon)
Midline structures (brainstem)
A list with classes 'aseg' and 'atlas' containing:
A NeuroVol object containing the 3D volume of atlas labels
A data frame with RGB color specifications for each region
Integer vector of region IDs present in the atlas
Character vector of anatomical labels corresponding to each ID
Character vector indicating hemisphere ('left', 'right', or NA) for each region
Fischl, B., et al. (2002). Whole brain segmentation: automated labeling of neuroanatomical structures in the human brain. Neuron, 33(3), 341-355.
map_atlas for mapping values onto atlas regions
get_roi for extracting specific regions of interest
## Not run: # Load the atlas in native space aseg <- get_aseg_atlas() # View the available region labels aseg$labels # Get the unique region IDs aseg$ids ## End(Not run)## Not run: # Load the atlas in native space aseg <- get_aseg_atlas() # View the available region labels aseg$labels # Get the unique region IDs aseg$ids ## End(Not run)
Dispatches to the loader registered for 'name', forwarding '...' to it. This is a thin convenience wrapper: it lets callers request an atlas by string id (e.g. '"schaefer"', '"glasser"', '"aseg"') without having to know which specific 'get_*_atlas()' function to call. Aliases registered alongside the canonical id are matched case/punctuation-insensitively.
get_atlas(name, ...)get_atlas(name, ...)
name |
Atlas id or alias; see [list_atlases()] for available choices. |
... |
Arguments forwarded to the registered loader function. |
The loaded atlas object (class depends on the loader).
[list_atlases()].
## Not run: # Equivalent to get_aseg_atlas() aseg <- get_atlas("aseg") # Equivalent to get_schaefer_atlas(parcels = "100", networks = "7") schaef <- get_atlas("schaefer", parcels = "100", networks = "7") ## End(Not run)## Not run: # Equivalent to get_aseg_atlas() aseg <- get_atlas("aseg") # Equivalent to get_schaefer_atlas(parcels = "100", networks = "7") schaef <- get_atlas("schaefer", parcels = "100", networks = "7") ## End(Not run)
Downloads and loads the Brainnetome Atlas 246-region MNI152 1 mm labelmap. Files are cached under the neuroatlas user cache directory rather than bundled with the package.
get_brainnetome_atlas(outspace = NULL, smooth = FALSE, use_cache = TRUE)get_brainnetome_atlas(outspace = NULL, smooth = FALSE, use_cache = TRUE)
outspace |
Optional |
smooth |
Logical. Whether to smooth parcel boundaries when resampling. |
use_cache |
Logical. Use cached Brainnetome files when available. |
The Brainnetome download page describes non-commercial use and attribution
terms. This loader keeps the data outside the package source and records the
upstream assets in atlas_artifacts().
A list with classes c("brainnetome", "volatlas", "atlas").
https://atlas.brainnetome.org/download.html
Fan, L. et al. (2016). The Human Brainnetome Atlas: A New Brain Atlas Based on Connectional Architecture. Cerebral Cortex, 26(8), 3508-3526.
Load FSL-distributed atlases into the standard neuroatlas 'atlas' object shape. FSL atlases are described by XML files under '$FSLDIR/data/atlases'; many probabilistic atlases provide both a 4D probability image and a 3D maximum-probability summary image. The summary image labels are offset by one relative to XML/probability-volume indices, so 'get_fsl_atlas()' applies that correction when loading max-probability summaries.
get_fsl_atlas( name, fsl_dir = Sys.getenv("FSLDIR"), resolution = NULL, image = c("summary", "probability"), outspace = NULL, path_only = FALSE )get_fsl_atlas( name, fsl_dir = Sys.getenv("FSLDIR"), resolution = NULL, image = c("summary", "probability"), outspace = NULL, path_only = FALSE )
name |
Atlas identifier, FSL XML path, or known alias. Known aliases include '"harvard_oxford_cortical"', '"harvard_oxford_subcortical"', '"harvard_oxford_cortical_subcortical"', and '"julich"'. |
fsl_dir |
FSL installation directory. Defaults to 'Sys.getenv("FSLDIR")'. 'get_julich_brain_atlas()' downloads an FSL-style Julich-Brain cache when this is empty and 'download = TRUE'. |
resolution |
Preferred image resolution, e.g. '"1mm"' or '"2mm"'. If 'NULL', the first image entry in the XML file is used. |
image |
One of '"summary"' or '"probability"'. 'neuroatlas' atlas objects are discrete parcellations, so '"summary"' is the default. '"probability"' currently returns paths and metadata when 'path_only = TRUE'; loading 4D probabilistic images as atlas objects is intentionally deferred. |
outspace |
Optional 'NeuroSpace' to resample the discrete atlas into. |
path_only |
Logical; return resolved paths and parsed metadata without loading image data. |
An 'atlas' object, or a path/metadata list when 'path_only = TRUE'.
'r lifecycle::badge("deprecated")'
This function has been deprecated in favour of the native
plot_brain() renderer.
Use schaefer_surf() to obtain a surface atlas and
plot_brain() for visualisation.
get_ggseg_atlas(atlas)get_ggseg_atlas(atlas)
atlas |
An atlas object containing Schaefer parcellation information. |
A ggseg brain atlas object for visualization (if ggsegSchaefer is installed).
# Deprecated — use plot_brain(schaefer_surf(200, 17)) instead# Deprecated — use plot_brain(schaefer_surf(200, 17)) instead
Retrieves and loads a volumetric representation of the Glasser/HCP-MMP 1.0 cortical parcellation atlas.
get_glasser_atlas(outspace = NULL, source = c("xcpengine", "mni2009c"))get_glasser_atlas(outspace = NULL, source = c("xcpengine", "mni2009c"))
outspace |
Optional |
source |
Volume source to use. One of |
The Glasser atlas divides each hemisphere into 180 areas (360 total) based on cortical architecture, function, connectivity, and topography.
Supported sources:
"xcpengine" (default): xcpEngine Glasser360 volume
(glasser360MNI.nii.gz) with stable runtime availability but less
explicit template provenance.
"mni2009c": MNI152NLin2009cAsym-provenance volume file
(MMP_in_MNI_corr.nii.gz). This source is attempted only when
requested.
If source = "mni2009c" is unavailable at runtime, the loader
automatically falls back to "xcpengine" and marks confidence as
"uncertain". In practice, some GitHub mirrors for this source may
serve a small git-annex pointer stub rather than the real NIfTI payload.
Region labels are read from the xcpEngine node-name table to provide stable parcel naming across sources.
A list with class 'glasser' and 'atlas' containing:
Character string "Glasser360"
A ClusteredNeuroVol object containing the parcellation
Data frame with RGB color specifications for each region
Integer vector of region IDs (1:360)
Character vector of anatomical labels
Character vector indicating hemisphere ('left' or 'right')
Source-specific links are recorded in atlas_ref(atlas)$provenance.
Glasser, M. F., et al. (2016). A multi-modal parcellation of human cerebral cortex. Nature, 536(7615), 171-178.
## Not run: # Load atlas in native space atlas <- get_glasser_atlas() # View region labels head(atlas$labels) # Check number of regions per hemisphere table(atlas$hemi) ## End(Not run)## Not run: # Load atlas in native space atlas <- get_glasser_atlas() # View region labels head(atlas$labels) # Check number of regions per hemisphere table(atlas$hemi) ## End(Not run)
Loads Harvard-Oxford cortical, subcortical, or combined cortical/subcortical parcellations. By default this uses TemplateFlow, which does not require a local FSL installation. Set 'source = "fsl"' to read from '$FSLDIR'.
get_harvard_oxford_atlas( type = c("cortical", "subcortical", "cortical_subcortical"), threshold = c(25, 0, 50), template_space = "MNI152NLin6Asym", resolution = "01", source = c("templateflow", "fsl"), outspace = NULL, use_cache = TRUE, path_only = FALSE ) get_harvard_oxford_cortical_atlas(...) get_harvard_oxford_subcortical_atlas(...) get_harvard_oxford_cortical_subcortical_atlas(...)get_harvard_oxford_atlas( type = c("cortical", "subcortical", "cortical_subcortical"), threshold = c(25, 0, 50), template_space = "MNI152NLin6Asym", resolution = "01", source = c("templateflow", "fsl"), outspace = NULL, use_cache = TRUE, path_only = FALSE ) get_harvard_oxford_cortical_atlas(...) get_harvard_oxford_subcortical_atlas(...) get_harvard_oxford_cortical_subcortical_atlas(...)
type |
One of '"cortical"', '"subcortical"', or '"cortical_subcortical"'. |
threshold |
Maximum-probability threshold, one of '0', '25', or '50'. |
template_space |
TemplateFlow space. |
resolution |
TemplateFlow/FSL resolution. TemplateFlow accepts '"01"' or '"02"'; FSL accepts values such as '"1mm"' and '"2mm"'. |
source |
'"templateflow"' or '"fsl"'. |
outspace |
Optional 'NeuroSpace' to resample the atlas into. |
use_cache |
Passed through to 'get_template()'. |
path_only |
Return resolved paths and metadata without loading image data. |
download |
Logical; for 'get_julich_brain_atlas()', download the Julich-Brain atlas archive into the neuroatlas cache when 'fsl_dir' is unset. |
An 'atlas' object, or path metadata when 'path_only = TRUE'.
Creates a hippocampus-specific atlas from the Olsen MTL atlas, with optional anterior-posterior subdivisions.
get_hipp_atlas(outspace = NULL, apsections = 1)get_hipp_atlas(outspace = NULL, apsections = 1)
outspace |
Optional |
apsections |
Integer specifying number of anterior-posterior divisions. Default: 1 (no subdivision) |
This function extracts hippocampal regions from the full MTL atlas and can subdivide them into anterior-posterior segments. The resulting atlas maintains bilateral organization and can be used for targeted hippocampal analyses.
A list with class c("hippocampus", "atlas") containing:
Character string "hippocampus"
NeuroVol object with hippocampal parcellation
Integer vector of region IDs
Character vector of region labels
Character vector of hemisphere designations
Matrix of RGB colors for visualization
Full labels including hemisphere information
## Not run: # Basic hippocampal atlas hipp <- get_hipp_atlas() # With anterior-posterior subdivisions hipp_ap <- get_hipp_atlas(apsections = 3) ## End(Not run)## Not run: # Basic hippocampal atlas hipp <- get_hipp_atlas() # With anterior-posterior subdivisions hipp_ap <- get_hipp_atlas(apsections = 3) ## End(Not run)
Thin wrapper around 'get_fsl_atlas()' for the FSL-distributed Julich-Brain cytoarchitectonic atlas. This requires a local FSL-style atlas directory and uses the XML/image files under '$FSLDIR/data/atlases'.
get_julich_brain_atlas(fsl_dir = Sys.getenv("FSLDIR"), download = TRUE, ...)get_julich_brain_atlas(fsl_dir = Sys.getenv("FSLDIR"), download = TRUE, ...)
fsl_dir |
FSL installation directory. Defaults to 'Sys.getenv("FSLDIR")'. 'get_julich_brain_atlas()' downloads an FSL-style Julich-Brain cache when this is empty and 'download = TRUE'. |
An 'atlas' object, or path metadata when 'path_only = TRUE'.
Loads the Olsen medial temporal lobe atlas and optionally resamples it to a different space.
get_olsen_mtl(outspace = NULL)get_olsen_mtl(outspace = NULL)
outspace |
Optional |
A list with class 'atlas' containing the MTL parcellation
get_hipp_atlas for hippocampus-specific parcellation
# Load in native space mtl <- get_olsen_mtl() # Load and resample to MNI152NLin2009cAsym space (requires neuroim2) # space <- neuroim2::read_template_space("MNI152NLin2009cAsym") # mtl_resampled <- get_olsen_mtl(outspace = space)# Load in native space mtl <- get_olsen_mtl() # Load and resample to MNI152NLin2009cAsym space (requires neuroim2) # space <- neuroim2::read_template_space("MNI152NLin2009cAsym") # mtl_resampled <- get_olsen_mtl(outspace = space)
Extracts a specific region of interest from an atlas object based on label, ID, and hemisphere information.
get_roi(x, label = NULL, id = NULL, hemi = NULL) ## S3 method for class 'atlas' get_roi(x, label = NULL, id = NULL, hemi = NULL)get_roi(x, label = NULL, id = NULL, hemi = NULL) ## S3 method for class 'atlas' get_roi(x, label = NULL, id = NULL, hemi = NULL)
x |
An atlas object |
label |
Character string specifying the ROI label/name |
id |
Numeric ID of the ROI in the atlas |
hemi |
Character string specifying hemisphere ('left' or 'right') |
Returns a subset of the atlas containing only the specified ROI
## Not run: # Load the aseg atlas atlas <- get_aseg_atlas() # Extract the hippocampus ROI roi <- get_roi(atlas, label = "Hippocampus") ## End(Not run)## Not run: # Load the aseg atlas atlas <- get_aseg_atlas() # Extract the hippocampus ROI roi <- get_roi(atlas, label = "Hippocampus") ## End(Not run)
Retrieves and loads the Schaefer brain parcellation atlas, which provides a data-driven parcellation of the cerebral cortex based on both local gradient and global similarity approaches.
get_schaefer_atlas( parcels = c("100", "200", "300", "400", "500", "600", "700", "800", "900", "1000"), networks = c("7", "17"), resolution = c("1", "2"), outspace = NULL, smooth = FALSE, use_cache = TRUE ) sy_100_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_100_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_200_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_200_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_300_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_300_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_400_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_400_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_500_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_500_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_600_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_600_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_700_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_700_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_800_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_800_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_900_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_900_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_1000_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_1000_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... )get_schaefer_atlas( parcels = c("100", "200", "300", "400", "500", "600", "700", "800", "900", "1000"), networks = c("7", "17"), resolution = c("1", "2"), outspace = NULL, smooth = FALSE, use_cache = TRUE ) sy_100_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_100_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_200_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_200_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_300_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_300_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_400_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_400_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_500_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_500_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_600_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_600_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_700_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_700_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_800_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_800_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_900_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_900_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_1000_7( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... ) sy_1000_17( resolution = "2", outspace = NULL, smooth = FALSE, use_cache = TRUE, ... )
parcels |
Character string specifying number of parcels. Options: "100", "200", "300", "400", "500", "600", "800", "1000" |
networks |
Character string specifying network count. Options: "7", "17" |
resolution |
Character string specifying MNI space resolution in mm. Options: "1", "2" |
outspace |
Optional |
smooth |
Logical. Whether to smooth parcel boundaries after resampling. Default: FALSE |
use_cache |
Logical. Whether to cache downloaded files. Default: TRUE |
... |
Additional arguments (currently unused, included for consistency with convenience functions) |
The Schaefer atlas offers multiple resolutions of cortical parcellation (100-1000 parcels) and two network versions (7 or 17 networks). The atlas is based on resting-state functional connectivity from 1489 subjects. Features include:
Multiple granularity levels (100-1000 parcels)
Network assignments (7 or 17 networks)
Bilateral parcellation
Available in different resolutions (1mm or 2mm)
A list with classes c("schaefer", "volatlas", "atlas") containing:
Character string identifying atlas version
ClusteredNeuroVol object containing the parcellation
Data frame with RGB colors for visualization
Integer vector of region IDs
Character vector of region names
Original region labels from source data
Network assignment for each region
Hemisphere designation for each region
Shorthand functions are provided for common Schaefer atlas configurations. These functions call get_schaefer_atlas with the parcels and networks arguments pre-set. They all accept resolution (default "2"), outspace, smooth, use_cache, and ... arguments.
sy_100_7(): 100 parcels, 7 networks.
sy_100_17(): 100 parcels, 17 networks.
sy_200_7(): 200 parcels, 7 networks.
sy_200_17(): 200 parcels, 17 networks.
sy_300_7(): 300 parcels, 7 networks.
sy_300_17(): 300 parcels, 17 networks.
sy_400_7(): 400 parcels, 7 networks.
sy_400_17(): 400 parcels, 17 networks.
sy_500_7(): 500 parcels, 7 networks.
sy_500_17(): 500 parcels, 17 networks.
sy_600_7(): 600 parcels, 7 networks.
sy_600_17(): 600 parcels, 17 networks.
sy_800_7(): 800 parcels, 7 networks.
sy_800_17(): 800 parcels, 17 networks.
sy_1000_7(): 1000 parcels, 7 networks.
sy_1000_17(): 1000 parcels, 17 networks.
https://github.com/ThomasYeoLab/CBIG/
Schaefer, A., et al. (2018). Local-Global Parcellation of the Human Cerebral Cortex from Intrinsic Functional Connectivity MRI. Cerebral Cortex, 28(9), 3095-3114.
get_schaefer_surfatlas for surface-based version
## Not run: # Load 300-parcel atlas with 7 networks atlas <- get_schaefer_atlas(parcels = "300", networks = "7") # Load high-resolution version atlas_hires <- get_schaefer_atlas(parcels = "400", networks = "17", resolution = "1") # Resample to a different space new_space <- neuroim2::NeuroSpace(dim = c(91,109,91), spacing = c(2,2,2)) atlas_resampled <- get_schaefer_atlas(parcels = "300", outspace = new_space) ## End(Not run)## Not run: # Load 300-parcel atlas with 7 networks atlas <- get_schaefer_atlas(parcels = "300", networks = "7") # Load high-resolution version atlas_hires <- get_schaefer_atlas(parcels = "400", networks = "17", resolution = "1") # Resample to a different space new_space <- neuroim2::NeuroSpace(dim = c(91,109,91), spacing = c(2,2,2)) atlas_resampled <- get_schaefer_atlas(parcels = "300", outspace = new_space) ## End(Not run)
Loads the surface-based version of the Schaefer parcellation atlas, compatible with FreeSurfer surface representations.
get_schaefer_surfatlas( parcels = c("100", "200", "300", "400", "500", "600", "800", "1000"), networks = c("7", "17"), surf = c("inflated", "white", "pial"), use_cache = TRUE )get_schaefer_surfatlas( parcels = c("100", "200", "300", "400", "500", "600", "800", "1000"), networks = c("7", "17"), surf = c("inflated", "white", "pial"), use_cache = TRUE )
parcels |
Character string specifying number of parcels. Options: "100", "200", "300", "400", "500", "600", "800", "1000" |
networks |
Character string specifying network count. Options: "7", "17" |
surf |
Character string specifying surface type. Options: "inflated", "white", "pial" |
use_cache |
Logical. Whether to cache downloaded files. Default: TRUE |
Provides the Schaefer parcellation mapped to FreeSurfer surface meshes. The atlas can be loaded onto different surface representations (inflated, white, or pial) and maintains the same parcellation scheme as the volumetric version.
A list with classes c("schaefer", "surfatlas", "atlas") containing:
Surface type used
Left hemisphere surface atlas
Right hemisphere surface atlas
Atlas identifier
RGB color specifications
Region IDs
Region names
Original region labels
Network assignments
Hemisphere designations
get_schaefer_atlas for volumetric version
## Not run: # Load inflated surface atlas surf_atlas <- get_schaefer_surfatlas(parcels = "300", networks = "7", surf = "inflated") # Load pial surface version pial_atlas <- get_schaefer_surfatlas(parcels = "400", networks = "17", surf = "pial") ## End(Not run)## Not run: # Load inflated surface atlas surf_atlas <- get_schaefer_surfatlas(parcels = "300", networks = "7", surf = "inflated") # Load pial surface version pial_atlas <- get_schaefer_surfatlas(parcels = "400", networks = "17", surf = "pial") ## End(Not run)
Retrieve the affine transformation matrix for converting coordinates between two standard neuroimaging coordinate spaces.
get_space_transform(from, to)get_space_transform(from, to)
from |
Character string specifying the source coordinate space. One of "MNI305", "MNI152". |
to |
Character string specifying the target coordinate space. One of "MNI305", "MNI152". |
A 4x4 numeric matrix representing the affine transform.
Returns the identity matrix if from == to.
Returns NULL with a warning if the transform is not available.
transform_coords, MNI305_to_MNI152
# Get the MNI305 to MNI152 transform xfm <- get_space_transform("MNI305", "MNI152") # Identity for same-space id <- get_space_transform("MNI152", "MNI152") all.equal(id, diag(4))# Get the MNI305 to MNI152 transform xfm <- get_space_transform("MNI305", "MNI152") # Identity for same-space id <- get_space_transform("MNI152", "MNI152") all.equal(id, diag(4))
Fetches one of the AtlasPack-derived subcortical atlases (CIT168, HCP thalamus, MDTB10 cerebellum, or HCP hippocampus/amygdala) using the existing TemplateFlow integration. The returned object includes the source template space and resolution so downstream workflows can track provenance.
get_subcortical_atlas( name, template_space = NULL, resolution = NULL, desc = NULL, outspace = NULL, use_cache = TRUE, path_only = FALSE, ... )get_subcortical_atlas( name, template_space = NULL, resolution = NULL, desc = NULL, outspace = NULL, use_cache = TRUE, path_only = FALSE, ... )
name |
Atlas identifier; see |
template_space |
TemplateFlow space to download (e.g.,
|
resolution |
TemplateFlow resolution (e.g., "01"). Defaults to the atlas recommendation; validated against known options for the atlas. |
desc |
Optional TemplateFlow |
outspace |
Optional |
use_cache |
Logical; pass through to |
path_only |
Logical; if TRUE, return paths to the atlas/label files plus metadata instead of loading into R objects. |
... |
Additional arguments forwarded to |
When path_only=FALSE (default), a list with classes
c("subcortical", "atlas") containing:
name: human-friendly atlas name
atlas: ClusteredNeuroVol with parcellation labels
ids: integer vector of region IDs
labels: character vector of region labels
orig_labels: same as labels
hemi: inferred hemisphere labels when available
cmap: optional RGB mapping if provided by the label file
space, resolution, desc: TemplateFlow metadata
template_atlas: TemplateFlow atlas parameter used
When path_only=TRUE, a list with class
c("subcortical_paths","list") containing atlas_path,
label_path, and the same metadata fields above.
## Not run: # Load CIT168 in NLin6Asym space cit <- get_subcortical_atlas("cit168", template_space = "MNI152NLin6Asym") # Get only the file paths without loading volumes paths <- get_subcortical_atlas("mdtb10", path_only = TRUE) ## End(Not run)## Not run: # Load CIT168 in NLin6Asym space cit <- get_subcortical_atlas("cit168", template_space = "MNI152NLin6Asym") # Get only the file paths without loading volumes paths <- get_subcortical_atlas("mdtb10", path_only = TRUE) ## End(Not run)
Determine which standard coordinate space a surface template's vertices are defined in.
get_surface_coordinate_space(template_id)get_surface_coordinate_space(template_id)
template_id |
Character string identifying the surface template. Examples: "fsaverage", "fsaverage5", "fsaverage6", "fsLR". |
FreeSurfer's fsaverage surfaces were created using Talairach registration, which targets MNI305 space. All fsaverage density variants (fsaverage, fsaverage5, fsaverage6) share this coordinate system.
The HCP's fsLR template was designed to align with MNI152 space, so no transform is needed when working with MNI152 volumetric data.
Character string indicating the coordinate space:
"MNI305" for fsaverage variants (fsaverage, fsaverage5, fsaverage6)
"MNI152" for fsLR (HCP template)
"Unknown" for unrecognized templates
transform_coords, get_space_transform
get_surface_coordinate_space("fsaverage") # "MNI305" get_surface_coordinate_space("fsaverage6") # "MNI305" get_surface_coordinate_space("fsLR") # "MNI152"get_surface_coordinate_space("fsaverage") # "MNI305" get_surface_coordinate_space("fsaverage6") # "MNI305" get_surface_coordinate_space("fsLR") # "MNI152"
Unified function to retrieve neuroimaging templates and related files from
the TemplateFlow repository via the pure R templateflow package.
get_template( space = "MNI152NLin2009cAsym", variant = "brain", modality = "T1w", resolution = 1, cohort = NULL, desc = "brain", label = NULL, atlas = NULL, suffix = NULL, extension = ".nii.gz", path_only = FALSE, use_cache = TRUE, api_handle = NULL, ... ) get_surface_template( template_id, surface_type, hemi, density = NULL, resolution = NULL, ..., load_as_path = TRUE )get_template( space = "MNI152NLin2009cAsym", variant = "brain", modality = "T1w", resolution = 1, cohort = NULL, desc = "brain", label = NULL, atlas = NULL, suffix = NULL, extension = ".nii.gz", path_only = FALSE, use_cache = TRUE, api_handle = NULL, ... ) get_surface_template( template_id, surface_type, hemi, density = NULL, resolution = NULL, ..., load_as_path = TRUE )
space |
Character string. The primary TemplateFlow identifier for the template space
(e.g., |
variant |
Character string. A high-level descriptor for common template types.
Supported: |
modality |
Character string. The imaging modality or primary suffix for the template file.
Supported: |
resolution |
(Optional) Character string specifying the resolution, primarily for fsaverage variants (e.g., "06" for fsaverage6). |
cohort |
Character string. Optional cohort identifier. |
desc |
Character string. Specific TemplateFlow |
label |
Character string. Specific TemplateFlow |
atlas |
Character string. Specific TemplateFlow |
suffix |
Character string. Specific TemplateFlow |
extension |
Character string. The file extension. Default: |
path_only |
Logical. If |
use_cache |
Logical. If |
api_handle |
Deprecated and ignored. Kept for backward compatibility. |
... |
Additional arguments passed to the TemplateFlow query
(e.g., |
template_id |
The main TemplateFlow template identifier for the surface (e.g., "fsLR", "fsaverage"). This is passed as the 'space' argument to 'get_template'. |
surface_type |
A character string indicating the type of surface to retrieve. Common values include: "pial", "white", "inflated", "midthickness", "sphere". This is passed as the 'suffix' argument to 'get_template'. |
hemi |
Character string, "L" for left hemisphere or "R" for right hemisphere. Passed as 'hemi' to 'get_template'. |
density |
(Optional) Character string specifying the surface density (e.g., "32k" for fsLR, "164k" for fsaverage). Forwarded to TemplateFlow as 'density'. |
load_as_path |
Logical, whether to return only the path to the file. Defaults to 'TRUE'. |
The function performs several pre-flight checks:
- Validates the existence of the specified space.
- Validates the specified resolution against available resolutions.
Caching behaviour:
- The templateflow R package maintains its own disk cache.
- NeuroVol loading is memoised at the R session level to avoid
re-reading large NIfTI files.
If any of space, variant, modality, resolution,
or label are vectors of length > 1, a named list of results is returned.
Otherwise a single neuroim2::NeuroVol or file path string.
If 'load_as_path' is 'TRUE', a character string (path). If 'load_as_path' is 'FALSE', the result of 'as_neurovol'.
## Not run: # Get default MNI T1w brain template mni_brain <- get_template() # Vectorized: Get MNI brain and mask variants mni_variants <- get_template(variant = c("brain", "mask")) # Path only path <- get_template(path_only = TRUE) ## End(Not run) # Get the pial surface for the left hemisphere of fsLR 32k template (as path) # fslr_pial_L_path <- get_surface_template(template_id = "fsLR", surface_type = "pial", # hemi = "L", density = "32k") # print(fslr_pial_L_path)## Not run: # Get default MNI T1w brain template mni_brain <- get_template() # Vectorized: Get MNI brain and mask variants mni_variants <- get_template(variant = c("brain", "mask")) # Path only path <- get_template(path_only = TRUE) ## End(Not run) # Get the pial surface for the left hemisphere of fsLR 32k template (as path) # fslr_pial_L_path <- get_surface_template(template_id = "fsLR", surface_type = "pial", # hemi = "L", density = "32k") # print(fslr_pial_L_path)
Load the Rosenke et al. (2021) probabilistic functional atlas of human
occipito-temporal visual cortex ("visfAtlas") as a volumetric MNI atlas.
The maximum-probability labelmap contains 33 regions spanning the early
retinotopic areas (v1d, v2d, v3d, v1v,
v2v, v3v), motion-selective hMT, and category-selective
regions for faces, bodies, characters, and places.
get_visfatlas(outspace = NULL, smooth = FALSE, use_cache = TRUE)get_visfatlas(outspace = NULL, smooth = FALSE, use_cache = TRUE)
outspace |
Optional |
smooth |
Logical. Whether to smooth parcel boundaries when resampling. |
use_cache |
Logical. Whether to use cached downloads. Default
|
The atlas is distributed as a single archive
(visfAtlas.zip, ~70 MB) containing FreeSurfer, BrainVoyager, and
NIfTI representations. This loader downloads the archive on demand, extracts
the volumetric maximum-probability map
(visfAtlas_MNI152_volume.nii.gz, 1 mm), and caches both under the
neuroatlas user cache directory. Region intensities (1-33) follow the
distributed FSL atlas specification; region names use the lower/upper-case
source labels with hemisphere prefixes lh_/rh_.
The volume is a single-subject MNI-space grid (182 x 218 x 182, 1 mm); the publication aligns it to the MNI colin27 brain.
Note that the visfAtlas defines V1-V3 (dorsal and ventral) but not hV4; for
V4 see get_wang_atlas or get_visual_atlas.
A list with classes c("visfatlas", "volatlas", "atlas").
https://download.brainvoyager.com/data/visfAtlas.zip
Rosenke, M., van Hoof, R., van den Hurk, J., Grill-Spector, K., & Goebel, R. (2021). A Probabilistic Functional Atlas of Human Occipito-Temporal Visual Cortex. Cerebral Cortex, 31(1), 603-619. doi:10.1093/cercor/bhaa246
get_wang_atlas, get_visual_atlas.
## Not run: visf <- get_visfatlas() table(visf$hemi) get_roi(visf, label = "lh_v1d_retinotopic") ## End(Not run)## Not run: visf <- get_visfatlas() table(visf$hemi) get_roi(visf, label = "lh_v1d_retinotopic") ## End(Not run)
A convenience loader that extracts the early visual areas from the
Julich-Brain cytoarchitectonic atlas and relabels them as V1-V5
per hemisphere. This provides a compact, probabilistically-derived
early-visual parcellation in MNI volume space without the surrounding
whole-brain regions.
get_visual_atlas( outspace = NULL, smooth = FALSE, resolution = NULL, fsl_dir = Sys.getenv("FSLDIR"), download = TRUE )get_visual_atlas( outspace = NULL, smooth = FALSE, resolution = NULL, fsl_dir = Sys.getenv("FSLDIR"), download = TRUE )
outspace |
Optional |
smooth |
Logical. Whether to smooth parcel boundaries when resampling. |
resolution |
Optional Julich-Brain resolution (e.g. |
fsl_dir |
FSL installation directory. Defaults to
|
download |
Logical. Download the Julich-Brain FSL cache when
|
The source regions are the Julich-Brain maximum-probability labels
GM Visual cortex V1 BA17, V2 BA18, V3V, V4, and
V5 (left/right), loaded via get_julich_brain_atlas().
Note that the Julich atlas defines only the ventral subdivision of V3
(V3V) and a single V4/V5 region per hemisphere.
For the topographic surface atlas with dorsal/ventral subdivisions and
hV4, see get_wang_atlas; for a volumetric functional
atlas, see get_visfatlas.
A list with classes c("visual", "volatlas", "atlas")
containing the V1-V5 regions per hemisphere.
Amunts, K., Mohlberg, H., Bludau, S., & Zilles, K. (2020). Julich-Brain: A 3D probabilistic atlas of the human brain's cytoarchitecture. Science, 369(6506), 988-992. doi:10.1126/science.abb4588
get_wang_atlas, get_visfatlas,
get_julich_brain_atlas.
## Not run: v <- get_visual_atlas() v$labels get_roi(v, label = "V1", hemi = "left") ## End(Not run)## Not run: v <- get_visual_atlas() v$labels get_roi(v, label = "V1", hemi = "left") ## End(Not run)
Load the Wang et al. (2015) probabilistic atlas of visual topographic areas
as a pair of neurosurf LabeledNeuroSurface objects on the FreeSurfer
fsaverage surface. The atlas defines 25 topographic areas per
hemisphere, covering the early visual areas (V1v, V1d,
V2v, V2d, V3v, V3d, hV4) plus ventral,
lateral, dorsal, and parietal maps (VO1/2, PHC1/2,
LO1/2, TO1/2, V3A/B, IPS0-5, SPL1,
FEF).
get_wang_atlas( surf = c("inflated", "pial", "white", "midthickness"), space = "fsaverage", use_cache = TRUE )get_wang_atlas( surf = c("inflated", "pial", "white", "midthickness"), space = "fsaverage", use_cache = TRUE )
surf |
Surface type. One of |
space |
Surface space / mesh template. Only |
use_cache |
Logical. Whether to use cached downloads. Default
|
The surface labels are the maximum-probability map (MPM) derived from 53
subjects, distributed as fsaverage (164k vertices) FreeSurfer overlay
files (lh/rh.wang15_mplbl.v1_0.mgz) bundled with the neuropythy
library. Files are downloaded on demand from the neuropythy GitHub
repository and cached under the neuroatlas user cache directory.
Surface geometry is obtained from TemplateFlow via
get_surface_template, so a working TemplateFlow setup is
required (mirroring glasser_surf). The full per-area
probability maps are also available from the original Princeton
distribution and may be added in a future release.
A list with classes c("wang", "surfatlas", "atlas")
containing lh_atlas/rh_atlas (LabeledNeuroSurface
objects), ids, labels, hemi, cmap, and the
standard atlas provenance metadata.
https://github.com/noahbenson/neuropythy (bundled Wang 2015 atlas); original distribution at https://scholar.princeton.edu/napl/resources.
Wang, L., Mruczek, R. E. B., Arcaro, M. J., & Kastner, S. (2015). Probabilistic Maps of Visual Topography in Human Cortex. Cerebral Cortex, 25(10), 3911-3931. doi:10.1093/cercor/bhu277
get_wang_prob_atlas for the full per-area probability
volumes, get_visfatlas for a volumetric visual-cortex atlas,
get_visual_atlas for cytoarchitectonic V1-V5.
## Not run: # Wang 2015 visual topography atlas on the fsaverage inflated surface wang <- get_wang_atlas(surf = "inflated") wang$labels get_roi(wang, label = "hV4") ## End(Not run)## Not run: # Wang 2015 visual topography atlas on the fsaverage inflated surface wang <- get_wang_atlas(surf = "inflated") wang$labels get_roi(wang, label = "hV4") ## End(Not run)
Resolve (and optionally load) the full per-area probability maps and
maximum-probability volumes from the original Princeton ProbAtlas_v4
distribution of the Wang et al. (2015) visual topography atlas. These are
the volumetric counterparts to the surface labels returned by
get_wang_atlas(): for each of the 25 topographic areas there is
a continuous probability map (perc_VTPM_vol_roi<n>_<hemi>.nii.gz) in
MNI volume space, plus a maximum-probability summary
(maxprob_vol_<hemi>.nii.gz).
get_wang_prob_atlas( prob_dir = NULL, image = c("probability", "maxprob"), hemi = c("both", "lh", "rh"), rois = NULL, path_only = TRUE, use_cache = TRUE ) ## S3 method for class 'wang_prob_paths' print(x, ...)get_wang_prob_atlas( prob_dir = NULL, image = c("probability", "maxprob"), hemi = c("both", "lh", "rh"), rois = NULL, path_only = TRUE, use_cache = TRUE ) ## S3 method for class 'wang_prob_paths' print(x, ...)
prob_dir |
Optional path to a locally-extracted ProbAtlas_v4 directory
(the folder containing |
image |
One of |
hemi |
One of |
rois |
Optional subset of areas, given as labels (e.g.
|
path_only |
Logical. When |
use_cache |
Logical. Also look for files under the neuroatlas Wang cache
directory when |
x |
A |
... |
Unused. |
The Princeton server (scholar.princeton.edu / napl) blocks
automated downloads of the binary archive (it returns HTTP 403 to scripted
requests), so this function does not download the data. Instead it
defaults to path_only = TRUE and returns a manifest describing the
expected files, the manual download URL, and the canonical ROI labels.
To work with the actual volumes, download ProbAtlas_v4.zip once in a
browser from the Princeton resources page, unzip it, and pass the resulting
directory (or its subj_vol_all subfolder) via prob_dir. With a
valid prob_dir you can set path_only = FALSE to read the
requested volumes as NeuroVol objects.
When path_only = TRUE, an object of class wang_prob_paths: a
list with the requested image/hemi, the manual download
zip_url, a files tibble (id, label, hemi,
member, path, exists), and the canonical labels.
When path_only = FALSE, a wang_prob_volumes list whose
volumes element holds the loaded NeuroVol objects.
https://napl.scholar.princeton.edu/resources
Wang, L., Mruczek, R. E. B., Arcaro, M. J., & Kastner, S. (2015). Probabilistic Maps of Visual Topography in Human Cortex. Cerebral Cortex, 25(10), 3911-3931. doi:10.1093/cercor/bhu277
get_wang_atlas for the fsaverage surface atlas.
## Not run: # Manifest only (no download): see which files are needed and where to get them manifest <- get_wang_prob_atlas() manifest head(manifest$files) # After manually downloading + unzipping ProbAtlas_v4.zip: paths <- get_wang_prob_atlas(prob_dir = "~/atlases/ProbAtlas_v4") v1v_lh <- get_wang_prob_atlas(prob_dir = "~/atlases/ProbAtlas_v4", rois = "V1v", hemi = "lh", path_only = FALSE) ## End(Not run)## Not run: # Manifest only (no download): see which files are needed and where to get them manifest <- get_wang_prob_atlas() manifest head(manifest$files) # After manually downloading + unzipping ProbAtlas_v4.zip: paths <- get_wang_prob_atlas(prob_dir = "~/atlases/ProbAtlas_v4") v1v_lh <- get_wang_prob_atlas(prob_dir = "~/atlases/ProbAtlas_v4", rois = "V1v", hemi = "lh", path_only = FALSE) ## End(Not run)
'r lifecycle::badge("deprecated")'
This function has been deprecated in favour of plot_brain().
Use plot_brain(schaefer_surf(...)) for interactive cortical surface
visualisation.
ggseg_schaefer( atlas, vals, thresh = NULL, pos = FALSE, palette = "Spectral", interactive = TRUE, lim = range(vals) )ggseg_schaefer( atlas, vals, thresh = NULL, pos = FALSE, palette = "Spectral", interactive = TRUE, lim = range(vals) )
atlas |
An atlas object containing Schaefer parcellation information |
vals |
Numeric vector of values to visualize on the atlas |
thresh |
Numeric vector of length 2 specifying (min, max) thresholds. |
pos |
Logical. If TRUE, uses raw values for thresholding. |
palette |
Character string specifying the color palette. Default: "Spectral" |
interactive |
Logical. If TRUE, creates an interactive plot. Default: TRUE |
lim |
Numeric vector of length 2 specifying the range for color mapping. |
A ggplot2 or ggiraph object.
## Not run: # Deprecated — use plot_brain(schaefer_surf(200, 17), vals = ...) instead ## End(Not run)## Not run: # Deprecated — use plot_brain(schaefer_surf(200, 17), vals = ...) instead ## End(Not run)
Load the Glasser HCP-MMP1.0 cortical parcellation projected to the
FreeSurfer fsaverage surface, as distributed by Kathryn Mills
(see Figshare dataset "HCP-MMP1.0 projected on fsaverage").
The result is a pair of neurosurf LabeledNeuroSurface objects plus
atlas metadata.
glasser_surf( space = "fsaverage", surf = c("pial", "white", "inflated", "midthickness"), use_cache = TRUE )glasser_surf( space = "fsaverage", surf = c("pial", "white", "inflated", "midthickness"), use_cache = TRUE )
space |
Surface space / mesh template. Only |
surf |
Surface type. One of |
use_cache |
Logical. Whether to cache downloaded annotation files in
the neuroatlas cache directory. Default: |
This function uses:
fsaverage surface geometry from TemplateFlow via
get_surface_template
fsaverage .annot files from the Mills Figshare distribution
(lh.HCP-MMP1.annot, rh.HCP-MMP1.annot)
Currently only the "fsaverage" surface space is supported.
A list with classes c("glasser_surf","surfatlas","atlas")
containing:
lh_atlas, rh_atlas: LabeledNeuroSurface
objects for left and right hemispheres.
surf_type: requested surface type.
surface_space: surface template space ("fsaverage").
ids, labels, orig_labels,
hemi, cmap: atlas metadata.
## Not run: # Glasser MMP1.0 on fsaverage pial surface atl <- glasser_surf(space = "fsaverage", surf = "pial") ## End(Not run)## Not run: # Glasser MMP1.0 on fsaverage pial surface atl <- glasser_surf(space = "fsaverage", surf = "pial") ## End(Not run)
Classify a vector as "continuous" or "categorical" for plot
defaults.
infer_design_var_type(x)infer_design_var_type(x)
x |
A vector. |
A character scalar.
**DEPRECATED:** TemplateFlow is now accessed via the pure R 'templateflow' package. Python is no longer required.
Install the R package instead:
remotes::install_github("bbuchsbaum/templateflow")
install_templateflow( method = "auto", conda = "auto", envname = NULL, force_reinstall = FALSE )install_templateflow( method = "auto", conda = "auto", envname = NULL, force_reinstall = FALSE )
method |
Ignored. |
conda |
Ignored. |
envname |
Ignored. |
force_reinstall |
Ignored. |
Invisible NULL.
# Deprecated. Install the R templateflow package instead: # remotes::install_github("bbuchsbaum/templateflow")# Deprecated. Install the R templateflow package instead: # remotes::install_github("bbuchsbaum/templateflow")
Convenience wrapper around cluster_explorer() that launches the
app in an interactive session.
launch_cluster_explorer(...)launch_cluster_explorer(...)
... |
Passed to |
Invisibly returns the running app object.
Enumerate the atlases currently registered in the neuroatlas dispatch registry. Useful for discovery from scripts, vignettes, and Shiny apps.
list_atlases()list_atlases()
A tibble with one row per registered atlas and columns 'id', 'label', 'family', 'representation', 'default_space', and a comma-joined 'aliases' string.
[get_atlas()] to load an atlas by id.
list_atlases()list_atlases()
Convenience wrapper around get_surface_template that
downloads (via TemplateFlow) the requested surface geometry and returns it
as a neurosurf::SurfaceGeometry object (or a left/right list).
load_surface_template( template_id, surface_type, hemi = c("L", "R", "both"), density = NULL, resolution = NULL, ... )load_surface_template( template_id, surface_type, hemi = c("L", "R", "both"), density = NULL, resolution = NULL, ... )
template_id |
Surface template identifier passed to TemplateFlow (e.g., "fsaverage", "fsaverage6", "fsLR"). |
surface_type |
Surface type (e.g., "white", "pial", "inflated", "midthickness"). |
hemi |
Hemisphere to load. One of "L", "R", or "both". If "both",
a named list with elements |
density |
Optional surface density (TemplateFlow |
resolution |
Optional resolution string (TemplateFlow |
... |
Additional arguments forwarded to |
A neurosurf::SurfaceGeometry object when hemi is "L"
or "R"; a named list of two SurfaceGeometry objects when
hemi is "both".
## Not run: # fsaverage6 pial surface as NeuroSurface lh <- load_surface_template("fsaverage", "pial", hemi = "L", density = "41k", resolution = "06") # Both hemispheres of fsLR 32k inflated surface both <- load_surface_template("fsLR", "inflated", hemi = "both", density = "32k") ## End(Not run)## Not run: # fsaverage6 pial surface as NeuroSurface lh <- load_surface_template("fsaverage", "pial", hemi = "L", density = "41k", resolution = "06") # Both hemispheres of fsLR 32k inflated surface both <- load_surface_template("fsLR", "inflated", hemi = "both", density = "32k") ## End(Not run)
Maps a set of values to regions/parcels in an atlas object. This can be used to visualize data (like statistics or measurements) across atlas regions.
map_atlas(x, vals, thresh, ...) ## S3 method for class 'atlas' map_atlas(x, vals, thresh = NULL, pos = FALSE, ...) ## S3 method for class 'schaefer' map_atlas(x, vals, thresh = NULL, pos = FALSE, ...) ## S3 method for class 'glasser' map_atlas(x, vals, thresh = NULL, pos = FALSE, ...)map_atlas(x, vals, thresh, ...) ## S3 method for class 'atlas' map_atlas(x, vals, thresh = NULL, pos = FALSE, ...) ## S3 method for class 'schaefer' map_atlas(x, vals, thresh = NULL, pos = FALSE, ...) ## S3 method for class 'glasser' map_atlas(x, vals, thresh = NULL, pos = FALSE, ...)
x |
An atlas object to map values onto |
vals |
Numeric vector of values to map to atlas regions. Length should match the number of regions in the atlas |
thresh |
Optional numeric vector of length 2 specifying (min, max) thresholds for the mapped values. Values outside this range will be clamped. |
... |
Additional arguments passed to methods |
pos |
Logical. If 'TRUE', values are thresholded using raw values; otherwise the absolute values are used. |
Returns the atlas object with mapped values
## Not run: # Load the aseg atlas atlas <- get_aseg_atlas() vals <- rnorm(length(atlas$orig_labels)) # Map values with a threshold of -2 to 2 mapped <- map_atlas(atlas, vals, thresh = c(-2, 2)) ## End(Not run)## Not run: # Load the aseg atlas atlas <- get_aseg_atlas() vals <- rnorm(length(atlas$orig_labels)) # Map values with a threshold of -2 to 2 mapped <- map_atlas(atlas, vals, thresh = c(-2, 2)) ## End(Not run)
'r lifecycle::badge("deprecated")'
This function has been deprecated. Use map_atlas() directly
or plot_brain() for visualisation.
map_to_schaefer(atlas, vals, thresh = NULL, pos = FALSE)map_to_schaefer(atlas, vals, thresh = NULL, pos = FALSE)
atlas |
An atlas object containing Schaefer parcellation information |
vals |
Numeric vector of values to map to atlas regions |
thresh |
Numeric vector of length 2 specifying (min, max) thresholds. |
pos |
Logical. If TRUE, uses raw values; if FALSE, uses absolute values for thresholding. Default: FALSE |
A tibble with mapped values.
# Deprecated — use map_atlas() or plot_brain() instead# Deprecated — use map_atlas() or plot_brain() instead
Combines two brain atlases into a single unified atlas object, preserving all region information and adjusting region IDs to prevent conflicts. This is useful for creating composite atlases that combine different parcellation schemes.
merge_atlases(atlas1, atlas2)merge_atlases(atlas1, atlas2)
atlas1 |
The first atlas object to merge |
atlas2 |
The second atlas object to merge |
The merging process:
Verifies that both atlases have the same dimensions
Adjusts region IDs in the second atlas to avoid overlap
Combines color maps, labels, and hemisphere information
Creates a new ClusteredNeuroVol object for the merged atlas
A new atlas object containing:
Combined names of input atlases (atlas1::atlas2)
Combined ClusteredNeuroVol object
Combined colormap for all regions
Adjusted vector of all region IDs
Combined vector of region labels
Original labels from both atlases
Combined hemisphere designations
## Not run: # Load two atlases atlas1 <- get_aseg_atlas() atlas2 <- get_aseg_atlas() # Merge the atlases merged <- merge_atlases(atlas1, atlas2) # Check the combined regions print(merged) ## End(Not run)## Not run: # Load two atlases atlas1 <- get_aseg_atlas() atlas2 <- get_aseg_atlas() # Merge the atlases merged <- merge_atlases(atlas1, atlas2) # Check the combined regions print(merged) ## End(Not run)
The inverse of MNI305_to_MNI152, for converting RAS coordinates
from MNI152 space back to MNI305 (fsaverage) space.
MNI152_to_MNI305MNI152_to_MNI305
A 4x4 numeric matrix (affine transform in homogeneous coordinates).
This matrix is derived from FreeSurfer's mni152.register.dat file,
located at $FREESURFER_HOME/average/mni152.register.dat.
The transform accounts for the approximately 4mm difference between MNI305 and MNI152 coordinate systems. It includes small rotation, scaling, and translation components.
To apply: for a point p = c(R, A, S), compute
MNI305_to_MNI152 %*% c(p, 1) and take the first 3 elements.
MNI305_to_MNI152, transform_coords
# Transform a point from MNI152 to MNI305 point_152 <- c(10.695, -18.409, 36.137) point_305 <- (MNI152_to_MNI305 %*% c(point_152, 1))[1:3] print(point_305) # approximately c(10, -20, 35)# Transform a point from MNI152 to MNI305 point_152 <- c(10.695, -18.409, 36.137) point_305 <- (MNI152_to_MNI305 %*% c(point_152, 1))[1:3] print(point_305) # approximately c(10, -20, 35)
The canonical 4x4 affine transformation matrix for converting RAS coordinates from MNI305 (fsaverage) space to MNI152 space.
MNI305_to_MNI152MNI305_to_MNI152
A 4x4 numeric matrix (affine transform in homogeneous coordinates).
This matrix is derived from FreeSurfer's mni152.register.dat file,
located at $FREESURFER_HOME/average/mni152.register.dat.
The transform accounts for the approximately 4mm difference between MNI305 and MNI152 coordinate systems. It includes small rotation, scaling, and translation components.
To apply: for a point p = c(R, A, S), compute
MNI305_to_MNI152 %*% c(p, 1) and take the first 3 elements.
FreeSurfer: $FREESURFER_HOME/average/mni152.register.dat
https://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems
MNI152_to_MNI305, transform_coords
# Transform a single point from MNI305 to MNI152 point_305 <- c(10, -20, 35) point_152 <- (MNI305_to_MNI152 %*% c(point_305, 1))[1:3] print(point_152) # approximately c(10.695, -18.409, 36.137)# Transform a single point from MNI305 to MNI152 point_305 <- c(10, -20, 35) point_152 <- (MNI305_to_MNI152 %*% c(point_305, 1))[1:3] print(point_152) # approximately c(10.695, -18.409, 36.137)
Determines whether two template spaces require an affine coordinate transform (e.g., MNI305 to MNI152).
needs_coord_transform(from, to)needs_coord_transform(from, to)
from |
Source template space identifier. |
to |
Target template space identifier. |
This checks whether the *coordinate systems* differ (MNI305 vs MNI152), which requires an affine transform. It does NOT check whether the template grids differ within the same coordinate system (use [needs_template_warp()] for that).
Logical. 'TRUE' if the coordinate spaces differ, 'FALSE' if they match, 'NA' if either space is unknown.
[needs_template_warp()] for checking template-grid differences, [template_to_coord_space()] for the underlying lookup.
needs_coord_transform("fsaverage", "MNI152NLin6Asym") # TRUE needs_coord_transform("fsaverage", "MNI305") # FALSE needs_coord_transform("MNI152NLin6Asym", "MNI152NLin2009cAsym") # FALSEneeds_coord_transform("fsaverage", "MNI152NLin6Asym") # TRUE needs_coord_transform("fsaverage", "MNI305") # FALSE needs_coord_transform("MNI152NLin6Asym", "MNI152NLin2009cAsym") # FALSE
Determines whether two template spaces are in the same coordinate system but on different template grids, requiring a nonlinear warp.
needs_template_warp(from, to)needs_template_warp(from, to)
from |
Source template space identifier. |
to |
Target template space identifier. |
This function identifies cases where an affine transform is NOT needed but a nonlinear warp IS needed. For example, MNI152NLin6Asym and MNI152NLin2009cAsym are both in MNI152 coordinate space but use different nonlinear registration targets, so voxel grids don't align exactly (~2mm difference).
Logical. 'TRUE' if the templates share a coordinate space but differ in grid/registration, 'FALSE' otherwise, 'NA' if either space is unknown.
[needs_coord_transform()] for checking coordinate-space differences, [atlas_transform_plan()] for planning multi-step transforms.
needs_template_warp("MNI152NLin6Asym", "MNI152NLin2009cAsym") # TRUE needs_template_warp("fsaverage", "fsaverage6") # TRUE needs_template_warp("fsaverage", "MNI152") # FALSE (different coord spaces) needs_template_warp("MNI152NLin6Asym", "MNI152NLin6Asym") # FALSE (identical)needs_template_warp("MNI152NLin6Asym", "MNI152NLin2009cAsym") # TRUE needs_template_warp("fsaverage", "fsaverage6") # TRUE needs_template_warp("fsaverage", "MNI152") # FALSE (different coord spaces) needs_template_warp("MNI152NLin6Asym", "MNI152NLin6Asym") # FALSE (identical)
Convenience function to check whether a coordinate transform is required when working with a surface template and volumetric data in a given space.
needs_transform(surface_template, volume_space)needs_transform(surface_template, volume_space)
surface_template |
Character string identifying the surface template (e.g., "fsaverage", "fsLR"). |
volume_space |
Character string identifying the volumetric data's coordinate space (e.g., "MNI152", "MNI305"). |
Logical. TRUE if a transform is needed, FALSE if
the spaces match.
# fsaverage + MNI152 volume: transform needed needs_transform("fsaverage", "MNI152") # TRUE # fsLR + MNI152 volume: no transform needed needs_transform("fsLR", "MNI152") # FALSE # fsaverage + MNI305 volume: no transform needed needs_transform("fsaverage", "MNI305") # FALSE# fsaverage + MNI152 volume: transform needed needs_transform("fsaverage", "MNI152") # TRUE # fsLR + MNI152 volume: no transform needed needs_transform("fsLR", "MNI152") # FALSE # fsaverage + MNI305 volume: no transform needed needs_transform("fsaverage", "MNI305") # FALSE
Assign harmonic anchor hues to networks
network_anchor_hues( network_levels, scheme = c("even", "triadic", "tetradic", "complementary"), start_hue = 15 )network_anchor_hues( network_levels, scheme = c("even", "triadic", "tetradic", "complementary"), start_hue = 15 )
network_levels |
Character vector of unique network names. |
scheme |
Hue spacing scheme: '"even"', '"triadic"', '"tetradic"', or '"complementary"'. |
start_hue |
Starting hue in degrees. |
Named numeric vector of anchor hues.
hues <- network_anchor_hues(c("Visual", "Default", "DorsalAttn")) hueshues <- network_anchor_hues(c("Visual", "Default", "DorsalAttn")) hues
Structured provenance and space metadata for atlas objects.
new_atlas_ref( family, model, representation = c("volume", "surface", "derived"), template_space = NA_character_, coord_space = NA_character_, resolution = NA_character_, density = NA_character_, provenance = NA_character_, source = NA_character_, lineage = NA_character_, confidence = c("exact", "high", "approximate", "uncertain"), notes = NA_character_ )new_atlas_ref( family, model, representation = c("volume", "surface", "derived"), template_space = NA_character_, coord_space = NA_character_, resolution = NA_character_, density = NA_character_, provenance = NA_character_, source = NA_character_, lineage = NA_character_, confidence = c("exact", "high", "approximate", "uncertain"), notes = NA_character_ )
family |
Atlas family identifier (e.g., '"schaefer"', '"glasser"'). |
model |
Atlas model identifier (e.g., '"Schaefer2018"'). |
representation |
Atlas representation ('"volume"', '"surface"', or '"derived"'). |
template_space |
Template/grid identifier (e.g., '"MNI152NLin2009cAsym"', '"fsaverage6"'). |
coord_space |
Coordinate-space identifier (e.g., '"MNI152"', '"MNI305"'). |
resolution |
Optional resolution descriptor (e.g., '"1mm"'). |
density |
Optional surface density descriptor (e.g., '"41k"'). |
provenance |
URL, DOI, or short source identifier. |
source |
Source key used by the loader. |
lineage |
Optional derivation/projection note. |
confidence |
Confidence tier: '"exact"', '"high"', '"approximate"', or '"uncertain"'. |
notes |
Optional free-text notes. |
An object of class '"atlas_ref"'.
A detailed parcellation atlas of the medial temporal lobe (MTL) regions, including hippocampus and surrounding cortical areas, based on the work of Rosanna Olsen and colleagues.
olsen_mtlolsen_mtl
A list with class 'atlas' containing:
Character string identifying the atlas
NeuroVol object containing the parcellation in 1mm MNI space
Character vector of anatomical region labels
Full region labels including hemisphere information
Integer vector of region IDs (1:16)
Character vector indicating hemisphere ('left' or 'right')
The atlas provides a detailed segmentation of MTL structures in MNI space at 1mm resolution. It includes bilateral parcellation of:
Hippocampal subfields
Perirhinal cortex
Entorhinal cortex
Parahippocampal cortex
Olsen, R. K., et al. (2013). The role of relational binding in item memory: Evidence from face recognition in a case of developmental amnesia. Journal of Neuroscience, 33(36), 14107-14111.
# Load the atlas data data(olsen_mtl) # View available regions olsen_mtl$labels # Check distribution across hemispheres table(olsen_mtl$hemi)# Load the atlas data data(olsen_mtl) # View available regions olsen_mtl$labels # Check distribution across hemispheres table(olsen_mtl$hemi)
Create a validated, serializable parcel-level data object.
parcel_data( parcels, atlas_id, atlas_name = atlas_id, atlas_version = NULL, atlas_space = NULL, schema_version = "1.0.0" )parcel_data( parcels, atlas_id, atlas_name = atlas_id, atlas_version = NULL, atlas_space = NULL, schema_version = "1.0.0" )
parcels |
A data frame or tibble with one row per parcel. |
atlas_id |
Canonical parcellation identifier. |
atlas_name |
Human-readable parcellation name. Defaults to 'atlas_id'. |
atlas_version |
Optional atlas version string. |
atlas_space |
Optional template/space identifier. |
schema_version |
Schema version string. Default: '"1.0.0"'. |
'parcel_data' formalizes reduced parcel representations as two components: - atlas identity metadata ('atlas') - a parcel table ('parcels') with required columns 'id', 'label', and 'hemi'
Additional columns in 'parcels' are interpreted as value or feature columns.
An object of class '"parcel_data"'.
[as_parcel_data()], [write_parcel_data()], [read_parcel_data()]
tbl <- tibble::tibble( id = c(1L, 2L), label = c("A", "B"), hemi = c("left", "right"), statistic = c(0.4, -0.2) ) x <- parcel_data(tbl, atlas_id = "toy_atlas") xtbl <- tibble::tibble( id = c(1L, 2L), label = c("A", "B"), hemi = c("left", "right"), statistic = c(0.4, -0.2) ) x <- parcel_data(tbl, atlas_id = "toy_atlas") x
Returns a vector aligned to 'atlas$ids', suitable for 'map_atlas()' or 'plot_brain()'.
parcel_values(x, atlas, column = "value")parcel_values(x, atlas, column = "value")
x |
A 'parcel_data' object. |
atlas |
An atlas object. |
column |
Value column in 'x$parcels' to extract. |
A vector with 'length(atlas$ids)' elements ordered to 'atlas$ids'.
Renders a triangle-mesh projection of cortical surface parcellations with configurable views and optional ggiraph interactivity. This function replaces the legacy ggseg-based visualisation pipeline.
plot_brain( surfatlas, vals = NULL, views = c("lateral", "medial"), hemis = c("left", "right"), surface = "inflated", color_method = "rule_hcl", colors = NULL, palette = "cork", lim = NULL, interactive = TRUE, data_id_mode = c("parcel", "polygon"), ncol = 2L, panel_layout = c("native", "presentation"), style = c("default", "ggseg_like"), border = TRUE, border_geom = c("path", "segment"), boundary_smooth = 0L, projection_smooth = 0L, border_color = "grey30", border_size = 0.15, border_lineend = "round", border_linejoin = "round", silhouette = border, silhouette_color = border_color, silhouette_size = border_size, network_border = FALSE, network_border_color = border_color, network_border_size = border_size * 2, shading = FALSE, shading_strength = 0.22, shading_gamma = 1, shading_color = "black", fill_alpha = 1, overlay = NULL, overlay_threshold = NULL, overlay_alpha = 0.45, overlay_palette = "vik", overlay_lim = NULL, overlay_border = TRUE, overlay_border_color = "black", overlay_border_size = 0.25, overlay_fun = c("avg", "nn", "mode"), overlay_sampling = c("midpoint", "normal_line", "thickness"), colorbar = FALSE, colorbar_title = NULL, title = NULL, subtitle = NULL, caption = NULL, panel_labels = NULL, outline = FALSE, bg = "white", ... )plot_brain( surfatlas, vals = NULL, views = c("lateral", "medial"), hemis = c("left", "right"), surface = "inflated", color_method = "rule_hcl", colors = NULL, palette = "cork", lim = NULL, interactive = TRUE, data_id_mode = c("parcel", "polygon"), ncol = 2L, panel_layout = c("native", "presentation"), style = c("default", "ggseg_like"), border = TRUE, border_geom = c("path", "segment"), boundary_smooth = 0L, projection_smooth = 0L, border_color = "grey30", border_size = 0.15, border_lineend = "round", border_linejoin = "round", silhouette = border, silhouette_color = border_color, silhouette_size = border_size, network_border = FALSE, network_border_color = border_color, network_border_size = border_size * 2, shading = FALSE, shading_strength = 0.22, shading_gamma = 1, shading_color = "black", fill_alpha = 1, overlay = NULL, overlay_threshold = NULL, overlay_alpha = 0.45, overlay_palette = "vik", overlay_lim = NULL, overlay_border = TRUE, overlay_border_color = "black", overlay_border_size = 0.25, overlay_fun = c("avg", "nn", "mode"), overlay_sampling = c("midpoint", "normal_line", "thickness"), colorbar = FALSE, colorbar_title = NULL, title = NULL, subtitle = NULL, caption = NULL, panel_labels = NULL, outline = FALSE, bg = "white", ... )
surfatlas |
A surface atlas object of class |
vals |
Optional numeric vector of values to map onto parcels. Length
must equal the number of atlas regions ( |
views |
Character vector of views to render. Any combination of
|
hemis |
Character vector of hemispheres to include.
Default: |
surface |
Surface type. One of |
color_method |
Colour algorithm for discrete parcel colouring (when
|
colors |
Optional pre-computed colours: a tibble with |
palette |
Character: scico palette for continuous colour scale (when
|
lim |
Numeric vector of length 2 for colour scale limits (continuous
mode). Defaults to range of |
interactive |
Logical. If |
data_id_mode |
Interactive data-id granularity (when
|
ncol |
Integer: number of columns in the facet layout. Default: 2. |
panel_layout |
Panel coordinate layout strategy:
|
style |
Visual preset. |
border |
Logical. If |
border_geom |
Boundary rendering method. |
boundary_smooth |
Non-negative integer controlling Chaikin smoothing
iterations applied to boundary paths when |
projection_smooth |
Non-negative integer controlling Laplacian-like
smoothing iterations applied to projected vertex coordinates before parcel
polygons are constructed. This smooths filled parcel edges while
preserving shared boundaries across parcels. |
border_color |
Colour for parcel boundary lines. Default:
|
border_size |
Line width for parcel boundaries. Default: |
border_lineend |
Line end style for boundary lines (passed to
|
border_linejoin |
Line join style for boundary lines (passed to
|
silhouette |
Logical. If |
silhouette_color |
Colour for silhouette lines. Default:
|
silhouette_size |
Line width for silhouette lines. Default:
|
network_border |
Logical. If |
network_border_color |
Colour for network boundary lines. Default:
|
network_border_size |
Line width for network boundary lines. Default:
|
shading |
Logical. If |
shading_strength |
Numeric in |
shading_gamma |
Positive numeric scalar controlling the shadow falloff.
Higher values concentrate shadows in more oblique regions. Default:
|
shading_color |
Colour of the shading overlay. Default: |
fill_alpha |
Numeric in |
overlay |
Vertex-wise overlay or a |
overlay_threshold |
Optional absolute threshold for overlay values before rendering. |
overlay_alpha |
Numeric in |
overlay_palette |
scico palette for overlay colour mapping. Default:
|
overlay_lim |
Optional numeric length-2 limits for overlay colour mapping. |
overlay_border |
Logical. If |
overlay_border_color |
Colour for overlay boundaries. Default:
|
overlay_border_size |
Line width for overlay boundaries. Default:
|
overlay_fun |
Character: interpolation function passed to
|
overlay_sampling |
Character: sampling strategy passed to
|
colorbar |
Logical or character. When |
colorbar_title |
Optional character label for the colorbar. |
title, subtitle, caption
|
Optional plot-level annotations for static output. When a colorbar is present these are applied to the composed figure; otherwise they are added directly to the returned ggplot. |
panel_labels |
Optional panel label override. Use either an unnamed
character vector matching the number of panels, a named character vector
keyed by default panel names such as |
outline |
Logical. If |
bg |
Character: background colour for the plot. Default: |
... |
Additional arguments (currently unused). |
A ggplot2 object (when interactive = FALSE and no
standalone colorbar is requested), a patchwork object (when a
standalone static colorbar is composed), or a ggiraph::girafe
widget (when interactive = TRUE).
## Not run: atl <- schaefer_surf(200, 17) plot_brain(atl) plot_brain(atl, vals = rnorm(200), palette = "vik") plot_brain(atl, views = "lateral", interactive = FALSE) # Styling: rounded white parcel borders + thicker silhouette + network edges plot_brain( atl, interactive = FALSE, border_color = "white", border_size = 0.25, border_lineend = "round", silhouette_size = 0.6, network_border = TRUE, network_border_color = "grey10", network_border_size = 0.5, shading = TRUE, fill_alpha = 0.98, bg = "#f7f7f7" ) ## End(Not run)## Not run: atl <- schaefer_surf(200, 17) plot_brain(atl) plot_brain(atl, vals = rnorm(200), palette = "vik") plot_brain(atl, views = "lateral", interactive = FALSE) # Styling: rounded white parcel borders + thicker silhouette + network edges plot_brain( atl, interactive = FALSE, border_color = "white", border_size = 0.25, border_lineend = "round", silhouette_size = 0.6, network_border = TRUE, network_border_color = "grey10", network_border_size = 0.5, shading = TRUE, fill_alpha = 0.98, bg = "#f7f7f7" ) ## End(Not run)
Arranges multiple brain surface plots into a grid layout using
patchwork. Each element of vals_list produces one panel
rendered by plot_brain.
plot_brain_grid( surfatlas, vals_list, views = c("lateral", "medial"), hemis = c("left", "right"), ncol = NULL, shared_scale = TRUE, palette = "cork", lim = NULL, titles = NULL, colorbar = TRUE, colorbar_title = NULL, title = NULL, subtitle = NULL, caption = NULL, ... )plot_brain_grid( surfatlas, vals_list, views = c("lateral", "medial"), hemis = c("left", "right"), ncol = NULL, shared_scale = TRUE, palette = "cork", lim = NULL, titles = NULL, colorbar = TRUE, colorbar_title = NULL, title = NULL, subtitle = NULL, caption = NULL, ... )
surfatlas |
A |
vals_list |
A named list of numeric vectors, one per panel. Each vector must have length equal to the number of atlas regions. |
views |
Character vector of views passed to |
hemis |
Character vector of hemispheres passed to
|
ncol |
Integer number of columns in the grid layout. If |
shared_scale |
Logical. If |
palette |
Character: scico palette name. Default: |
lim |
Optional numeric length-2 colour limits. Overrides automatic limits when provided. |
titles |
Optional character vector of panel titles. If |
colorbar |
Logical or character. Use |
colorbar_title |
Optional shared colorbar title. |
title, subtitle, caption
|
Optional overall plot annotations applied to the composed figure. |
... |
Additional arguments passed to |
A patchwork object.
## Not run: atl <- schaefer_surf(200, 7) vals <- list( Contrast_A = rnorm(200), Contrast_B = rnorm(200) ) plot_brain_grid(atl, vals) ## End(Not run)## Not run: atl <- schaefer_surf(200, 7) vals <- list( Contrast_A = rnorm(200), Contrast_B = rnorm(200) ) plot_brain_grid(atl, vals) ## End(Not run)
'r lifecycle::badge("deprecated")'
This function has been deprecated. Use
plot_brain(glasser_surf(), vals = ...) instead for interactive
cortical surface visualisation.
plot_glasser(vals = NULL, value_col = "value", position = "dispersed")plot_glasser(vals = NULL, value_col = "value", position = "dispersed")
vals |
A data frame containing values to plot, must include columns:
If NULL (default), all regions will be assigned a value of 1 |
value_col |
Character string specifying the name of the column in vals containing the values to plot. Defaults to "value" |
position |
Character string specifying layout type. |
An error; this function has been removed.
## Not run: # Deprecated — use plot_brain(glasser_surf(), vals = ...) instead ## End(Not run)## Not run: # Deprecated — use plot_brain(glasser_surf(), vals = ...) instead ## End(Not run)
Visualise a Glasser atlas object. For surface atlases (glasser_surf),
renders via plot_brain(). For volumetric Glasser atlases,
falls back to the base plot.atlas() method.
Volumetric slice visualisation for any atlas object. By default renders a
multi-slice montage with each parcel coloured by the
atlas_roi_colors() system. An orthogonal three-plane view is
also available.
## S3 method for class 'atlas' plot( x, y, view = c("montage", "ortho"), method = "rule_hcl", colors = NULL, nslices = 12L, ... ) ## S3 method for class 'glasser' plot( x, y, vals = NULL, thresh = c(0, 0), pos = FALSE, palette = "cork", lim = NULL, ... ) ## S3 method for class 'surfatlas' plot(x, y, vals = NULL, views = c("lateral", "medial"), ...)## S3 method for class 'atlas' plot( x, y, view = c("montage", "ortho"), method = "rule_hcl", colors = NULL, nslices = 12L, ... ) ## S3 method for class 'glasser' plot( x, y, vals = NULL, thresh = c(0, 0), pos = FALSE, palette = "cork", lim = NULL, ... ) ## S3 method for class 'surfatlas' plot(x, y, vals = NULL, views = c("lateral", "medial"), ...)
x |
An atlas object (atlas, glasser, schaefer, etc.) |
y |
Ignored (required for S3 consistency) |
view |
Character; |
method |
Colour algorithm passed to |
colors |
Optional pre-computed colour specification: a tibble from
|
nslices |
Number of slices for montage view (default 12). |
... |
Additional arguments passed to |
vals |
Numeric vector of values to visualize. If NULL (default), all regions will be assigned a value of 1, creating a uniform visualization |
thresh |
Numeric vector of length 2 for thresholding values |
pos |
Logical. If TRUE, uses raw values for thresholding |
palette |
Character. Name of scico color palette |
lim |
Numeric vector of length 2 for color scale limits. If NULL, will be set to range of vals |
views |
Character vector of views to render for surface atlases.
Any combination of |
plot.surfatlas renders a cortical surface projection via
plot_brain().
A ggplot2 or ggiraph object
For view = "montage", a ggplot2 object (invisibly).
For view = "ortho", a patchwork composite (if available) or a
list of three ggplot2 objects.
atlas_roi_colors, ggseg_schaefer
atlas <- get_aseg_atlas() plot(atlas) plot(atlas, view = "ortho") plot(atlas, method = "maximin_view", nslices = 6)atlas <- get_aseg_atlas() plot(atlas) plot(atlas, view = "ortho") plot(atlas, method = "maximin_view", nslices = 6)
Print methods for various atlas objects in the neuroatlas package
## S3 method for class 'atlas' print(x, ...) ## S3 method for class 'atlas_provenance' print(x, ...) ## S3 method for class 'glasser' print(x, ...) ## S3 method for class 'schaefer' print(x, ...)## S3 method for class 'atlas' print(x, ...) ## S3 method for class 'atlas_provenance' print(x, ...) ## S3 method for class 'glasser' print(x, ...) ## S3 method for class 'schaefer' print(x, ...)
x |
An atlas object (atlas, glasser, schaefer, etc.) |
... |
Additional arguments passed to print |
Invisibly returns x.
The object is returned invisibly
atlas <- get_aseg_atlas() print(atlas)atlas <- get_aseg_atlas() print(atlas)
Print Method for Atlas Alignment Results
## S3 method for class 'atlas_alignment' print(x, ...)## S3 method for class 'atlas_alignment' print(x, ...)
x |
An 'atlas_alignment' object. |
... |
Unused. |
Invisibly returns 'x'.
ref <- new_atlas_ref( family = "schaefer", model = "Schaefer2018", representation = "volume", template_space = "MNI152NLin6Asym", coord_space = "MNI152", confidence = "high" ) a <- structure(list(atlas_ref = ref), class = c("schaefer", "atlas")) print(atlas_alignment(a, a))ref <- new_atlas_ref( family = "schaefer", model = "Schaefer2018", representation = "volume", template_space = "MNI152NLin6Asym", coord_space = "MNI152", confidence = "high" ) a <- structure(list(atlas_ref = ref), class = c("schaefer", "atlas")) print(atlas_alignment(a, a))
Print Method for Atlas References
## S3 method for class 'atlas_ref' print(x, ...)## S3 method for class 'atlas_ref' print(x, ...)
x |
An 'atlas_ref' object. |
... |
Unused. |
Invisibly returns 'x'.
Print Method for Transform Plans
## S3 method for class 'atlas_transform_plan' print(x, ...)## S3 method for class 'atlas_transform_plan' print(x, ...)
x |
An 'atlas_transform_plan' object. |
... |
Unused. |
Invisibly returns 'x'.
p <- atlas_transform_plan("MNI305", "MNI152") print(p)p <- atlas_transform_plan("MNI305", "MNI152") print(p)
Provides a brief summary of the TemplateFlow interface object.
## S3 method for class 'templateflow' print(x, ...)## S3 method for class 'templateflow' print(x, ...)
x |
An object of class |
... |
Additional arguments (unused). |
The input object x, returned invisibly.
Public wrapper for the core surface-view projection used by
plot_brain().
project_surface_view( verts, view = c("lateral", "medial", "dorsal", "ventral"), hemi = c("left", "right") )project_surface_view( verts, view = c("lateral", "medial", "dorsal", "ventral"), hemi = c("left", "right") )
verts |
Numeric matrix ( |
view |
Character scalar: one of |
hemi |
Character scalar: |
A list with elements:
xyNumeric matrix () of projected coordinates.
view_dirNumeric length-3 view direction vector used for backface culling.
Atlas-first convenience wrappers for label lookup. 'query_coord()' queries world/mm coordinates, while 'query_vox()' queries R-style 1-based voxel grid indices and converts them to world coordinates before dispatching to 'query_point()'.
query_coord(x, coords, ...) query_vox(x, ijk, ...)query_coord(x, coords, ...) query_vox(x, ijk, ...)
x |
A single atlas object or a named list of atlas objects. |
coords |
Numeric vector of length 3 or an N x 3 matrix of world/mm coordinates. |
... |
Additional arguments passed to 'query_point()', such as 'radius' or 'from_space'. |
ijk |
Numeric/integer vector of length 3 or an N x 3 matrix of R-style 1-based voxel grid indices. |
A tibble with atlas labels at the requested locations.
Given one or more 3D coordinates, look up the atlas region(s) at each location. Supports exact voxel lookup ('radius = 0') or fuzzy search ('radius > 0') that returns all regions within a sphere of given radius in millimetres. Multiple atlases can be queried simultaneously.
query_point(coords, atlas, radius = 0, from_space = "MNI152")query_point(coords, atlas, radius = 0, from_space = "MNI152")
coords |
Numeric vector of length 3 (single point) or an N x 3 matrix of world coordinates. |
atlas |
A single atlas object (class '"atlas"') or a named list of atlas objects. |
radius |
Numeric scalar giving the search radius in millimetres. '0' (default) performs an exact voxel lookup; values greater than zero return every region whose labelled voxels fall within 'radius' mm of the query coordinate. |
from_space |
Character string identifying the coordinate space of the input coordinates (default '"MNI152"'). |
World coordinates are converted to voxel grid positions via
coord_to_grid and rounded to the nearest integer.
When 'radius > 0', candidate voxel centres in a local grid neighbourhood
are tested in world coordinates to find all labelled atlas voxels within
'radius' mm.
If the atlas carries a coordinate-space annotation
('atlas$atlas_ref$coord_space') that differs from 'from_space', the input
coordinates are transformed automatically via
transform_coords.
A tibble with columns:
Integer index of the query coordinate (row number).
The input world coordinates.
Name of the atlas.
Integer region ID ('NA' for background or out-of-bounds).
Region label string ('NA' for background/OOB).
Hemisphere designation ('NA' if unavailable).
Network label ('NA' if unavailable).
## Not run: atlas <- get_schaefer_atlas(parcels = "200", networks = "7") query_point(c(24, -10, 5), atlas) # Multiple points pts <- rbind(c(24, -10, 5), c(-30, 20, 50)) query_point(pts, atlas) # Fuzzy search within 5 mm query_point(c(24, -10, 5), atlas, radius = 5) # Query multiple atlases at once atlases <- list(schaefer = atlas, aseg = get_aseg_atlas()) query_point(c(24, -10, 5), atlases) ## End(Not run)## Not run: atlas <- get_schaefer_atlas(parcels = "200", networks = "7") query_point(c(24, -10, 5), atlas) # Multiple points pts <- rbind(c(24, -10, 5), c(-30, 20, 50)) query_point(pts, atlas) # Fuzzy search within 5 mm query_point(c(24, -10, 5), atlas, radius = 5) # Query multiple atlases at once atlases <- list(schaefer = atlas, aseg = get_aseg_atlas()) query_point(c(24, -10, 5), atlases) ## End(Not run)
Read a 'parcel_data' Object from Disk
read_parcel_data(file, format = c("auto", "rds", "json"), validate = TRUE)read_parcel_data(file, format = c("auto", "rds", "json"), validate = TRUE)
file |
Input file path. |
format |
Serialization format: '"auto"', '"rds"', or '"json"'. |
validate |
Logical. If 'TRUE' (default), validate after reading. |
A 'parcel_data' object.
Applies a summary function to data within each ROI defined by an atlas. This is an S3 generic function.
reduce_atlas(atlas, data_vol, stat_func, ..., format = NULL) ## S3 method for class 'atlas' reduce_atlas( atlas, data_vol, stat_func, ..., format = NULL, level = c("parcel", "network", "hemisphere"), by = NULL )reduce_atlas(atlas, data_vol, stat_func, ..., format = NULL) ## S3 method for class 'atlas' reduce_atlas( atlas, data_vol, stat_func, ..., format = NULL, level = c("parcel", "network", "hemisphere"), by = NULL )
atlas |
An atlas object or another object for which a method is defined. |
data_vol |
A |
stat_func |
The function to apply to the data within each ROI (e.g., |
... |
Additional arguments passed to |
format |
Character string specifying output format: "wide" or "long". If NULL (default), uses "long" for NeuroVol and "wide" for NeuroVec. |
When data_vol is a 3D NeuroVol, the returned tibble contains a
single row with one column per ROI. If a 4D NeuroVec is supplied, each
time point is summarised separately and a time column is added to the
tibble.
A tibble with format depending on the format parameter:
"wide": Regions as columns. For NeuroVec, rows are time points.
"long": Columns are region and value (NeuroVol) or
time, region, and value (NeuroVec).
map_atlas for mapping values to atlas regions,
get_roi for extracting specific regions
## Not run: # Load an atlas atlas <- get_schaefer_atlas(parcels = "200", networks = "7") # Create example data (random values in brain space) brain_data <- neuroim2::NeuroVol(rnorm(prod(dim(atlas$atlas))), space = space(atlas$atlas)) # Compute mean values within each atlas region region_means <- reduce_atlas(atlas, brain_data, mean) # Compute standard deviation within each region region_sds <- reduce_atlas(atlas, brain_data, sd, na.rm = TRUE) ## End(Not run)## Not run: # Load an atlas atlas <- get_schaefer_atlas(parcels = "200", networks = "7") # Create example data (random values in brain space) brain_data <- neuroim2::NeuroVol(rnorm(prod(dim(atlas$atlas))), space = space(atlas$atlas)) # Compute mean values within each atlas region region_means <- reduce_atlas(atlas, brain_data, mean) # Compute standard deviation within each region region_sds <- reduce_atlas(atlas, brain_data, sd, na.rm = TRUE) ## End(Not run)
Averages (or otherwise summarises) a 4D image within each atlas parcel,
returning a ClusteredNeuroVec whose voxels share one
time-series per region.
reduce_atlas_vec(atlas, data_vol, mask, ...) ## S3 method for class 'atlas' reduce_atlas_vec( atlas, data_vol, mask, stat_func = mean, dilate = FALSE, radius = 4, maxn = 50, ... )reduce_atlas_vec(atlas, data_vol, mask, ...) ## S3 method for class 'atlas' reduce_atlas_vec( atlas, data_vol, mask, stat_func = mean, dilate = FALSE, radius = 4, maxn = 50, ... )
atlas |
An atlas object. |
data_vol |
A |
mask |
A |
... |
Additional arguments passed to methods. |
stat_func |
Function used to aggregate voxel values within each parcel
(default: |
dilate |
Logical. If |
radius |
Numeric dilation radius in voxels (passed to
|
maxn |
Integer maximum neighbours for dilation (passed to
|
The atlas volume is intersected with the brain mask so that only voxels inside the mask contribute to each parcel average.
Cluster IDs are remapped to contiguous 1:K before constructing the
ClusteredNeuroVec. This is required because the [,,,t]
accessor in neuroim2 uses cluster IDs as direct column indices into
the internal time-series matrix.
Parcels that have no voxels inside the mask receive NA time-series
in the output.
reduce_atlas for a tibble-based summary,
dilate_atlas for expanding parcels into a mask.
## Not run: atlas <- get_schaefer_atlas(parcels = "200", networks = "7") # data_vol: a NeuroVec with matching spatial dimensions # mask: a brain mask NeuroVol cvec <- reduce_atlas_vec(atlas, data_vol, mask) ts_mat <- as.matrix(cvec) # T x K cluster time-series ## End(Not run)## Not run: atlas <- get_schaefer_atlas(parcels = "200", networks = "7") # data_vol: a NeuroVec with matching spatial dimensions # mask: a brain mask NeuroVol cvec <- reduce_atlas_vec(atlas, data_vol, mask) ts_mat <- as.matrix(cvec) # T x K cluster time-series ## End(Not run)
Resamples a volume to a new space with optional smoothing of parcel boundaries. This is particularly useful for atlas parcellations where maintaining discrete labels is important.
resample( vol, outspace, smooth = FALSE, interp = 0, radius = NULL, min_neighbors = 3 )resample( vol, outspace, smooth = FALSE, interp = 0, radius = NULL, min_neighbors = 3 )
vol |
A NeuroVol object to be resampled |
outspace |
A NeuroSpace object specifying the target space |
smooth |
Logical. Whether to apply boundary smoothing after resampling. Default: FALSE |
interp |
Integer. Interpolation method (0=nearest neighbor, 1=linear). Default: 0 |
radius |
Numeric. Radius for smoothing neighborhood in voxels. If NULL, uses max(spacing)+0.5. Default: NULL |
min_neighbors |
Integer. Minimum number of neighbors required for smoothing. Default: 3 |
The resampling process:
First performs nearest-neighbor interpolation to the new space
Optionally smooths boundaries using a local majority voting scheme
Preserves zeros in the mask (background)
A resampled NeuroVol object in the new space
atlas <- get_aseg_atlas() vol <- atlas$atlas new_space <- neuroim2::NeuroSpace( dim = dim(vol), spacing = neuroim2::spacing(vol) ) resampled <- resample(vol, new_space)atlas <- get_aseg_atlas() vol <- atlas$atlas new_space <- neuroim2::NeuroSpace( dim = dim(vol), spacing = neuroim2::spacing(vol) ) resampled <- resample(vol, new_space)
Returns the names of attributes available for ROIs in an atlas. This is useful for discovering what metadata is available for filtering or analysis.
roi_attributes(x, ...) ## S3 method for class 'atlas' roi_attributes(x, ...)roi_attributes(x, ...) ## S3 method for class 'atlas' roi_attributes(x, ...)
x |
An atlas object |
... |
Additional arguments passed to methods |
A character vector of attribute names that contain meaningful (non-NA) values. Excludes internal fields like color values and the id column.
roi_metadata for getting the full metadata tibble
## Not run: # Discover available attributes atlas <- get_schaefer_atlas(parcels = "200", networks = "7") roi_attributes(atlas) #> [1] "label" "label_full" "hemi" "network" # Compare with ASEG atlas (no network attribute) aseg <- get_aseg_atlas() roi_attributes(aseg) #> [1] "label" "label_full" "hemi" ## End(Not run)## Not run: # Discover available attributes atlas <- get_schaefer_atlas(parcels = "200", networks = "7") roi_attributes(atlas) #> [1] "label" "label_full" "hemi" "network" # Compare with ASEG atlas (no network attribute) aseg <- get_aseg_atlas() roi_attributes(aseg) #> [1] "label" "label_full" "hemi" ## End(Not run)
Project ROI features to two dimensions (UMAP or PCA) and map polar angle to hue, yielding palettes that look globally structured.
roi_colors_embedding( rois, id_col = "roi", feature_cols = c("x", "y", "z"), hemi_col = NULL, method = c("umap", "pca"), C_range = c(40, 90), L = 65, seed = 1 )roi_colors_embedding( rois, id_col = "roi", feature_cols = c("x", "y", "z"), hemi_col = NULL, method = c("umap", "pca"), C_range = c(40, 90), L = 65, seed = 1 )
rois |
Tibble with one ROI per row containing 'roi', 'x', 'y', and 'z'. |
id_col |
Column containing ROI IDs. |
feature_cols |
Character vector of numeric or categorical columns that will be embedded (passed to 'stats::model.matrix()'). |
hemi_col |
Optional hemisphere column used for the final light/dark adjustment. |
method |
Either '"umap"' (requires the 'uwot' package) or '"pca"'. |
C_range |
Chroma range mapped from radial distance in the embedding. |
L |
Lightness value used for all ROIs before hemispheric adjustments. |
seed |
Random seed for reproducibility. |
Tibble with ROI IDs and colours.
rois <- data.frame( roi = 1:10, network = rep(c("Vis", "DMN"), 5), x = runif(10), y = runif(10), z = runif(10) ) pal <- roi_colors_embedding(rois, feature_cols = c("x","y","z"), method = "pca")rois <- data.frame( roi = 1:10, network = rep(c("Vis", "DMN"), 5), x = runif(10), y = runif(10), z = runif(10) ) pal <- roi_colors_embedding(rois, feature_cols = c("x","y","z"), method = "pca")
Assign perceptually separated colours by penalising conflicts between ROIs that are likely to appear together in axial/coronal/sagittal views. This is a strong default for general slice and surface visualisation.
roi_colors_maximin_view( rois, id_col = "roi", xyz_cols = c("x", "y", "z"), hemi_col = NULL, network_col = NULL, pair_col = NULL, k = 12, sigma_xy = 25, sigma_slice = 10, candidate_multiplier = 10, tau = 10, lambda_global = 0.15, bg_hex = "#808080", alpha = 0.85, seed = 1, weight_transform = NULL )roi_colors_maximin_view( rois, id_col = "roi", xyz_cols = c("x", "y", "z"), hemi_col = NULL, network_col = NULL, pair_col = NULL, k = 12, sigma_xy = 25, sigma_slice = 10, candidate_multiplier = 10, tau = 10, lambda_global = 0.15, bg_hex = "#808080", alpha = 0.85, seed = 1, weight_transform = NULL )
rois |
Tibble with one ROI per row containing 'roi', 'x', 'y', and 'z'. |
id_col |
Column containing ROI IDs. |
xyz_cols |
Character vector of length three giving the coordinates to use for distance calculations. |
hemi_col |
Optional hemisphere column used for the final light/dark adjustment. |
network_col |
Optional network label column to slightly boost cross-network conflicts. |
pair_col |
Optional column identifying homologous L/R ROI pairs. When supplied, colours are first assigned to the homolog pair and then nudged per hemisphere. |
k |
Number of nearest neighbours to evaluate when forming edges. |
sigma_xy |
In-plane decay (mm) for slice visibility. |
sigma_slice |
Through-slice decay (mm) for slice visibility. |
candidate_multiplier |
How many candidate colours to generate relative to the number of ROIs. |
tau |
Soft-min temperature; smaller emphasises hard minimum distance, larger smooths the objective. |
lambda_global |
Optional additional term that encourages global colour diversity. |
bg_hex |
Background grey (for contrast filtering). |
alpha |
Opacity of overlays when evaluating contrast. |
seed |
Random seed for reproducibility. |
weight_transform |
Optional weight adjustment callback passed to [build_conflict_edges()]. |
Tibble with ROI IDs and assigned colours.
rois <- data.frame( roi = 1:10, x = runif(10, 0, 90), y = runif(10, 0, 100), z = runif(10, 0, 80) ) pal <- roi_colors_maximin_view(rois, xyz_cols = c("x", "y", "z"))rois <- data.frame( roi = 1:10, x = runif(10, 0, 90), y = runif(10, 0, 100), z = runif(10, 0, 80) ) pal <- roi_colors_maximin_view(rois, xyz_cols = c("x", "y", "z"))
Assign colours so that networks share analogous hue families while still maximising spatial separation between neighbouring ROIs.
roi_colors_network_harmony( rois, id_col = "roi", xyz_cols = c("x", "y", "z"), network_col = "network", hemi_col = NULL, k = 12, sigma_xy = 25, sigma_slice = 10, scheme = "even", start_hue = 15, hue_width = 28, candidate_multiplier = 8, tau = 10, lambda_global = 0.1, bg_hex = "#808080", alpha = 0.85, seed = 1, weight_transform = NULL )roi_colors_network_harmony( rois, id_col = "roi", xyz_cols = c("x", "y", "z"), network_col = "network", hemi_col = NULL, k = 12, sigma_xy = 25, sigma_slice = 10, scheme = "even", start_hue = 15, hue_width = 28, candidate_multiplier = 8, tau = 10, lambda_global = 0.1, bg_hex = "#808080", alpha = 0.85, seed = 1, weight_transform = NULL )
rois |
Tibble with one ROI per row containing 'roi', 'x', 'y', and 'z'. |
id_col |
Column containing ROI IDs. |
xyz_cols |
Character vector of length three giving the coordinates to use for distance calculations. |
network_col |
Optional network label column to slightly boost cross-network conflicts. |
hemi_col |
Optional hemisphere column used for the final light/dark adjustment. |
k |
Number of nearest neighbours to evaluate when forming edges. |
sigma_xy |
In-plane decay (mm) for slice visibility. |
sigma_slice |
Through-slice decay (mm) for slice visibility. |
scheme |
Hue spacing scheme passed to [network_anchor_hues()]. |
start_hue |
Starting hue in degrees (0–360). |
hue_width |
Half-width (degrees) of the analogous band around each anchor hue. |
candidate_multiplier |
How many candidate colours to generate relative to the number of ROIs. |
tau |
Soft-min temperature; smaller emphasises hard minimum distance, larger smooths the objective. |
lambda_global |
Optional additional term that encourages global colour diversity. |
bg_hex |
Background grey (for contrast filtering). |
alpha |
Opacity of overlays when evaluating contrast. |
seed |
Random seed for reproducibility. |
weight_transform |
Optional weight adjustment callback passed to [build_conflict_edges()]. |
Tibble with ROI IDs and hex colours.
rois <- data.frame( roi = 1:10, network = rep(c("Vis", "DMN"), 5), x = runif(10, 0, 90), y = runif(10, 0, 100), z = runif(10, 0, 80) ) pal <- roi_colors_network_harmony(rois, xyz_cols = c("x","y","z"), network_col = "network")rois <- data.frame( roi = 1:10, network = rep(c("Vis", "DMN"), 5), x = runif(10, 0, 90), y = runif(10, 0, 100), z = runif(10, 0, 80) ) pal <- roi_colors_network_harmony(rois, xyz_cols = c("x","y","z"), network_col = "network")
Generates a fast, reproducible palette that combines harmonic network hues with anterior-posterior gradients and hemisphere luminance differences.
roi_colors_rule_hcl( rois, id_col = "roi", xyz_cols = c("x", "y", "z"), network_col = NULL, hemi_col = NULL, scheme = "even", start_hue = 15, hue_width = 30, C = 70, L_L = 72, L_R = 60 )roi_colors_rule_hcl( rois, id_col = "roi", xyz_cols = c("x", "y", "z"), network_col = NULL, hemi_col = NULL, scheme = "even", start_hue = 15, hue_width = 30, C = 70, L_L = 72, L_R = 60 )
rois |
Tibble with one ROI per row containing 'roi', 'x', 'y', and 'z'. |
id_col |
Column containing ROI IDs. |
xyz_cols |
Character vector of length three giving the coordinates to use for distance calculations. |
network_col |
Optional network label column to slightly boost cross-network conflicts. |
hemi_col |
Optional hemisphere column used for the final light/dark adjustment. |
scheme |
Hue spacing scheme passed to [network_anchor_hues()]. |
start_hue |
Starting hue in degrees (0–360). |
hue_width |
Half-width (degrees) of within-network hue modulation. |
C |
Fixed chroma. |
L_L |
Lightness for left hemisphere ROIs. |
L_R |
Lightness for right hemisphere ROIs. |
Tibble with ROI IDs and colours.
rois <- data.frame( roi = 1:10, network = rep(c("Vis", "DMN"), 5), hemi = rep(c("left", "right"), 5), x = runif(10), y = runif(10), z = runif(10) ) pal <- roi_colors_rule_hcl(rois, network_col = "network", hemi_col = "hemi", xyz_cols = c("x","y","z"))rois <- data.frame( roi = 1:10, network = rep(c("Vis", "DMN"), 5), hemi = rep(c("left", "right"), 5), x = runif(10), y = runif(10), z = runif(10) ) pal <- roi_colors_rule_hcl(rois, network_col = "network", hemi_col = "hemi", xyz_cols = c("x","y","z"))
Functions for accessing and filtering ROI (Region of Interest) metadata in atlas objects. These functions provide a unified, discoverable interface for working with multiple ROI attributes across different atlas types.
Returns a tibble containing metadata for all regions of interest (ROIs) in an atlas. This provides a unified, tidy interface for accessing ROI attributes across different atlas types.
roi_metadata(x, ...) ## S3 method for class 'atlas' roi_metadata(x, ...)roi_metadata(x, ...) ## S3 method for class 'atlas' roi_metadata(x, ...)
x |
An atlas object |
... |
Additional arguments passed to methods |
A tibble with one row per ROI and columns for each attribute. Standard columns include:
Numeric ROI identifier
Simplified region name
Original/full region label
Hemisphere ("left", "right", or NA for bilateral/midline)
RGB color values (0-255)
Template space identifier (e.g., "MNI152NLin6Asym"), when atlas_ref is available
Coordinate space (e.g., "MNI152", "MNI305"), when atlas_ref is available
Atlas family identifier (e.g., "schaefer"), when atlas_ref is available
Atlas model identifier (e.g., "Schaefer2018"), when atlas_ref is available
Representation type ("volume", "surface", or "derived"), when atlas_ref is available
Loader/source key, when atlas_ref is available
Atlas provenance confidence tier, when atlas_ref is available
Additional atlas-specific columns may be present (e.g., network for Schaefer atlases).
roi_attributes for listing available attributes,
filter_atlas for filtering atlas objects by attributes
## Not run: # Get metadata for Schaefer atlas atlas <- get_schaefer_atlas(parcels = "200", networks = "7") meta <- roi_metadata(atlas) # Filter using dplyr library(dplyr) left_visual <- meta %>% filter(hemi == "left", network == "Vis") ## End(Not run)## Not run: # Get metadata for Schaefer atlas atlas <- get_schaefer_atlas(parcels = "200", networks = "7") meta <- roi_metadata(atlas) # Filter using dplyr library(dplyr) left_visual <- meta %>% filter(hemi == "left", network == "Vis") ## End(Not run)
Load the Schaefer2018 cortical parcellation as a surface atlas, returning
neurosurf LabeledNeuroSurface objects plus standard atlas metadata.
By default this uses the packaged fsaverage6 geometry; other FreeSurfer
surface spaces use TemplateFlow for mesh geometry.
schaefer_surf( parcels = c(100, 200, 300, 400, 500, 600, 800, 1000), networks = c(7, 17), space = c("fsaverage6", "fsaverage", "fsaverage5"), surf = c("inflated", "white", "pial"), use_cache = TRUE )schaefer_surf( parcels = c(100, 200, 300, 400, 500, 600, 800, 1000), networks = c(7, 17), space = c("fsaverage6", "fsaverage", "fsaverage5"), surf = c("inflated", "white", "pial"), use_cache = TRUE )
parcels |
Number of parcels. Can be numeric or character; valid values are 100, 200, 300, 400, 500, 600, 800, 1000. |
networks |
Number of networks. Can be numeric or character; valid values are 7 or 17. |
space |
Surface space / mesh template. One of
|
surf |
Surface type. One of |
use_cache |
Logical. Passed to |
A list with classes c("schaefer","surfatlas","atlas")
containing:
lh_atlas, rh_atlas: LabeledNeuroSurface
objects for left and right hemispheres.
surf_type: requested surface type.
surface_space: Schaefer surface space (e.g. fsaverage6).
ids, labels, orig_labels,
network, hemi, cmap: atlas metadata.
## Not run: # Schaefer 200 parcels, 17 networks on fsaverage6 inflated surface atl <- schaefer_surf(parcels = 200, networks = 17, space = "fsaverage6", surf = "inflated") ## End(Not run)## Not run: # Schaefer 200 parcels, 17 networks on fsaverage6 inflated surface atl <- schaefer_surf(parcels = 200, networks = 17, space = "fsaverage6", surf = "inflated") ## End(Not run)
Return a data frame enumerating the currently supported Schaefer surface atlas variants, including their CBIG and TemplateFlow identifiers.
schaefer_surf_options()schaefer_surf_options()
A data frame with columns:
space: Schaefer surface space (fsaverage, fsaverage5, fsaverage6).
parcels: Number of parcels.
networks: Number of networks.
surf: Surface type ("inflated", "white", "pial").
cbig_space: CBIG FreeSurfer5.3 subfolder.
template_id, tf_resolution, tf_density:
TemplateFlow identifiers used by get_surface_template().
opts <- schaefer_surf_options() head(opts)opts <- schaefer_surf_options() head(opts)
Returns the path to the TemplateFlow cache directory. With the pure R
templateflow package, this is the TEMPLATEFLOW_HOME directory.
show_templateflow_cache_path()show_templateflow_cache_path()
A character string representing the path to the TemplateFlow cache directory.
cat("TemplateFlow cache is at:", show_templateflow_cache_path(), "\n")cat("TemplateFlow cache is at:", show_templateflow_cache_path(), "\n")
Returns known transforms between coordinate/template spaces from a static registry shipped with the package.
space_transform_manifest(status = NULL)space_transform_manifest(status = NULL)
status |
Optional character vector to filter by status (e.g., '"available"', '"planned"'). |
A data frame with one row per transform route and columns: 'from_space', 'to_space', 'transform_type', 'backend', 'confidence', 'reversible', 'data_files', 'status', and 'notes'.
# All known routes reg <- space_transform_manifest() # Only implemented routes available <- space_transform_manifest(status = "available")# All known routes reg <- space_transform_manifest() # Only implemented routes available <- space_transform_manifest(status = "available")
Tests whether the spatial correlation between two parcellated brain maps is stronger than expected by chance, using the spin-test framework of Alexander-Bloch et al. (2018). Parcel centroids on a sphere surface are randomly rotated and reassigned to the nearest original centroid, generating a null distribution of correlations.
spin_test( map1, map2, atlas, n_perm = 1000L, cor_method = c("pearson", "spearman", "kendall"), sphere = NULL, seed = NULL )spin_test( map1, map2, atlas, n_perm = 1000L, cor_method = c("pearson", "spearman", "kendall"), sphere = NULL, seed = NULL )
map1 |
Numeric vector of parcel values (length K, aligned to atlas parcels). |
map2 |
Numeric vector of parcel values (length K, aligned to atlas parcels). |
atlas |
A surface atlas object (class |
n_perm |
Integer. Number of spin permutations. Default: 1000. |
cor_method |
Character. Correlation method passed to |
sphere |
Optional list with elements |
seed |
Optional integer seed for reproducibility. |
The algorithm:
Compute parcel centroids on the sphere surface by averaging the sphere coordinates of vertices belonging to each parcel.
For each permutation, generate a uniform random 3D rotation matrix
(from the Haar measure on SO(3)), rotate all centroids, then reassign
each rotated centroid to its nearest original centroid using
nn.
Compute the correlation of map1 with the permuted
map2 (values shuffled according to the reassignment).
The p-value is (sum(abs(null) >= abs(observed)) + 1) /
(n_perm + 1).
A list of class "spin_test" with:
The observed correlation between map1 and map2.
Numeric vector of length n_perm containing
null correlations.
Two-sided p-value: proportion of null correlations with absolute value >= the observed absolute correlation.
Number of permutations performed.
Alexander-Bloch, A. F., et al. (2018). On testing for spatial correspondence between maps of human brain structure and function. NeuroImage, 178, 540-551.
## Not run: atlas <- get_schaefer_surfatlas(parcels = "100", networks = "7") K <- length(atlas$ids) map1 <- rnorm(K) map2 <- map1 + rnorm(K, sd = 0.5) res <- spin_test(map1, map2, atlas, n_perm = 500, seed = 42) print(res) ## End(Not run)## Not run: atlas <- get_schaefer_surfatlas(parcels = "100", networks = "7") K <- length(atlas$ids) map1 <- rnorm(K) map2 <- map1 + rnorm(K, sd = 0.5) res <- spin_test(map1, map2, atlas, n_perm = 500, seed = 42) print(res) ## End(Not run)
Return a new atlas containing only the requested regions. Regions can be
identified by integer ID (matching x$ids), by label (matching
x$labels), or by hemisphere. When multiple selection criteria are
given they are intersected.
sub_atlas(x, ids = NULL, labels = NULL, hemi = NULL, ...) ## S3 method for class 'atlas' sub_atlas(x, ids = NULL, labels = NULL, hemi = NULL, network = NULL, ...)sub_atlas(x, ids = NULL, labels = NULL, hemi = NULL, ...) ## S3 method for class 'atlas' sub_atlas(x, ids = NULL, labels = NULL, hemi = NULL, network = NULL, ...)
x |
An atlas object. |
ids |
Integer or numeric vector of region IDs to retain (matched
against |
labels |
Character vector of region labels to retain (matched against
|
hemi |
Character vector of hemispheres to retain
( |
... |
Additional arguments passed to methods. |
This is the atlas-level analogue of
sub_clusters for
ClusteredNeuroVol objects.
An atlas object of the same class as x containing only the
selected regions. Voxels (or vertices) not belonging to the selected
regions are excluded.
filter_atlas for tidy-eval filtering by metadata
columns, get_roi for extracting ROI volumes
## Not run: atlas <- get_aseg_atlas() # By ID sub <- sub_atlas(atlas, ids = c(10, 11, 12)) # By label sub2 <- sub_atlas(atlas, labels = c("Thalamus", "Caudate")) # By hemisphere left <- sub_atlas(atlas, hemi = "left") # Combined: left-hemisphere regions matching specific labels sub3 <- sub_atlas(atlas, labels = c("Thalamus", "Caudate"), hemi = "left") ## End(Not run)## Not run: atlas <- get_aseg_atlas() # By ID sub <- sub_atlas(atlas, ids = c(10, 11, 12)) # By label sub2 <- sub_atlas(atlas, labels = c("Thalamus", "Caudate")) # By hemisphere left <- sub_atlas(atlas, hemi = "left") # Combined: left-hemisphere regions matching specific labels sub3 <- sub_atlas(atlas, labels = c("Thalamus", "Caudate"), hemi = "left") ## End(Not run)
Returns a tibble describing the supported subcortical atlases built and harmonized by the AtlasPack resource (HCP thalamus, MDTB10 cerebellum, CIT168 subcortex, and HCP hippocampus/amygdala). Each row includes the TemplateFlow atlas identifier, supported template spaces, and default resolution/desc parameters used to fetch the data.
subcortical_atlas_options()subcortical_atlas_options()
A tibble with columns:
id: canonical neuroatlas identifier
atlas: TemplateFlow atlas field
label: human-readable name
default_space: default TemplateFlow space
spaces: list-column of allowed spaces
default_resolution: default TemplateFlow resolution string
resolutions: list-column of allowed resolutions
default_desc: optional TemplateFlow desc value
1. AtlasPack resource for harmonized atlases: https://github.com/PennLINC/AtlasPack 2. Najdenovska E. et al. (2018) Scientific Data, HCP thalamus. 3. King M. et al. (2019) Nature Neuroscience, MDTB10 cerebellum. 4. Pauli W.M. et al. (2018) Scientific Data, CIT168 subcortex. 5. Glasser M.F. et al. (2013) Neuroimage, HCP subcortical structures.
opts <- subcortical_atlas_options() optsopts <- subcortical_atlas_options() opts
Determine which standard coordinate space a template's data are defined in. Handles both surface templates (e.g., fsaverage) and volumetric templates (e.g., MNI152NLin6Asym).
template_to_coord_space(template_id)template_to_coord_space(template_id)
template_id |
Character string identifying the template. Examples: "fsaverage", "fsaverage6", "fsLR_32k", "MNI152NLin6Asym", "MNI152NLin2009cAsym", "MNI152", "MNI305". |
This function normalizes the input using the same alias resolution as the space transform registry, then maps it to a coordinate space:
fsaverage, fsaverage5, fsaverage6, MNI305
fsLR_32k, MNI152, MNI152NLin6Asym, MNI152NLin2009cAsym
Character string indicating the coordinate space ('"MNI305"', '"MNI152"', or '"Unknown"').
[get_surface_coordinate_space()] for the surface-only version, [needs_coord_transform()] and [needs_template_warp()] for transform checks.
template_to_coord_space("fsaverage") # "MNI305" template_to_coord_space("MNI152NLin6Asym") # "MNI152" template_to_coord_space("MNI152NLin2009cAsym") # "MNI152" template_to_coord_space("fsLR_32k") # "MNI152"template_to_coord_space("fsaverage") # "MNI305" template_to_coord_space("MNI152NLin6Asym") # "MNI152" template_to_coord_space("MNI152NLin2009cAsym") # "MNI152" template_to_coord_space("fsLR_32k") # "MNI152"
Retrieves a list of file paths from TemplateFlow that match a given template space and other optional metadata query parameters.
tflow_files(space, query_args = list(), api_handle = NULL)tflow_files(space, query_args = list(), api_handle = NULL)
space |
Character string. The TemplateFlow identifier for the template space (e.g., "MNI152NLin2009cAsym"). |
query_args |
(Optional) A named list of additional query parameters to filter the results (e.g., 'list(suffix = "T1w", resolution = 1, desc = "brain")'). |
api_handle |
Deprecated and ignored. |
A character vector of file paths matching the query. Returns an empty vector if no files match.
# List all T1w files for MNI152NLin2009cAsym template # mni_t1w_files <- tflow_files("MNI152NLin2009cAsym", # query_args = list(suffix = "T1w"))# List all T1w files for MNI152NLin2009cAsym template # mni_t1w_files <- tflow_files("MNI152NLin2009cAsym", # query_args = list(suffix = "T1w"))
Retrieves a list of all available template space identifiers from the TemplateFlow archive.
tflow_spaces(pattern = NULL, api_handle = NULL, ...)tflow_spaces(pattern = NULL, api_handle = NULL, ...)
pattern |
(Optional) A character string containing a regular expression to filter the template space names. If 'NULL' (default), all names are returned. |
api_handle |
Deprecated and ignored. |
... |
Additional arguments passed to 'grep' if 'pattern' is specified (e.g., 'ignore.case = TRUE'). |
A character vector of available template space names.
# List all template spaces # all_spaces <- tflow_spaces() # List template spaces containing "MNI" # mni_spaces <- tflow_spaces(pattern = "MNI")# List all template spaces # all_spaces <- tflow_spaces() # List template spaces containing "MNI" # mni_spaces <- tflow_spaces(pattern = "MNI")
Apply an affine transformation to convert 3D coordinates from one neuroimaging coordinate space to another.
transform_coords( coords, from = NULL, to = NULL, transform = NULL, coords_as_cols = FALSE )transform_coords( coords, from = NULL, to = NULL, transform = NULL, coords_as_cols = FALSE )
coords |
Numeric matrix of 3D coordinates to transform. Can be:
|
from |
Character string specifying the source coordinate space. One of "MNI305", "MNI152". |
to |
Character string specifying the target coordinate space. One of "MNI305", "MNI152". |
transform |
Optional 4x4 affine matrix. If provided, |
coords_as_cols |
Logical. If |
The transformation is applied as: p_new = M %*% [p; 1] where M is
the 4x4 affine matrix and p is each 3D point in homogeneous coordinates.
Transformed coordinates in the same format as the input.
get_space_transform, MNI305_to_MNI152
# Transform a single point p305 <- c(10, -20, 35) p152 <- transform_coords(p305, from = "MNI305", to = "MNI152") print(p152) # Transform multiple points (N x 3 matrix) points_305 <- rbind( c(10, -20, 35), c(0, 0, 0), c(-30, 15, 50) ) points_152 <- transform_coords(points_305, from = "MNI305", to = "MNI152") print(points_152) # Round-trip: MNI305 -> MNI152 -> MNI305 p_roundtrip <- transform_coords( transform_coords(p305, "MNI305", "MNI152"), "MNI152", "MNI305" ) all.equal(p305, p_roundtrip, tolerance = 1e-10)# Transform a single point p305 <- c(10, -20, 35) p152 <- transform_coords(p305, from = "MNI305", to = "MNI152") print(p152) # Transform multiple points (N x 3 matrix) points_305 <- rbind( c(10, -20, 35), c(0, 0, 0), c(-30, 15, 50) ) points_152 <- transform_coords(points_305, from = "MNI305", to = "MNI152") print(points_152) # Round-trip: MNI305 -> MNI152 -> MNI305 p_roundtrip <- transform_coords( transform_coords(p305, "MNI305", "MNI152"), "MNI152", "MNI305" ) all.equal(p305, p_roundtrip, tolerance = 1e-10)
Convenience function to transform surface vertex coordinates to match a target volumetric coordinate space.
transform_vertices_to_volume( vertices, surface_template, target_space = "MNI152" )transform_vertices_to_volume( vertices, surface_template, target_space = "MNI152" )
vertices |
Numeric matrix of vertex coordinates (N x 3). |
surface_template |
Character string identifying the surface template the vertices come from (e.g., "fsaverage", "fsLR"). |
target_space |
Character string identifying the target coordinate space (e.g., "MNI152"). Default is "MNI152". |
This is a convenience wrapper around transform_coords that
automatically determines the source space from the surface template.
Transformed vertex coordinates (N x 3 matrix). Returns the input unchanged if no transform is needed.
transform_coords, get_surface_coordinate_space
## Not run: # Load fsaverage surface surf <- load_surface_template("fsaverage", "white", hemi = "L") verts <- neurosurf::vertices(surf) # Transform vertices to MNI152 for sampling from fMRI volume verts_mni152 <- transform_vertices_to_volume(verts, "fsaverage", "MNI152") ## End(Not run)## Not run: # Load fsaverage surface surf <- load_surface_template("fsaverage", "white", hemi = "L") verts <- neurosurf::vertices(surf) # Transform vertices to MNI152 for sampling from fMRI volume verts_mni152 <- transform_vertices_to_volume(verts, "fsaverage", "MNI152") ## End(Not run)
Validate an Atlas Reference
validate_atlas_ref(x)validate_atlas_ref(x)
x |
Object to validate. |
Invisibly returns 'x' when valid.
Validate structure and key invariants for 'parcel_data' objects.
validate_parcel_data(x, strict = TRUE)validate_parcel_data(x, strict = TRUE)
x |
An object expected to be 'parcel_data'. |
strict |
Logical. If 'TRUE' (default), enforce strict checks on atlas metadata consistency. |
Invisibly returns 'x' if valid; otherwise throws an error.
Write a 'parcel_data' Object to Disk
write_parcel_data(x, file, format = c("auto", "rds", "json"), pretty = TRUE)write_parcel_data(x, file, format = c("auto", "rds", "json"), pretty = TRUE)
x |
A 'parcel_data' object. |
file |
Output file path. |
format |
Serialization format: '"auto"', '"rds"', or '"json"'. |
pretty |
Logical; pretty-print JSON output when 'format = "json"'. |
Invisibly returns normalized output path.