Package 'neuroatlas'

Description

A concise infix operator for filtering atlas regions by metadata attributes. Equivalent to calling filter_atlas but allows a more fluent pipe-friendly syntax.

Usage

atlas %where% expr

Arguments

Value

A new atlas object containing only the matching ROIs.

See Also

filter_atlas for the underlying function, roi_metadata for available filter columns

Examples

## 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)

Description

Match a data-frame column to atlas parcels and return a numeric vector in exact 'atlas$ids' order. Matching is strict by default: atlas and data keys must be unique, data keys must all exist in the atlas, and every atlas parcel must be represented unless 'allow_partial = TRUE'.

Usage

align_parcel_values(atlas, data, value, by = NULL, allow_partial = FALSE)

Arguments

Details

With 'by = NULL', 'id' is preferred, followed by 'label_full'. Composite label keys are considered only when they are unique in both the atlas and data. Ambiguous short labels therefore fail instead of being recycled across hemispheres or networks.

Atlas metadata columns supplied in 'data' are treated as consistency checks. They are never allowed to overwrite canonical metadata.

Glasser volume and surface IDs number opposite hemispheres first. Any Glasser join using id (including renamed or composite keys) therefore requires a matching id_convention column, or a parcel_data object with a matching atlas$id_convention. The convention is "hcp_R_first" for volumes and "surfatlas_L_first" for surfaces. Only declare a convention when the source of the IDs is known; missing or conflicting conventions cause an error. Reload older Glasser atlas objects that lack this metadata.

To move Glasser values between representations, supply only the shared label_full key and value columns, then use by = "label_full"; alternatively use by = c("area", "hemi"). For example, select source$parcels[c("label_full", "value")] from a parcel_data object. Representation-specific IDs, labels, colours and provenance in a full source table remain consistency checks and must be omitted for such a join. A complete parcel_data object remains bound to its source representation.

Value

A numeric vector named by parcel ID and ordered exactly like 'atlas$ids'.

Examples

atlas <- structure(
  list(
    name = "toy",
    atlas = array(1:3, c(3, 1, 1)),
    ids = 1:3,
    labels = c("A", "B", "C"),
    orig_labels = c("lh_A", "lh_B", "rh_C"),
    hemi = c("left", "left", "right")
  ),
  class = "atlas"
)
results <- data.frame(
  roi_index = c(3L, 1L, 2L),
  estimate = c(0.3, 0.1, 0.2)
)
align_parcel_values(
  atlas,
  results,
  value = estimate,
  by = c(id = "roi_index")
)

Description

Applies the declared qualified surface operator independently to each map. Noncortical values and their availability are copied by structure/index. Source map metadata and label tables are retained. Missing scalar values stay missing. Missing label values require explicit existing label keys, and their unavailable brainordinate indices are retained in per-map XML metadata and available; assigning a key does not establish sampled support.

Usage

apply_cifti_transform(
  x,
  transform,
  na_policy = c("propagate", "omit", "error"),
  label_method = c("aggregate", "largest"),
  missing_labels = NULL
)

Arguments

Value

A CiftiData on the target layout with original map metadata, per-brainordinate availability and cortical execution provenance.

See Also

write_cifti(), apply_template_transform()

Examples

## Not run: 
mapped <- apply_cifti_transform(source, op, missing_labels = 0)
write_cifti(mapped, "mapped.dlabel.nii")

## End(Not run)

Description

Scalar and probability data use trilinear interpolation; labels use nearest voxel centers with lower-index half-voxel ties. Sampling is restricted to the closed voxel-center box; unsupported values are NA, and supported zero is preserved. Probability channels retain partial mass and are not normalized across maps. Missingness considers strictly positive contributors only. fsLR composition resolves sampling missingness on fsaverage first, then resolves missing surface contributors with the native operator. Coverage for each stage is retained separately. Ribbon omission combines voxel and node weights within the sampling stage.

Usage

apply_surface_projection(
  x,
  projection,
  source_space = NULL,
  affine = NULL,
  data_type = c("auto", "continuous", "label", "probability"),
  na_policy = c("propagate", "omit", "error"),
  label_table = NULL
)

Arguments

Value

SurfaceData with values, exact target domain, per-map availability, finite source-weight mass, geometric sampling coverage, lost labels and directed projection provenance. Ribbon omission normalizes all finite voxel/node weights together; categorical nodes vote with smallest-key ties. projection_diagnostics() exposes per-map coverage and per-key counts at the source, sampled surface and final surface. These are representation counts, not anatomical accuracy or conservation across dimensions.

Examples

## Not run: 
result <- apply_surface_projection(volume, projection,
  source_space = "MNI152NLin6Asym", data_type = "probability"
)

## End(Not run)

Description

Continuous maps use row-normalized interpolation. Label keys use categorical voting and are never averaged. Unsupported and target-masked outputs are 'NA'; supported zero, including label key zero, remains a valid value. Missingness and source weight mass are returned separately for every map. Probability output roundoff within '1e-12' of [0,1] is clipped to that interval; larger excursions are errors. Input bounds remain strict and probability channels are never renormalized across maps.

Usage

apply_surface_transform(
  x,
  transform,
  na_policy = c("propagate", "omit", "error"),
  label_method = c("aggregate", "largest")
)

Arguments

Value

'SurfaceData' on the target domain, with 'coverage' diagnostics and provenance including input identity, operator identity and policies.

Examples

