Skip to contents

Create cortical atlas from a neuromaps annotation

Source: R/atlas_cortical.R
create_cortical_from_neuromaps.Rd

[Experimental]

Build a brain atlas directly from a neuromaps annotation. The annotation is downloaded via neuromapr::fetch_neuromaps_annotation().

Supports both surface (.func.gii) and volume (.nii/.nii.gz) annotations. Volume annotations in MNI152 space are automatically projected to fsaverage5 via FreeSurfer's mri_vol2surf.

Usage

create_cortical_from_neuromaps(
  source,
  desc,
  space = "fsaverage",
  density = "10k",
  hemisphere = c("rh", "lh"),
  views = c("lateral", "medial", "superior", "inferior"),
  verbose = get_verbose(),
  ...,
  label_table = NULL,
  breaks = NULL,
  atlas_name = NULL,
  output_dir = NULL,
  min_coverage = NULL,
  cleanup = NULL,
  skip_existing = NULL
)

Arguments

source

Neuromaps source identifier (e.g., "schaefer").

desc

Neuromaps descriptor key (e.g., "400Parcels7Networks").

space

Coordinate space. Defaults to "fsaverage".

density

Surface vertex density. Defaults to "10k".

hemisphere

Which hemispheres to include: "lh", "rh", or both.

views

Which views to include: "lateral", "medial", "superior", "inferior".

verbose

How much to print: 0 silent, 1 progress (the default), 2 adds FreeSurfer's own output. TRUE and FALSE mean 1 and 0. Falls back to options("ggseg.extra.verbose"), then GGSEG_EXTRA_VERBOSE.

...

Not used. Present so that a mistyped or misplaced argument is reported against this function rather than silently ignored; anything passed here is an error. Geometry is shaped after the build: see atlas_polish(), or atlas_simplify(), atlas_smooth() and atlas_dilate() individually.

label_table

Optional data.frame mapping parcel IDs to region names.

breaks

How to cut a continuous map into bins. One of:

  • NULL, the default: quantile bins, as many as Sturges' rule gives for the number of vertices (1 + log2(n)), kept between 5 and 20.

  • A single number: that many quantile bins.

  • Increasing numbers: the edges of the bins.

  • A function that takes the map's finite values and returns the edges, such as function(x) pretty(x, 6) for round, equal-width bins.

Quantile bins each hold about the same number of vertices. Both hemispheres are cut on the same edges, so a bin covers the same range of values on the left and on the right. Values outside edges you supply are left unknown, with a warning. Ignored for parcellation data.

atlas_name

Name for the atlas. If NULL, derived from the input filename. It also names the folder of intermediate files inside output_dir, so it must be a single name without path separators.

output_dir

Where to put the intermediate files. Defaults to tempdir(), from options("ggseg.extra.output_dir") or GGSEG_EXTRA_OUTPUT_DIR.

min_coverage

Smallest share of core labels that must end up with 2D geometry, between 0 and 1. A build that falls below it warns and names the labels that have no shape; the warning fires whatever verbose is set to, because a region that cannot be drawn is data loss rather than progress chatter. The build itself still returns, so a long pipeline is never thrown away over a threshold. Use 0 to turn the check off. Defaults to 0.8, or to options("ggseg.extra.min_coverage"), then GGSEG_EXTRA_MIN_COVERAGE.

cleanup

Remove the intermediate files afterwards. Default TRUE, from options("ggseg.extra.cleanup") or GGSEG_EXTRA_CLEANUP.

The intermediate files live in a folder named after the atlas inside output_dir, and the whole folder is removed. A build therefore refuses to start if that folder already holds files it did not write, since removing it would take them too. Choose another output_dir or atlas_name, or pass FALSE to build there and keep everything.

skip_existing

Reuse a step's intermediate files when they already exist, instead of running the step. Default FALSE, from options("ggseg.extra.skip_existing") or GGSEG_EXTRA_SKIP_EXISTING.

A cache records which ggseg.extra wrote it, not what it was built from, so reuse cannot tell that the volume or lookup table has changed. Reuse is therefore asked for rather than assumed, and is reported when it happens. To continue an interrupted build, either pass TRUE or leave the finished steps out of steps.

Value

A ggseg_atlas object of type "cortical" containing region metadata (core), vertex indices for 3D rendering, a colour palette, and sf geometry for 2D plots.

See also

atlas_polish() to simplify and round off the result, which most builds want next.

Other atlas creation: create_cerebellar_from_annotation(), create_cerebellar_from_gifti(), create_cerebellar_from_volume(), create_cortical_from_annotation(), create_cortical_from_cifti(), create_cortical_from_gifti(), create_cortical_from_labels(), create_subcortical_from_volume(), create_tract_from_tractography(), create_tract_from_volume(), create_wholebrain_from_volume()

Examples

if (FALSE) { # \dontrun{
atlas <- create_cortical_from_neuromaps(
  source = "abagen",
  desc = "genepc1",
  breaks = 7
)
} # }