sphere <- rbind(
  c(1, 0, 0), c(-1, 0, 0), c(0, 1, 0),
  c(0, -1, 0), c(0, 0, 1), c(0, 0, -1)
)
faces <- rbind(
  c(0, 2, 4), c(2, 1, 4), c(1, 3, 4), c(3, 0, 4),
  c(2, 0, 5), c(1, 2, 5), c(3, 1, 5), c(0, 3, 5)
)
cortex <- rep(TRUE, 6)
domain <- surface_domain(
  "toy", "L", "6v", sphere, faces, cortex,
  "analytic", "v1"
)
if (requireNamespace("neurotransform", quietly = TRUE) &&
  utils::packageVersion("neurotransform") >= "0.2.0") {
  geometry <- surface_geometry(domain, sphere, faces, cortex)
  operator <- get_surface_transform(geometry, geometry, cache_dir = NULL)
  values <- surface_data(seq(0, 0.5, length.out = 6), domain)
  apply_surface_transform(values, operator)
}

Description

Composes the complete route in physical coordinates and samples each input channel once. Labels use nearest neighbour; scalar and probability values use linear interpolation. For image-to-image transforms, out-of-field samples are zero and probability channels are interpolated independently. Surface transforms dispatch to apply_surface_transform() or apply_surface_projection(), whose unsupported samples are NA and whose coverage and missingness semantics are documented separately.

Usage

apply_template_transform(
  x,
  transform,
  target = NULL,
  data_type = c("auto", "continuous", "label", "probability"),
  interpolation = NULL,
  missing_labels = NULL
)

Arguments

Value

The transformed atlas or volume. The neuroatlas_transform attribute records the route, artifact hashes, interpolation, grids and lost labels. Atlas objects retain semantic IDs, labels and source provenance, including regions that disappear on the target grid. A surface destination returns SurfaceData with exact domain, availability and projection provenance. A CIFTI destination returns CiftiData and preserves noncortical support.

Examples

if (requireNamespace("neurotransform", quietly = TRUE) &&
  requireNamespace("hdf5r", quietly = TRUE)) {
  grid <- neuroim2::NeuroSpace(c(2, 2, 2))
  volume <- neuroim2::NeuroVol(array(0.25, c(2, 2, 2)), grid)
  transform <- get_template_transform("MNI152NLin6Asym", "MNI152NLin6Asym")
  apply_template_transform(volume, transform, grid, data_type = "continuous")
}

Description

Convert Atlas Connectivity to igraph

Usage

as_igraph(x, ...)

## S3 method for class 'atlas_connectivity'
as_igraph(x, weighted = TRUE, ...)

Arguments

Value

Dispatches to methods.

Examples

if (requireNamespace("igraph", quietly = TRUE)) {
  connectivity <- structure(matrix(c(0, 0.5, 0.5, 0), 2),
    class = c("atlas_connectivity", "matrix", "array")
  )
  as_igraph(connectivity)
}

Description

Convert an Object to 'parcel_data'

Usage

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",
  by = NULL,
  allow_partial = FALSE,
  atlas_id = NULL,
  atlas_version = NULL,
  atlas_space = NULL,
  schema_version = "1.0.0",
  ...
)

## Default S3 method:
as_parcel_data(x, ...)

Arguments

Details

Glasser ID joins require a matching id_convention in the input table or parcel_data atlas metadata. See align_parcel_values() for safe joins between Glasser volume and surface representations. Numeric vectors are positional: they must already follow the target atlas's parcel order.

Value

An object of class '"parcel_data"'.

Examples

x <- parcel_data(data.frame(
  id = 1:2, label = c("A", "B"),
  hemi = c("left", "right"), value = c(0.2, 0.7)
), atlas_id = "toy")
as_parcel_data(x)

Description

Returns a structured compatibility/alignment summary between two atlas representations based on atlas provenance metadata.

Usage

atlas_alignment(x, y)

Arguments

Details

For same family/model/representation comparisons across templates, this function consults the space transform registry when available.

Value

A list of class '"atlas_alignment"' with fields: 'from', 'to', 'compatible', 'relation', 'method', 'confidence', 'status', 'requires_transform', and 'notes'.

Examples

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)$relation

Description

Get Atlas Artifact Metadata

Usage

atlas_artifacts(x, ...)

Arguments

Value

A tibble with one row per upstream artifact used to construct the atlas.

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
atlas_artifacts(atlas)

Description

Convert the stored citation table to R bibliography entries. These accessors never resolve DOIs or contact a service. References without complete article metadata remain 'Misc' entries with their recorded title and URL.

Usage

atlas_citations(x, role = NULL)

template_citations(x, role = NULL)

Arguments

Value

A ‘bibentry' vector, suitable for [utils::toBibtex()]. Each entry’s note identifies its role, and its key is derived from the stored DOI, URL, or title. The table with separate role rows is available through [atlas_metadata()] or [template_metadata()].

Examples

refs <- atlas_citations(get_aseg_atlas())
refs
utils::toBibtex(refs)

Description

Extracts mean time-series for each atlas region from a 4D NeuroVec and computes pairwise correlations to produce a connectivity matrix.

Usage

atlas_connectivity(
  data_vol,
  atlas,
  method = c("pearson", "spearman", "partial"),
  threshold = NULL,
  stat_func = mean,
  ...
)

Arguments

Value

A symmetric matrix of class c("atlas_connectivity", "matrix") with region labels as dimnames.

See Also

reduce_atlas for the underlying extraction, as_igraph.atlas_connectivity for graph conversion

Examples

## 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)

Description

Atlas Coordinate-Space Convenience Accessor

Usage

atlas_coord_space(x)

Arguments

Value

Character scalar (or 'NA_character_').

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
atlas_coord_space(atlas)

Description

Atlas Family Convenience Accessor

Usage

atlas_family(x)

Arguments

Value

Character scalar.

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
atlas_family(atlas)

Description

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.

Usage

atlas_graph(
  atlas,
  connectivity = c("6", "18", "26"),
  as = c("matrix", "igraph", "tibble"),
  include_weight = TRUE
)

Arguments

Value

Depending on as:

matrix

A symmetric integer matrix of dimension K x K with row/column names set to region labels.

igraph

An undirected igraph graph (requires the igraph package).

tibble

A data.frame (tibble if available) with columns from, to, and weight.

Examples

## 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)

Description

Extracts hierarchical level information from an atlas, describing how parcels map to higher-level groupings (networks, hemispheres).

Usage

atlas_hierarchy(atlas)

Arguments

Value

A list of class "atlas_hierarchy" with components:

levels

Character vector of hierarchy level names, from finest to coarsest (e.g., c("parcel", "network", "hemisphere")).

mappings

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).

Examples

## 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)

Description

Get Atlas Processing History

Usage

atlas_history(x, ...)

Arguments

Value

A tibble with one row per processing step tracked by neuroatlas.

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
atlas_history(atlas)

Description

A versioned, portable description of a loaded resource. Metadata are stored with the object and can be inspected without downloading files or resolving citations. Atlas objects store the record in 'x$metadata'; template volumes and surfaces use the 'neuroatlas_metadata' attribute, preserving their class.

Usage

atlas_metadata(x, ...)

## S3 method for class 'atlas'
atlas_metadata(x, ...)

## Default S3 method:
atlas_metadata(x, ...)

## S3 method for class 'wang_prob_volumes'
atlas_metadata(x, ...)

template_metadata(x, ...)

validate_resource_metadata(x)

## S3 method for class 'NeuroResourceMetadata'
print(x, ...)

Arguments

Details

'identity' describes the resource and its published version (unknown versions are 'NA'). 'content' describes the loaded representation, value type, selected parameters and current region count. 'spatial' describes the current sampling geometry; 'artifacts' retain source-space and resolution descriptors. A TemplateFlow resolution key is a query parameter, not a voxel size in millimetres.

'spatial$basis' records whether template identity is source-declared, inferred, user-supplied, or unknown. Geometry alone does not identify an anatomical template. Grid resampling does not establish registration to a different anatomical template.

'citations' is a table with reference roles; [atlas_citations()] and [template_citations()] convert it to R 'bibentry' objects. 'history' contains structured parameters and software versions. 'parents' retains metadata snapshots for composite resources. Missing historical metadata in legacy objects is reported conservatively; it is not reconstructed from the network.

The older [atlas_ref()], [atlas_artifacts()] and [atlas_history()] accessors read this authoritative record. Legacy list fields are compatibility copies; do not edit them to change metadata. Metadata preservation is guaranteed for neuroatlas loaders and supported atlas operations, not arbitrary operations in other packages or direct replacement of an object's data.

Value

'atlas_metadata()' and 'template_metadata()' return a 'NeuroResourceMetadata' list with 'schema_version', 'kind', 'identity', 'content', 'spatial', 'provenance', 'citations', 'artifacts', 'history', and 'parents'. 'validate_resource_metadata()' returns its input invisibly.

Examples

a <- get_aseg_atlas()
atlas_metadata(a)
atlas_metadata(a)$spatial$voxel_size
atlas_citations(a)

Description

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.

Usage

atlas_overlap(atlas1, atlas2, metrics = c("dice", "jaccard"), min_overlap = 0)

Arguments

Value

A tibble with columns:

atlas1_id

Integer region ID from atlas1

atlas1_label

Character label from atlas1

atlas2_id

Integer region ID from atlas2

atlas2_label

Character label from atlas2

dice

Dice similarity coefficient (if requested)

jaccard

Jaccard similarity coefficient (if requested)

n_overlap

Number of overlapping voxels

n_atlas1

Total voxels in the atlas1 region

n_atlas2

Total voxels in the atlas2 region

Rows are sorted by Dice coefficient descending (or Jaccard if Dice was not requested).

Examples

## 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)

Description

Access structured provenance metadata for atlas objects, including the canonical atlas identity, upstream artifacts, and processing history.

Usage

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, ...)

Arguments

Value

A list of class '"atlas_provenance"' with fields:

ref

Canonical atlas_ref() identity metadata.

artifacts

A tibble describing upstream files/resources.

history

A tibble describing processing steps applied in neuroatlas.

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
atlas_provenance(atlas)

Description

Returns the canonical atlas reference metadata for an atlas object.

Usage

atlas_ref(x, ...)

## S3 method for class 'atlas'
atlas_ref(x, ...)

## Default S3 method:
atlas_ref(x, ...)

Arguments

Value

An object of class '"atlas_ref"'.

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
atlas_ref(atlas)

Description

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.

Usage

atlas_roi_colors(atlas, method = "rule_hcl", ...)

Arguments

Details

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.

Value

A tibble with columns id (integer) and color (hex string), one row per region in the atlas.

Examples

atlas <- get_aseg_atlas()
cols <- atlas_roi_colors(atlas)
head(cols)

Description

Atlas Template-Space Convenience Accessor

Usage

atlas_space(x)

Arguments

Value

Character scalar (or 'NA_character_').

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
atlas_space(atlas)

Description

Returns currently known cross-representation alignment routes and their implementation status.

Usage

atlas_transform_manifest(scope = c("alignment", "space"))

Arguments

Value

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()].

Examples

# Atlas-family alignment routes
atlas_transform_manifest("alignment")

# Space-to-space routes
atlas_transform_manifest("space")

Description

Computes a transform route between spaces using the packaged transform registry.

Usage

atlas_transform_plan(
  from_space,
  to_space,
  data_type = c("parcel", "vertex", "voxel"),
  mode = c("auto", "strict"),
  available_only = FALSE,
  provider = c("auto", "neuroatlas", "templateflow")
)

Arguments

Details

Space identifiers are normalized internally, so aliases such as '"fslr32k"' are accepted.

Value

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.

Examples

# Direct route
p1 <- atlas_transform_plan("MNI305", "MNI152")

# Alias normalization + planned route
p2 <- atlas_transform_plan("fsaverage", "fslr32k")
p2$status

Description

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.

Usage

batch_reduce(
  inputs,
  atlas,
  stat_func = mean,
  ...,
  format = "long",
  parallel = FALSE,
  .progress = TRUE
)

Arguments

Value

A tibble with a subject column prepended to the reduce_atlas output for each input.

See Also

reduce_atlas for single-volume extraction

Examples

## 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)

Description

Downloads (if needed) and returns the Brainnetome 246-region label table used by get_brainnetome_atlas().

Usage

brainnetome_labels(use_cache = TRUE)

Arguments

Details

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.

Value

A tibble with one row per parcel and columns for parcel id, label, hemisphere, lobe/gyrus, Yeo network membership, RGB colour, and cytoarchitectonic description.

Source

https://atlas.brainnetome.org/download.html

Examples

## Not run: 
labels <- brainnetome_labels()
head(labels)

## End(Not run)

Description

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.

Usage

build_brain_polygon_data(
  surfatlas,
  views,
  surface,
  projection_smooth = 0L,
  depth_cull = TRUE
)

Arguments

Value

A list with two elements:

polygons

Tibble of 2D projected polygon vertices with columns x, y, poly_id, parcel_id, label, hemi, view, panel.

boundaries

Tibble of boundary edges with columns x, y, xend, yend, panel.

Examples

## Not run: 
atlas <- get_schaefer_surfatlas(100)
polygons <- build_brain_polygon_data(atlas,
  views = "lateral",
  surface = "inflated"
)

## End(Not run)

Description

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.

Usage

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
)

Arguments

Value

A list with:

cluster_table

Cluster summary tibble.

cluster_parcels

Cluster-parcel overlap tibble.

cluster_ts

Sample-level cluster signal tibble.

cluster_voxels

Named list of voxel coordinate matrices by cluster ID.

cluster_index

A NeuroVol of global cluster IDs.

sample_table

Normalized sample table with .sample_index.

prefetch_info

List describing whether eager signal prefetch was requested/applied and the effective guard thresholds.

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
samples <- array(rep(c(0.2, 0.7), 3), c(2, 1, 1, 3))
data_source <- neuroim2::NeuroVec(
  samples, neuroim2::NeuroSpace(dim(samples))
)
stat_map <- neuroim2::NeuroVol(array(c(4, 5), c(2, 1, 1)), grid)
clusters <- build_cluster_explorer_data(data_source, atlas, stat_map,
  threshold = 3, min_cluster_size = 1, tail = "positive"
)
clusters$cluster_table

Description

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\].

Usage

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
)

Arguments

Value

Tibble with columns 'from_idx', 'to_idx', 'from', 'to', and 'w'.

Examples

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"))

Description

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().

Usage

build_surface_polygon_data(
  surfatlas,
  views = c("lateral", "medial"),
  surface = "inflated",
  merged = TRUE,
  projection_smooth = 0L,
  use_cache = TRUE,
  depth_cull = TRUE
)

Arguments

Value

A list with components:

polygons

A tibble of projected polygon vertices.

boundaries

A tibble of projected boundary segments.

Examples

## Not run: 
atlas <- get_schaefer_surfatlas(100)
polygons <- build_surface_polygon_data(atlas, views = "lateral")
head(polygons$polygons)

## End(Not run)

Description

Checks whether the TemplateFlow R package is installed and provides cache information.

Usage

check_templateflow()

Value

Invisible NULL. Prints status information to the console.

Examples

check_templateflow()

Description

Removes cached files and clears in-memory memoisation.

Usage

clear_templateflow_cache(confirm = TRUE)

Arguments

Value

Invisibly returns 'TRUE' if the cache was cleared, 'FALSE' if aborted.

Examples

## Not run: 
clear_templateflow_cache()
clear_templateflow_cache(confirm = FALSE)

## End(Not run)

Description

Removes only transform artifact files owned by neuroatlas. The cache root is retained, and a cache containing an active artifact lock is refused.

Usage

clear_transform_cache(
  artifact_version = NULL,
  cache_dir = transform_cache_path()
)

Arguments

Value

The number of artifact files removed, invisibly.

Examples

cache <- tempfile("neuroatlas-example-cache-")
dir.create(cache)
clear_transform_cache(cache_dir = cache)
unlink(cache, recursive = TRUE)

Description

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.

Usage

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"
)

Arguments

Details

Calling cluster_explorer() with no arguments launches a synthetic demo dataset so the UI can be explored immediately.

Value

A shiny.appobj.

Examples

## Not run: 
app <- cluster_explorer()
# Start the interactive viewer with shiny::runApp(app).

## End(Not run)

Description

Character constants for standard neuroimaging coordinate spaces.

Usage

coord_spaces

Format

A named list with the following elements:

MNI305

FreeSurfer/Talairach space (fsaverage native)

MNI152

Broad MNI152 coordinate family, without template identity

SCANNER

Native scanner space (subject-specific)

UNKNOWN

Unknown or unspecified space

Examples

coord_spaces$MNI305
coord_spaces$MNI152

Description

Functions and constants for transforming coordinates between standard neuroimaging coordinate spaces, particularly MNI305 (fsaverage) and MNI152 (common fMRI template space).

Details

These legacy helpers classify broad coordinate families and apply a fixed FreeSurfer affine. They do not establish template-specific registration or cortical correspondence. Use exact MNI template identifiers and qualified transforms for image resampling or population cortical projection.

Value

This documentation topic describes legacy coordinate-family constants and affine helpers. Use exact template identifiers for qualified registration.

Coordinate Spaces

MNI305

FreeSurfer/Talairach space. Native space for fsaverage, fsaverage5, and fsaverage6 surfaces. Based on 305 subjects with linear registration to approximate Talairach space.

MNI152

A broad coordinate-family label. MNI152NLin6Asym and MNI152NLin2009cAsym are distinct templates; this shorthand does not identify either variant or a registration between them.

References

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

Examples

transform_coords(matrix(c(0, 0, 0), nrow = 1),
  from = "MNI305", to = "MNI152"
)

Description

**DEPRECATED:** TemplateFlow is now accessed via the pure R 'templateflow' package. No initialization is needed. Use [get_template()], [tflow_spaces()], and [tflow_files()] directly.

Usage

create_templateflow(cache_dir = NULL, verbosity = 0, default_template = NULL)

Arguments

Value

An S3 object of class templateflow (deprecated stub).

Examples

## Not run: 
# Deprecated. Use get_template(), tflow_spaces(), etc. directly.

## End(Not run)

Description

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.

Usage

dilate_atlas(atlas, mask, radius = 4, maxn = 50)

Arguments

Details

The dilation process:

• Identifies unassigned voxels that lie within the mask

• For each unassigned voxel, finds assigned voxels within radius (Euclidean distance, in voxel units)

• Assigns the voxel to a parcel by inverse-distance-weighted voting over those neighbours (up to maxn of them)

• Leaves a voxel unassigned when no parcel lies within radius, so distant in-mask voxels (e.g. cerebellar grey matter for a cortical atlas) are not absorbed

• 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.

Value

A ClusteredNeuroVol object containing the dilated parcellation. The object maintains the original label mappings but may include additional voxels in existing parcels.

References

The algorithm uses efficient k-d tree based nearest neighbor searches for spatial queries in 3D voxel space.

See Also

get_template_brainmask for creating appropriate masks from TemplateFlow

Examples

## 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)

Description

Subsets an atlas object to include only ROIs matching specified criteria. Uses non-standard evaluation (NSE) similar to dplyr::filter().

Usage

filter_atlas(x, ..., .dots = NULL)

## S3 method for class 'atlas'
filter_atlas(x, ..., .dots = NULL)

Arguments

Details

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. Surface-atlas subsetting is not implemented; use get_roi() to extract labelled surface regions.

Value

A new volume 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 data is also subset.

See Also

roi_metadata for viewing available filter columns, roi_attributes for listing available attributes, get_roi for extracting ROI data

Examples

## 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)

Description

A list including left and right hemispheres for the orig, white, inflated, and pial surfaces.

Usage

data(fsaverage)

Format

A named list with elements lh and rh, each containing surface geometry objects for orig, white, inflated, and pial surfaces.

Examples

data(fsaverage)
names(fsaverage)

Description

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.

Usage

get_aseg_atlas(outspace = NULL)

Arguments

Details

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)

Value

A list with classes 'aseg' and 'atlas' containing:

atlas

A NeuroVol object containing the 3D volume of atlas labels

cmap

A data frame with RGB color specifications for each region

ids

Integer vector of region IDs present in the atlas

labels

Character vector of anatomical labels corresponding to each ID

hemi

Character vector indicating hemisphere ('left', 'right', or NA) for each region

References

Fischl, B., et al. (2002). Whole brain segmentation: automated labeling of neuroanatomical structures in the human brain. Neuron, 33(3), 341-355.

See Also

map_atlas for mapping values onto atlas regions get_roi for extracting specific regions of interest

Examples

## 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)

Description

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.

Usage

get_atlas(name, ...)

Arguments

Value

The loaded atlas object (class depends on the loader).

See Also

[list_atlases()].

Examples

## 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)

Description

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.

Usage

get_brainnetome_atlas(outspace = NULL, smooth = FALSE, use_cache = TRUE)

Arguments

Details

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().

Value

A list with classes c("brainnetome", "volatlas", "atlas").

Source

https://atlas.brainnetome.org/download.html

References

Fan, L. et al. (2016). The Human Brainnetome Atlas: A New Brain Atlas Based on Connectional Architecture. Cerebral Cortex, 26(8), 3508-3526.

Examples

## Not run: 
atlas <- get_brainnetome_atlas()
atlas_ref(atlas)

## End(Not run)

Description

Creates a mixed-layout adapter with explicit hemisphere operators. The file cannot prove a registration identity: supplying an operator declares that its exact source domain matches the CIFTI vertex ordering. Counts are checked but never used to infer that binding. Noncortical models must retain the same indices and volume geometry; their rows may be reordered. Changed voxel grids or support require a separate volumetric operation and are rejected here.

Usage

get_cifti_transform(from, to, cortex, volume_space = NULL)

Arguments

Value

A CiftiTransform binding source/target layouts and cortical operators.

See Also

apply_cifti_transform(), read_cifti()

Examples

## Not run: 
op <- get_cifti_transform(source, reference, list(L = left, R = right),
  volume_space = "MNI152NLin6Asym"
)

## End(Not run)

Description

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.

Usage

get_fsl_atlas(
  name,
  fsl_dir = Sys.getenv("FSLDIR"),
  resolution = NULL,
  image = c("summary", "probability"),
  outspace = NULL,
  path_only = FALSE
)

Arguments

Value

An 'atlas' object, or a path/metadata list when 'path_only = TRUE'.

Examples

## Not run: 
# Requires an FSL installation configured through FSLDIR.
atlas <- get_fsl_atlas("harvard_oxford_cortical", resolution = 2)
atlas_ref(atlas)

## End(Not run)

Description

'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.

Usage

get_ggseg_atlas(atlas)

Arguments

Value

A ggseg brain atlas object for visualization (if ggsegSchaefer is installed).

Examples

# Deprecated — use plot_brain(schaefer_surf(200, 17)) instead

Description

Retrieves and loads a volumetric representation of the Glasser/HCP-MMP 1.0 cortical parcellation atlas.

Usage

get_glasser_atlas(outspace = NULL, source = c("xcpengine", "mni2009c"))

Arguments

Details

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.

Parcel IDs are representation-specific: volume IDs 1–180 refer to the right hemisphere ("hcp_R_first"), whereas glasser_surf() uses left-first IDs ("surfatlas_L_first"). For cross-representation tables, join on roi_metadata(atlas)$label_full ("L_V1_ROI", "R_V1_ROI", etc.), or on c("area", "hemi"). Both loaders expose these shared keys. Original source labels remain in orig_labels. ID-keyed tables must declare a matching id_convention column; see align_parcel_values().

Value

A list with class 'glasser' and 'atlas' containing:

name

Character string "Glasser360"

atlas

A ClusteredNeuroVol object containing the parcellation

cmap

Data frame with RGB color specifications for each region

ids

Integer vector of region IDs (1:360)

labels

Character vector of anatomical labels

hemi

Character vector indicating hemisphere ('left' or 'right')

Source

Source-specific links are recorded in atlas_ref(atlas)$provenance.

References

Glasser, M. F., et al. (2016). A multi-modal parcellation of human cerebral cortex. Nature, 536(7615), 171-178.

Examples

## 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)

Description

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'.

Usage

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(...)

Arguments

Value

An 'atlas' object, or path metadata when 'path_only = TRUE'.

Examples

## Not run: 
atlas <- get_harvard_oxford_atlas("cortical", threshold = 25)
atlas_ref(atlas)

## End(Not run)

Description

Load HCPex v1.1, a volumetric atlas with 360 cortical and 66 subcortical regions in the source-declared MNI152NLin2009cAsym template space.

Usage

get_hcpex_atlas(resolution = c("1", "2"), outspace = NULL, use_cache = TRUE)

Arguments

Details

Files are downloaded on demand from a pinned revision of the upstream v1.1 distribution. Both native resolutions retain the upstream voxel geometry and HCPex IDs (1:426, with zero as background). HCPex cortical ordering differs from the original HCP-MMP1.0 ordering; matrices in that ordering must be reordered before use with this atlas.

Labels combine upstream abbreviations with hemisphere suffixes (e.g., V1_L, V1_R). orig_labels preserves the full lookup-table names. roi_metadata() also includes region (the unsuffixed abbreviation) and division ("cortical" for IDs 1:360, "subcortical" for 361:426). The complete region catalogue is retained after resampling, even when some regions no longer have voxels. No surface representation is supplied.

The upstream data are distributed under GPL-3.0; their license, source revision, file receipts, and publication references are attached to the atlas.

Value

An object with classes hcpex and atlas, containing a NeuroVol, region IDs, labels, hemisphere assignments, RGB colors, and resource metadata.

Source

https://github.com/wayalan/HCPex, including the v1.1 user guide.

References

Huang CC, Rolls ET, Feng J, Lin CP (2022). An extended Human Connectome Project multimodal parcellation atlas of the human cortex and subcortical areas. Brain Structure and Function, 227, 763-778. doi:10.1007/s00429-021-02421-6

Huang CC, Rolls ET, Hsu CH, Feng J, Lin CP (2021). Extensive Cortical Connectivity of the Human Hippocampal Memory System: Beyond the "What" and "Where" Dual Stream Model. Cerebral Cortex. doi:10.1093/cercor/bhab113

See Also

get_atlas(), get_glasser_atlas(), atlas_citations()

Examples

## Not run: 
hcp <- get_hcpex_atlas(resolution = 2)
# Also available through get_atlas("hcpex", resolution = 2)
get_roi(hcp, label = "V1_L")
subcortex <- filter_atlas(hcp, division == "subcortical")
atlas_metadata(hcp)
atlas_citations(hcp)

## End(Not run)

Description

Creates a hippocampus-specific atlas from the Olsen MTL atlas, with optional anterior-posterior subdivisions.

Usage

get_hipp_atlas(outspace = NULL, apsections = 1)

Arguments

Details

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.

Value

A list with class c("hippocampus", "atlas") containing:

name

Character string "hippocampus"

atlas

NeuroVol object with hippocampal parcellation

ids

Integer vector of region IDs

labels

Character vector of region labels

hemi

Character vector of hemisphere designations

cmap

Matrix of RGB colors for visualization

orig_labels

Full labels including hemisphere information

Examples

## Not run: 
# Basic hippocampal atlas
hipp <- get_hipp_atlas()

# With anterior-posterior subdivisions
hipp_ap <- get_hipp_atlas(apsections = 3)

## End(Not run)

Description

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'.

Usage

get_julich_brain_atlas(fsl_dir = Sys.getenv("FSLDIR"), download = TRUE, ...)

Arguments

Value

An 'atlas' object, or path metadata when 'path_only = TRUE'.

Examples

## Not run: 
atlas <- get_julich_brain_atlas()
atlas_ref(atlas)

## End(Not run)

Description

Loads the Olsen medial temporal lobe atlas and optionally resamples it to a different space.

Usage

get_olsen_mtl(outspace = NULL)

Arguments

Value

A list with class 'atlas' containing the MTL parcellation

See Also

get_hipp_atlas for hippocampus-specific parcellation

Examples

# 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)

Description

Extracts a specific region of interest from an atlas object based on label, ID, and hemisphere information.

Usage

get_roi(x, label = NULL, id = NULL, hemi = NULL)

## S3 method for class 'atlas'
get_roi(x, label = NULL, id = NULL, hemi = NULL)

Arguments

Value

Returns a subset of the atlas containing only the specified ROI

Examples

## Not run: 
# Load the aseg atlas
atlas <- get_aseg_atlas()

# Extract the hippocampus ROI
roi <- get_roi(atlas, label = "Hippocampus")

## End(Not run)

Description

get_roi() method for surface atlases (class surfatlas, e.g. from get_wang_atlas, glasser_surf, or schaefer_surf). It returns one ROISurface per matched region, carrying the mesh vertices of that area on the appropriate hemisphere.

Because a surface atlas stores each hemisphere on its own mesh, a label present in both hemispheres yields one ROI per hemisphere, named "<label>_left" / "<label>_right"; pass hemi to restrict. When selecting by id, results are named by id (ids are unique across hemispheres: 1..K left, K+1..2K right).

Usage

## S3 method for class 'surfatlas'
get_roi(x, label = NULL, id = NULL, hemi = NULL)

Arguments

Value

A named list of ROISurface objects.

See Also

get_roi

Examples

## Not run: 
atlas <- get_schaefer_surfatlas(100)
roi <- get_roi(atlas, id = atlas$ids[1])

## End(Not run)

Description

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.

Usage

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,
  cache_dir = NULL
)

sy_100_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_100_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_200_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_200_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_300_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_300_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_400_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_400_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_500_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_500_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_600_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_600_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_700_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_700_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_800_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_800_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_900_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_900_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_1000_7(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

sy_1000_17(
  resolution = "2",
  outspace = NULL,
  smooth = FALSE,
  use_cache = TRUE,
  cache_dir = NULL,
  ...
)

Arguments

Details

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)

Value

A list with classes c("schaefer", "volatlas", "atlas") containing:

name

Character string identifying atlas version

atlas

ClusteredNeuroVol object containing the parcellation

cmap

Data frame with RGB colors for visualization

ids

Integer vector of region IDs

labels

Character vector of region names

orig_labels

Original region labels from source data

network

Network assignment for each region

hemi

Hemisphere designation for each region

Convenience Functions

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, cache_dir, 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.

Source

https://github.com/ThomasYeoLab/CBIG/

References

Schaefer, A., et al. (2018). Local-Global Parcellation of the Human Cerebral Cortex from Intrinsic Functional Connectivity MRI. Cerebral Cortex, 28(9), 3095-3114.

See Also

get_schaefer_surfatlas for surface-based version

Examples

## 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)

Description

Loads the surface-based version of the Schaefer parcellation atlas, compatible with FreeSurfer surface representations.

Usage

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
)

Arguments

Details

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.

Value

A list with classes c("schaefer", "surfatlas", "atlas") containing:

surf_type

Surface type used

lh_atlas

Left hemisphere surface atlas

rh_atlas

Right hemisphere surface atlas

name

Atlas identifier

cmap

RGB color specifications

ids

Region IDs

labels

Region names

orig_labels

Original region labels

network

Network assignments

hemi

Hemisphere designations

See Also

get_schaefer_atlas for volumetric version

Examples

## 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)

Description

Retrieve the affine transformation matrix for converting coordinates between two standard neuroimaging coordinate spaces.

Usage

get_space_transform(from, to)

Arguments

Value

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.

See Also

transform_coords, MNI305_to_MNI152

Examples

# 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))

Description

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.

Usage

get_subcortical_atlas(
  name,
  template_space = NULL,
  resolution = NULL,
  desc = NULL,
  outspace = NULL,
  use_cache = TRUE,
  path_only = FALSE,
  ...
)

Arguments

Value

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.

Examples

## 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)

Description

Determine which standard coordinate space a surface template's vertices are defined in.

Usage

get_surface_coordinate_space(template_id)

Arguments

Details

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.

Value

Character string indicating the coordinate space:

• "MNI305" for fsaverage variants (fsaverage, fsaverage5, fsaverage6)

• "MNI152" for fsLR (HCP template)

• "Unknown" for unrecognized templates

See Also

transform_coords, get_space_transform

Examples

get_surface_coordinate_space("fsaverage") # "MNI305"
get_surface_coordinate_space("fsaverage6") # "MNI305"
get_surface_coordinate_space("fsLR") # "MNI152"

Description

Downloads checksum-locked registration spheres, cortical masks and vertex areas from their original providers. Pinned fsaverage 164k, 41k (fsaverage6), 10k (fsaverage5), and fsLR 32k domains are supported. The fsLR sphere is in fsaverage correspondence. Inputs retain their upstream licenses, independently of neuroatlas's license; see 'extdata/surface-assets-LICENSES.md' in the installed package.

Usage

get_surface_geometry(
  template,
  density,
  hemisphere,
  cache_dir = transform_cache_path(),
  download = TRUE,
  offline = FALSE
)

Arguments

Value

A 'SurfaceGeometry' with exact domain identity, pinned input hashes, cortical mask, and upstream file provenance.

Examples

## Not run: 
left <- get_surface_geometry("fsaverage", "164k", "L")
target <- get_surface_geometry("fsLR", "32k", "L")
transform <- get_template_transform(left, target)
x <- surface_data(rep(0.25, left$domain$n_vertices), left$domain)
y <- apply_template_transform(x, transform)

## End(Not run)

Description

Uses pinned CBIG RF-ANTs population registration-fusion sampling coordinates on the exact fsaverage 164k domain. MNI2009c uses the qualified MNI6-to-2009c image pullback at those coordinates, without an intermediate resampled image. fsLR 32k output additionally uses the admitted native surface operator. Population correspondence does not substitute for subject registration. Numerical qualification covers the locked 1 mm and 2 mm source grids and the four pinned target domains. Other grids in the declared frame can be sampled, but have no retained grid-specific qualification. The original CBIG reference and MNI6 images agree on sampled cortical support, but differ elsewhere.

Usage

get_surface_projection(
  from,
  to,
  cache_dir = transform_cache_path(),
  download = TRUE,
  offline = FALSE
)

Arguments

Value

A directed 'SurfaceProjection', with resident sampling coordinates, exact domains, input hashes, engine identity and composition provenance.

Examples

## Not run: 
target <- get_surface_geometry("fsaverage", "164k", "L")
projection <- get_surface_projection("MNI152NLin6Asym", target)
volume <- get_template("MNI152NLin6Asym", resolution = 2)
cortex <- apply_surface_projection(volume, projection,
  source_space = "MNI152NLin6Asym", data_type = "continuous"
)

## End(Not run)

Description

Constructs ordinary native closest-point barycentric weights between explicit registered spheres. Source mask exclusion precedes row normalization; target masking follows it. No registration is fitted. Native geometric correctness and exact Workbench parity are distinct qualification claims. Arbitrary supplied geometries are always marked '"unqualified"'.

Usage

get_surface_transform(
  from,
  to,
  cache_dir = transform_cache_path(),
  offline = FALSE
)

Arguments

Value

A 'SurfaceTransform' with sparse weights, exact domains, engine fingerprint, integrity digest and directed provenance. Reverse resampling requires calling this function with swapped geometries; it is not an inverse.

See Also

[surface_geometry()], [surface_data()], [apply_surface_transform()]

Examples

sphere <- rbind(
  c(1, 0, 0), c(-1, 0, 0), c(0, 1, 0),
  c(0, -1, 0), c(0, 0, 1), c(0, 0, -1)
)
faces <- rbind(
  c(0, 2, 4), c(2, 1, 4), c(1, 3, 4), c(3, 0, 4),
  c(2, 0, 5), c(1, 2, 5), c(3, 1, 5), c(0, 3, 5)
)
cortex <- rep(TRUE, 6)
domain <- surface_domain(
  "toy", "L", "6v", sphere, faces, cortex,
  "analytic", "v1"
)
if (requireNamespace("neurotransform", quietly = TRUE) &&
  utils::packageVersion("neurotransform") >= "0.2.0") {
  geometry <- surface_geometry(domain, sphere, faces, cortex)
  operator <- get_surface_transform(geometry, geometry, cache_dir = NULL)
  values <- surface_data(seq(0, 0.5, length.out = 6), domain)
  apply_surface_transform(values, operator)
}

Description

Unified function to retrieve neuroimaging templates and related files from the TemplateFlow repository via the pure R templateflow package.

Usage

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
)

Arguments

Details

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.

Value

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', a 'SurfaceGeometry' with attached [template_metadata()].

Examples

## 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)

Description

Resolves an available image or exact-domain surface route and loads its verified artifacts. Two SurfaceGeometry endpoints select an admitted native surface operator. An exact MNI identifier and a pinned surface target select a directed population cortical projection. Equal domains require a verified diagonal operator with unit weights before admission as an identity. Planning and fitting are separate: this function never estimates a registration. Nonlinear routes must have a published checksum and a passing qualification record in space_transform_manifest().

Usage

get_template_transform(
  from,
  to,
  provider = c("auto", "neuroatlas", "templateflow"),
  download = TRUE,
  verify = TRUE,
  cache_dir = transform_cache_path(),
  offline = FALSE,
  cortex = NULL,
  volume_space = NULL
)

Arguments

Value

A template_transform containing the plan, files, pullback morphism, and artifact provenance. Its direction describes image movement; its morphism maps target coordinates into source coordinates for sampling. Surface routes return the operator from get_surface_transform() or the SurfaceProjection from get_surface_projection(). CIFTI layouts return a CiftiTransform from get_cifti_transform(), preserving noncortical geometry and support.

See Also

apply_template_transform(), transform_atlas()

Examples

if (requireNamespace("neurotransform", quietly = TRUE) &&
  requireNamespace("hdf5r", quietly = TRUE)) {
  get_template_transform("MNI152NLin6Asym", "MNI152NLin6Asym")
}

Description

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.

Usage

get_visfatlas(outspace = NULL, smooth = FALSE, use_cache = TRUE)

Arguments

Details

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.

Value

A list with classes c("visfatlas", "volatlas", "atlas").

Source

https://download.brainvoyager.com/data/visfAtlas.zip

References

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

See Also

get_wang_atlas, get_visual_atlas.

Examples

## Not run: 
visf <- get_visfatlas()
table(visf$hemi)
get_roi(visf, label = "lh_v1d_retinotopic")

## End(Not run)