Package 'ggseg.formats'

Description

Coerce to ggseg atlas

Usage

as_ggseg_atlas(x)

as_brain_atlas(x)

Arguments

Value

an object of class 'ggseg_atlas'

Examples

atlas <- as_ggseg_atlas(dk())
is_ggseg_atlas(atlas)

Description

Sets the single geom slot to the brain_polygons representation, converting from sf if needed. The result renders identically via the geom_polygon-based path in ggseg, but no longer depends on the sf class machinery in ⁠$data⁠ — useful for wasm builds and air-gapped installs.

Usage

as_polygon_atlas(atlas)

Arguments

Details

A single representation is kept (no redundant sf alongside polygons). To rehydrate sf for geometric operations later, use as_sf_atlas(). Extra geometry columns are carried over; only columns named x, y, group or subgroup cannot be, since the nested coordinate table reserves those names, and they are dropped with a warning.

This doubles as the backward-compatible path for sf-optional installs: a lite-only ggseg that meets a still-sf-backed atlas converts it on the fly when sf is installed. When sf is not installed the geometry cannot be read, so the call aborts with a pointer to migrate_atlas_files() — which the atlas maintainer runs once (on a machine with sf) to ship the package in the polygon format.

Value

A ggseg_atlas whose ⁠$data$geom⁠ is a brain_polygons object.

Examples

poly <- as_polygon_atlas(dk())
is_atlas_polygon(poly) # TRUE

Description

Inverse of as_polygon_atlas(). Sets the single geom slot to an sf-class geometry table, converting from polygons via sfheaders::sf_multipolygon() if needed — sfheaders is pure Rcpp with no GDAL/GEOS/PROJ dependencies, so the conversion itself does not require a full sf installation. Use this when you want to run sf operations (buffers, intersections, CRS transforms) on atlas geometry; those sf operations themselves still require sf.

Usage

as_sf_atlas(atlas)

Arguments

Details

A single representation is kept (no redundant polygons alongside sf). Extra geometry columns are carried over; because an sf row covers a whole label×view feature, a column that varies within one feature keeps only its first value there.

Value

A ggseg_atlas whose ⁠$data$geom⁠ is an sf object.

Examples

atlas <- as_sf_atlas(as_polygon_atlas(dk()))
sf::st_buffer(atlas_geom(atlas)$geometry[[1]], dist = 2)

Description

Returns the FreeSurfer automatic subcortical segmentation (aseg) atlas containing deep brain structures including the thalamus, caudate, putamen, pallidum, hippocampus, amygdala, accumbens, and ventricles.

Usage

aseg()

Details

This atlas is derived from FreeSurfer's aseg.mgz volumetric segmentation. It works with both ggseg (2D slice views) and ggseg3d (3D mesh visualizations) from a single object.

Value

A ggseg_atlas object with components:

atlas

Character. Atlas name ("aseg")

type

Character. Atlas type ("subcortical")

palette

Named character vector of colours for each region

data

A ggseg_data_subcortical object containing:

meshes

Data frame with label and mesh columns

sf

Simple features data frame for 2D rendering

Core columns

core carries one row per atlas region with the columns hemi, region, label and names, plus the atlas's own grouping column. label is the stable atlas identifier and the key the palette and the geometry are keyed on; region is a short, hemisphere-free key derived from it; names is the curated long-form display name, spelled out to read well in a figure legend.

region held the long-form name until version 0.1.0. names is not a record of those old values – use legacy_region_map() to translate them.

Structures

The atlas contains bilateral structures:

• Thalamus

• Caudate

• Putamen

• Pallidum (globus pallidus)

• Hippocampus

• Amygdala

• Accumbens (nucleus accumbens)

• Ventral diencephalon

Plus midline and ventricular structures:

• Lateral ventricles

• Third ventricle

• Fourth ventricle

• Brain stem

• Cerebellar cortex

• Cerebellar white matter

References

Fischl B, Salat DH, Busa E, et al. (2002). Whole brain segmentation: automated labeling of neuroanatomical structures in the human brain. Neuron, 33(3):341-355. doi:10.1016/S0896-6273(02)00569-X

See Also

dk() for cortical parcellation, ggseg_atlas() for the atlas class constructor

Other ggseg_atlases: dk(), suit(), tracula()

Examples

aseg()
plot(aseg())
atlas_regions(aseg())

Description

The companion to is_ggseg_atlas() for code that cannot continue without a valid atlas. The predicate answers a yes/no question and so has nothing to say about why an object failed; callers that turned that FALSE into an error could only report the class, which is the one thing that was usually fine. assert_ggseg_atlas() separates the two failure kinds:

Usage

assert_ggseg_atlas(x, arg = rlang::caller_arg(x), call = rlang::caller_env())

Arguments

Details

• A wrong class is reported as a wrong class.

• A ggseg_atlas whose parts do not satisfy the schema aborts with the ggseg_atlas() constructor's own diagnostic, chained as the parent error, so the reader sees the missing column, the duplicated label or the mismatched data class instead of a message about the class tag.

Prefer this wherever a bad atlas would otherwise propagate; keep is_ggseg_atlas() for control flow, where signalling is wrong.

Value

x, invisibly, when it is a valid atlas. Aborts otherwise.

Examples

atlas <- assert_ggseg_atlas(dk())

broken <- dk()
broken$core$label <- NULL
try(assert_ggseg_atlas(broken))

Description

Returns the centerline of each tract, joined with core region info and palette colours. Tract atlases represent each pathway as a curve through the bundle rather than as a surface, and render it by sweeping a tube along that curve, so the centerline — not a mesh — is the geometry that defines them.

Usage

atlas_centerlines(atlas)

Arguments

Value

A ggseg_centerlines data.frame with one row per tract, a points list-column of n x 3 coordinate matrices and a matching tangents list-column

See Also

Other atlas accessors: atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

centerlines <- atlas_centerlines(tracula())
nrow(centerlines)
dim(centerlines$points[[1]])

Description

The display column of core holds the long-form, human-readable name of each region, as against the short key in region and the atlas identifier in label. For the atlases bundled here it is also the region value shipped before the 0.1.0 re-keying, which is what makes that re-keying recoverable; see legacy_region_map().

Usage

atlas_display(x)

Arguments

Value

The display column of core, unchanged: one element per core row, in core row order, with repeats and NAs retained. It is therefore row-aligned with atlas_regions() and atlas_labels(). Use unique() for the distinct set. A zero-length character vector when the atlas carries no display column.

See Also

atlas_regions(), atlas_labels(), legacy_region_map()

Other atlas accessors: atlas_centerlines(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

atlas_display(dk())
atlas_display(aseg())

Description

Returns the single 2D geometry object stored in atlas$data$geom, which is either an sf-class data frame or a brain_polygons data.frame. Its class determines which rendering path is used downstream.

Usage

atlas_geom(atlas)

Arguments

Details

For backward compatibility with released atlases built before the unified geom slot, this falls back to the legacy sf slot. Reverse dependencies should call this accessor (or atlas_sf() / atlas_polygons()) rather than reaching into atlas$data directly.

Value

an sf or brain_polygons object, or NULL if the atlas has no 2D geometry

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

g <- atlas_geom(dk())
atlas_geometry_type(dk())

Description

Classify or test an atlas's 2D geometry

Usage

atlas_geometry_type(atlas)

is_atlas_sf(atlas)

is_atlas_polygon(atlas)

Arguments

Value

atlas_geometry_type() returns "sf" or "polygon", and errors if the atlas has no recognised 2D geometry. is_atlas_sf() / is_atlas_polygon() return a logical scalar (FALSE for non-atlases).

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

atlas_geometry_type(dk())
is_atlas_polygon(dk())

Description

hemi records which side of the brain a row sits on, as one of "left", "right" or "midline", or NA where a side does not apply. It is a closed vocabulary, enforced at construction, because it is what consumers filter and facet on.

Usage

atlas_hemi(x)

Arguments

Value

The hemi column of core, unchanged: one element per core row, in core row order, with repeats and NAs retained. A zero-length character vector when the atlas carries no hemi column.

See Also

atlas_regions(), atlas_labels(), atlas_display()

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

unique(atlas_hemi(dk()))
unique(atlas_hemi(suit()))

Description

Extract the label column of an atlas

Usage

atlas_labels(x)

brain_labels(x)

Arguments

Value

The label column of core, unchanged: one element per core row, in core row order, with repeats and NAs retained. It is therefore row-aligned with atlas_regions() and atlas_display(). Use unique() for the distinct set. A zero-length character vector when the atlas carries no label column.

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

atlas_labels(dk())
atlas_labels(aseg())

Description

Functions for modifying brain atlas objects. These cover three areas:

Usage

atlas_region_remove(atlas, pattern, match_on = c("label", "region"))

atlas_region_contextual(
  atlas,
  pattern,
  match_on = c("label", "region"),
  ignore.case = TRUE
)

atlas_region_op(
  atlas,
  x,
  y,
  action = c("difference", "intersection", "union", "symdifference"),
  into = NULL,
  match_on = c("label", "region"),
  colour = NULL
)

atlas_context_remove(atlas)

atlas_region_rename(
  atlas,
  pattern,
  replacement,
  match_on = c("label", "region")
)

atlas_region_keep(atlas, pattern, match_on = c("label", "region"))

atlas_core_add(atlas, data, by = "region")

atlas_view_remove(atlas, views)

atlas_view_keep(atlas, views)

atlas_view_remove_region(
  atlas,
  pattern,
  match_on = c("label", "region"),
  views = NULL
)

atlas_view_remove_small(
  atlas,
  min_area,
  views = NULL,
  scope = c("region", "piece"),
  labels = NULL,
  exclude = NULL
)

atlas_view_select(atlas, threshold = 0.5, weights = NULL)

atlas_view_gather(atlas, gap = 0.15)

atlas_view_reorder(atlas, order, gap = 0.15)

Arguments

Details

Region manipulation modifies which regions are active in the atlas:

• atlas_region_remove(): completely remove regions

• atlas_region_contextual(): keep geometry but remove from core/palette

• atlas_context_remove(): drop all contextual sf geometry

• atlas_region_rename(): rename regions in core

• atlas_region_keep(): keep only matching regions

• atlas_region_op(): combine two regions' geometry with a boolean op (difference / intersection / union / symdifference)

View manipulation modifies the 2D sf geometry data:

• atlas_view_remove(): remove entire views

• atlas_view_keep(): keep only matching views

• atlas_view_remove_region(): remove specific region geometry from sf

• atlas_view_remove_small(): remove small regions, or stray specks

• atlas_view_select(): keep each region only in the views that show it well

• atlas_view_gather(): reposition views to close gaps

• atlas_view_reorder(): change view order

Core manipulation modifies atlas metadata:

• atlas_core_add(): join additional metadata columns

Value

Modified ggseg_atlas object

Functions

• atlas_region_contextual(): Keep geometry for visual context but remove from core, palette, and 3D data. Context geometries render grey and don't appear in legends. Contextual rows are moved behind the remaining core regions so focus regions draw on top where they overlap in projection. Operates on whichever 2D representation the atlas carries (sf and/or polygons), keeping both in sync, and needs no sf for a polygon atlas.

• atlas_region_op(): Combine two sets of region geometry with a vector boolean operation (per view), writing the result to a new region into. x and y are patterns matched against match_on; within each view their matching geometries are unioned, then combined via action: "difference" (x minus y, e.g. punching white matter out of a cortex silhouette), "intersection", "union", or "symdifference". Inputs are left in place; any existing into geometry is replaced. With a colour, into becomes a legended core region; otherwise it stays contextual (grey) and is drawn behind the core regions. Boolean ops need a geometry engine, so this is the one manipulation helper that always requires sf installed; a polygon-only atlas is rehydrated for the operation and the result is returned in polygon form.

• atlas_context_remove(): Drop all contextual sf geometry — every sf row whose label is not present in core. Covers labels marked via atlas_region_contextual() plus pipeline-generated outlines (cortex_, Background, unknown). Remaining views are re-packed via atlas_view_gather() so the plot focuses tightly on the labelled regions.

• atlas_region_rename(): Rename regions matching a pattern. Only ever writes to the region column, never to label. match_on chooses the rows: those whose label (the default) or region matches pattern. The edit is always made to the region text those rows already have. A string replacement is substituted for pattern wherever the region contains it, so atlas_region_rename(atlas, "Left-", "") strips the prefix from regions that still carry it. A function replacement receives the regions of the matching rows and returns the new ones, which is how to set a region outright for a label: ⁠atlas_region_rename(atlas, "^Brain-Stem$", \(region) "brainstem")⁠. A string that changes nothing, because the pattern is in the labels but not in their regions, is reported with a warning.

• atlas_region_keep(): Keep only matching regions. Non-matching regions are removed from core, palette, and 3D data but sf geometry is preserved for surface continuity.

• atlas_core_add(): Join additional metadata columns to atlas core.

• atlas_view_remove(): Remove views matching pattern from sf data. Remaining views are re-packed via atlas_view_gather() so the layout stays tight.

• atlas_view_keep(): Keep only views matching pattern.

• atlas_view_remove_region(): Remove specific region geometry from sf data only. Core, palette, and 3D data are unchanged. Views are re-packed via atlas_view_gather() in case any view shrank.

• atlas_view_remove_small(): Remove geometry below a minimum area threshold. With scope = "region" (the default) a label's whole geometry in a view is removed when its combined area is too small, and context geometries (labels not in core) are never removed. With scope = "piece" individual disconnected pieces are removed while the rest of the region stays – use this to clear stray specks left by volumetric projection. A region's largest piece in a view is always kept, so no region disappears, and context is cleaned too. Optionally scope to specific views. Views are re-packed via atlas_view_gather() in case any view shrank.

• atlas_view_select(): Keep each region only in the views that show it well.

  A slice or projection slab catches a structure in cross-section as readily as along its length, so most regions leave a sliver in most views. That leaves every panel cluttered and every region drawn several times over. A region is kept only where it is substantially represented: in any view holding at least threshold of the area it reaches in its best view.

  Regions are compared as a whole, across all the labels that share a region in core, so bilateral structures stay together – assigning left and right independently splits pairs across panels, which reads as an error rather than a choice. Every region is guaranteed to survive in at least one view, and context geometry (labels absent from core, such as a cortical outline) is never touched.

  Single-hemisphere views are the awkward case: a sagittal panel cuts one hemisphere while axial and coronal panels show both, so on raw area it loses every comparison and empties out. Such views are detected from the hemispheres actually present in each view and their areas scaled to match, so they compete fairly. Pass weights to override.

• atlas_view_gather(): Reposition remaining views to close gaps after view removal.

• atlas_view_reorder(): Reorder views and reposition. Views not in order are appended at end.

See Also

Other atlas manipulations: atlas_structure_reorder(), relabel_atlas()

Examples

dk() |>
  atlas_region_remove("bankssts") |>
  atlas_region_keep("frontal")

Description

Returns meshes data joined with core region info and palette colours. Used for subcortical and tract atlases.

Usage

atlas_meshes(atlas)

Arguments

Value

data.frame with meshes ready for 3D rendering

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

meshes <- atlas_meshes(aseg())
head(meshes)

Description

Retrieves the colour palette from a brain atlas: a named character vector mapping region labels to colours. To change the palette, use the set_atlas_palette() setter.

Usage

atlas_palette(atlas, ...)

Arguments

Value

Named character vector of colours.

See Also

set_atlas_palette() to set the palette.

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

atlas_palette(aseg())
atlas_palette(dk())

Description

Returns the atlas palette when it can tell the atlas's regions apart, and otherwise a palette of automatically assigned, distinguishable colours. Use this instead of reading atlas$palette directly whenever the palette is about to be drawn: some atlases are built from colour lookup tables that give every region the same colour (often black), and rendering those faithfully produces a solid silhouette in which no region can be told from its neighbours.

Usage

atlas_plot_palette(atlas)

Arguments

Details

A palette is treated as unusable when every one of the atlas's regions resolves to a single colour. Contextual geometry – the cortex_ silhouette and the unknown medial wall – is excluded from that judgement and keeps its conventional grey in the fallback, so backdrop is never mistaken for a parcel. Atlases with a single region, and palettes that are merely dark but varied, are left untouched: this replaces palettes that cannot be read, not palettes that are unusual.

Falling back warns, naming the atlas, because the fix belongs in the atlas's colour lookup table. An atlas carrying no palette at all is a supported, expected state rather than a broken table, so it falls back silently.

Value

Named character vector of colours keyed by label.

See Also

atlas_palette() for the palette exactly as stored.

Examples

# A well-formed palette comes back untouched
identical(atlas_plot_palette(dk()), atlas_palette(dk()))

Description

Returns the brain_polygons representation of the atlas geometry, converting from sf when needed. The sf-optional counterpart to atlas_sf().

Usage

atlas_polygons(atlas)

Arguments

Value

a brain_polygons data.frame

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

polys <- atlas_polygons(dk())

Description

Extract the region column of an atlas

Usage

atlas_regions(x)

brain_regions(x)

Arguments

Value

The region column of core, unchanged: one element per core row, in core row order, with repeats and NAs retained. It is therefore row-aligned with atlas_labels() and atlas_display(). Use unique() for the distinct set. A zero-length character vector when the atlas carries no region column.

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

atlas_regions(dk())
atlas_regions(aseg())

Description

Returns sf data joined with core region info and palette colours. This is the interception point used by ggseg for plotting: it always returns sf geometry, converting from the polygon representation when needed.

Usage

atlas_sf(atlas)

Arguments

Value

sf data.frame ready for plotting

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_type(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

sf_data <- atlas_sf(dk())
head(sf_data)

Description

Moves structures within an atlas's geometry, the way dplyr::relocate() moves columns. Geometry rows are drawn in the order they appear, so this is what decides which structure is painted over which where two overlap.

Overlap is common in subcortical atlases: a slab is a thick slice of the volume flattened into one panel, so structures that never touch in the brain can still overlap on the page.

Usage

atlas_structure_reorder(
  atlas,
  structures,
  .before = NULL,
  .after = NULL,
  match_on = c("label", "region")
)

Arguments

Details

Later rows are drawn on top. With neither .before nor .after, the structures move to the front, matching dplyr::relocate(), which means they are drawn first, and so end up behind everything else. To bring a structure to the front visually, move it after the last one.

The order is a property of the structure, not of a single view: an atlas holds one geometry row per structure with its views nested inside, so a structure keeps the same depth in every view it appears in.

Value

The ggseg_atlas, with its geometry rows in the new order.

See Also

atlas_view_reorder(), which moves whole views around the canvas rather than structures within them.

Other atlas manipulations: atlas_manipulation, relabel_atlas()

Examples

a <- aseg()

# Draw the thalamus on top of everything else
last <- utils::tail(atlas_labels(a), 1)
a <- atlas_structure_reorder(a, "Left-Thalamus", .after = last)

# Or tuck it behind its neighbours
a <- atlas_structure_reorder(a, "Left-Thalamus", .before = "Left-Putamen")

Description

Detect atlas type

Usage

atlas_type(x)

Arguments

Value

Character string: one of "cortical", "subcortical", "tract" or "cerebellar".

See Also

set_atlas_type() to set the type.

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_vertices(), atlas_views(), legacy_region_map()

Examples

atlas_type(dk())
atlas_type(aseg())
atlas_type(tracula())

Description

Returns vertices data joined with core region info and palette colours. Used for cortical atlases with vertex-based rendering.

Usage

atlas_vertices(atlas)

Arguments

Value

data.frame with vertices ready for 3D rendering

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_views(), legacy_region_map()

Examples

verts <- atlas_vertices(dk())
head(verts)

Description

Get available views in atlas

Usage

atlas_views(atlas)

brain_views(atlas)

Arguments

Value

Character vector of view names, or NULL if no sf data

See Also

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), legacy_region_map()

Examples

atlas_views(aseg())
atlas_views(tracula())

Description

Convert old-style ggseg (2D) and ggseg3d (3D) atlases into the new ggseg_atlas format. This is a bridge function for working with existing atlases during the transition period.

For new atlases, use ggsegExtra::create_cortical_atlas() or ggsegExtra::create_subcortical_atlas() instead - they produce better results with proper vertex indices.

The function handles three scenarios:

• Both 2D and 3D: Merges geometry with vertex data

• 3D only: Extracts vertices, infers indices from mesh coordinates

• 2D only: Keeps geometry, 3D rendering unavailable

If the 3D atlas already contains vertex indices (newer ggseg3d atlases), those are preserved. Otherwise, vertex indices are inferred from mesh coordinates using hash-based matching (no FreeSurfer needed).

Usage

convert_legacy_brain_atlas(
  atlas_2d = NULL,
  atlas_3d = NULL,
  atlas_name = NULL,
  type = NULL,
  surface = "inflated",
  brain_meshes = NULL
)

unify_legacy_atlases(
  atlas_2d = NULL,
  atlas_3d = NULL,
  atlas_name = NULL,
  type = NULL,
  surface = "inflated",
  brain_meshes = NULL
)

Arguments

Value

A ggseg_atlas object.

Examples

new_atlas <- convert_legacy_brain_atlas(atlas_2d = dk())

Description

Returns the Desikan-Killiany cortical parcellation atlas with 34 regions per hemisphere (68 total) on the cortical surface.

Usage

dk()

Details

This atlas is based on the FreeSurfer aparc annotation and is one of the most widely used cortical parcellations in neuroimaging research.

The atlas works with both ggseg (2D polygon plots) and ggseg3d (3D mesh visualizations) from a single object.

Value

A ggseg_atlas object with components:

atlas

Character. Atlas name ("dk")

type

Character. Atlas type ("cortical")

palette

Named character vector of colours for each region

data

A ggseg_data_cortical object containing:

vertices

Data frame with label and vertices columns

sf

Simple features data frame for 2D rendering

Core columns

core carries one row per atlas region with the columns hemi, region, label and names, plus the atlas's own grouping column. label is the stable atlas identifier and the key the palette and the geometry are keyed on; region is a short, hemisphere-free key derived from it; names is the curated long-form display name, spelled out to read well in a figure legend.

region held the long-form name until version 0.1.0. names is not a record of those old values – use legacy_region_map() to translate them.

Regions

The atlas contains 34 regions per hemisphere including: banks of superior temporal sulcus, caudal anterior cingulate, caudal middle frontal, cuneus, entorhinal, fusiform, inferior parietal, inferior temporal, isthmus cingulate, lateral occipital, lateral orbitofrontal, lingual, medial orbitofrontal, middle temporal, parahippocampal, paracentral, pars opercularis, pars orbitalis, pars triangularis, pericalcarine, postcentral, posterior cingulate, precentral, precuneus, rostral anterior cingulate, rostral middle frontal, superior frontal, superior parietal, superior temporal, supramarginal, frontal pole, temporal pole, transverse temporal, and insula.

References

Desikan RS, Segonne F, Fischl B, et al. (2006). An automated labeling system for subdividing the human cerebral cortex on MRI scans into gyral based regions of interest. NeuroImage, 31(3):968-980. doi:10.1016/j.neuroimage.2006.01.021

Fischl B, van der Kouwe A, Destrieux C, et al. (2004). Automatically parcellating the human cerebral cortex. Cerebral Cortex, 14(1):11-22. doi:10.1093/cercor/bhg087

See Also

aseg() for subcortical structures, ggseg_atlas() for the atlas class constructor

Other ggseg_atlases: aseg(), suit(), tracula()

Examples

dk()
plot(dk())
atlas_regions(dk())
atlas_labels(dk())

Description

Retrieves a brain surface mesh for the specified hemisphere and surface type. By default, provides the inflated fsaverage5 surface from internal data. Other surfaces (pial, white, semi-inflated) require the ggseg3d package.

Usage

get_brain_mesh(
  hemisphere = c("lh", "rh"),
  surface = "inflated",
  brain_meshes = NULL
)

Arguments

Value

A list with vertices (data.frame with x, y, z) and faces (data.frame with i, j, k), or NULL if the mesh is not available. The face indices of the bundled inflated surfaces are 0-based (0 to nrow(vertices) - 1), matching get_cerebellar_mesh(). Per-region subcortical meshes from ggseg_data_subcortical() are 1-based instead, and a user-supplied brain_meshes is returned exactly as given, so a consumer must not assume a single base across mesh sources.

Examples

mesh <- get_brain_mesh("lh")
head(mesh$vertices)

Description

Retrieves the shared SUIT cerebellar surface mesh used for vertex-based cerebellar atlas rendering. The mesh contains 28,935 original surface vertices plus 1,078 additional vertices forming a cap over the peduncular surface (where the cerebellum meets the brainstem). The cap vertices (indices 28,935–30,012) are duplicates of the boundary loop and a centroid, designed to render as an opaque grey wall when not assigned to any atlas region.

Usage

get_cerebellar_mesh()

Value

A list with vertices (data.frame with x, y, z) and faces (data.frame with i, j, k, 0-based indices).

Examples

mesh <- get_cerebellar_mesh()
nrow(mesh$vertices)

Description

Creates an object of class 'ggseg_atlas' for plotting brain parcellations using ggseg (2D) and ggseg3d (3D).

Usage

ggseg_atlas(atlas, type, core, data, palette = NULL)

brain_atlas(atlas, type, core, data, palette = NULL)

Arguments

Value

an object of class 'ggseg_atlas'

Examples

core <- data.frame(
  hemi = c("left", "left"),
  region = c("region1", "region2"),
  label = c("lh_region1", "lh_region2")
)
vertices <- data.frame(
  label = c("lh_region1", "lh_region2"),
  vertices = I(list(c(1L, 2L, 3L), c(4L, 5L, 6L)))
)
atlas <- ggseg_atlas(
  atlas = "test",
  type = "cortical",
  core = core,
  data = ggseg_data_cortical(vertices = vertices)
)

Description

Creates a data object for cerebellar brain atlases. Cerebellar atlases use sf polygons from a SUIT flatmap for 2D rendering and vertex indices into the shared SUIT cerebellar surface mesh for 3D rendering.

Usage

ggseg_data_cerebellar(geom = NULL, vertices = NULL, meshes = NULL, ...)

Arguments

Details

The shared mesh (see get_cerebellar_mesh()) includes a cap over the peduncular surface where the cerebellum meets the brainstem. Vertices on this cap (indices 28,935–30,012) are not assigned to any atlas region and render as na_colour in 3D, analogous to the medial wall in cortical atlases.

Deep cerebellar structures (e.g. dentate, interposed, fastigial nuclei) that are not on the cortical surface are stored as individual per-region meshes in meshes, following the same format as subcortical atlases. Their 2D sf geometries use views other than "flatmap" (e.g. "nuclei").

Value

An object of class c("ggseg_data_cerebellar", "ggseg_atlas_data")

Examples

data <- ggseg_data_cerebellar(
  vertices = data.frame(
    label = c("lobule_I", "lobule_II"),
    vertices = I(list(c(1L, 2L, 3L), c(4L, 5L, 6L)))
  )
)

Description

Creates a data object for cortical brain atlases. Cortical atlases use vertex indices that map regions to vertices on a shared brain surface mesh (e.g., fsaverage5).

Usage

ggseg_data_cortical(geom = NULL, vertices = NULL, ...)

brain_data_cortical(sf = NULL, vertices = NULL)

Arguments

Value

An object of class c("ggseg_data_cortical", "ggseg_atlas_data")

Examples

data <- ggseg_data_cortical(
  vertices = data.frame(
    label = c("bankssts", "caudalanteriorcingulate"),
    vertices = I(list(c(1L, 2L, 3L), c(4L, 5L, 6L)))
  )
)

Description

Creates a data object for subcortical brain atlases. Subcortical atlases use individual 3D meshes for each structure (e.g., hippocampus, amygdala).

Usage

ggseg_data_subcortical(geom = NULL, meshes = NULL, ...)

brain_data_subcortical(sf = NULL, meshes = NULL)

Arguments

Value

An object of class c("ggseg_data_subcortical", "ggseg_atlas_data")

Examples

data <- ggseg_data_subcortical(
  meshes = data.frame(
    label = "hippocampus_left",
    mesh = I(list(list(
      vertices = data.frame(x = 1:10, y = 1:10, z = 1:10),
      faces = data.frame(i = 1:3, j = 2:4, k = 3:5)
    )))
  )
)

Description

Creates a data object for white matter tract atlases. Stores centerlines compactly; tube meshes are generated at render time for efficiency.

Usage

ggseg_data_tract(geom = NULL, centerlines = NULL, meshes = NULL, ...)

brain_data_tract(sf = NULL, centerlines = NULL, meshes = NULL, ...)

Arguments

Value

An object of class c("ggseg_data_tract", "ggseg_atlas_data")

Examples

centerlines_df <- data.frame(
  label = "cst_left",
  points = I(list(matrix(rnorm(150), ncol = 3))),
  tangents = I(list(matrix(rnorm(150), ncol = 3)))
)
data <- ggseg_data_tract(centerlines = centerlines_df)

Description

These functions check both the class tag and structural validity by passing the object through ggseg_atlas(). An object that carries the right class but fails validation returns FALSE.

Usage

is_ggseg_atlas(x)

is_cortical_atlas(x)

is_subcortical_atlas(x)

is_tract_atlas(x)

is_cerebellar_atlas(x)

is_brain_atlas(x)

Arguments

Value

logical

See Also

assert_ggseg_atlas(), which aborts with the reason instead of reducing it to FALSE.

Examples

is_ggseg_atlas(dk())
is_cortical_atlas(dk())
is_subcortical_atlas(aseg())
is_tract_atlas(tracula())

Description

Check if object is a legacy ggseg3d atlas

Usage

is_ggseg3d_atlas(x)

Arguments

Value

logical

Examples

is_ggseg3d_atlas(dk())

Description

Before version 0.1.0 the region column of the bundled atlases held a long-form display name. From 0.1.0 it holds a short, hemisphere-free key derived from label, and the long-form name lives in display. Joins and filters written against the old values therefore match nothing and fail silently: merge(all.x = TRUE) and the ggseg fill scale both yield NA, which draws as a blank parcel rather than raising an error.

Usage

legacy_region_map(atlas)

Arguments

Details

This returns the translation between the two, so old code can be updated mechanically:

map <- legacy_region_map(dk())
my_data$region <- unname(map[my_data$region])

The mapping comes from a table of exactly what each bundled atlas shipped at 0.0.4, not from the atlas's current display column – display is the curated display name and several 0.0.4 region values were mechanically derived ("ventraldc", "cc posterior"), so the two are deliberately not the same. Where two old names shared one label, as "Thalamus" and "Thalamus Proper" did in aseg, both still translate even though the alias row itself is gone from core.

Value

A named character vector whose names are the pre-0.1.0 region values and whose values are the current region keys. Zero-length for an atlas this package ships no legacy table for, which is every atlas except the bundled four.

See Also

atlas_display() for the curated display names, atlas_regions() for the current keys.

Other atlas accessors: atlas_centerlines(), atlas_display(), atlas_geom(), atlas_geometry_type(), atlas_hemi(), atlas_labels(), atlas_meshes(), atlas_palette(), atlas_polygons(), atlas_regions(), atlas_sf(), atlas_type(), atlas_vertices(), atlas_views()

Examples

head(legacy_region_map(aseg()))
legacy_region_map(tracula())[["SLF I"]]
legacy_region_map(aseg())[["Thalamus Proper"]]

Description

Walks a directory of .rda files, finds every ggseg_atlas object inside them, and rewrites their 2D geometry into the single geom slot. By default the geometry is stored as brain_polygons (sf-optional); any legacy sf / polygons slots are dropped. Pass keep_sf = TRUE to store the geometry as sf instead.

Usage

migrate_atlas_files(
  path = "data",
  keep_sf = FALSE,
  quiet = FALSE,
  force = FALSE
)

Arguments

Details

Intended for downstream atlas-package maintainers across the ggsegverse ecosystem: run once against your ⁠data/⁠ directory, then drop sf from DESCRIPTION Imports.

Value

Invisibly, a character vector of paths to the files that were rewritten.

Examples

# In an atlas package you would call this on the package's own data/
# directory. Here it runs against a throwaway copy, since it rewrites the
# files it is pointed at. Producing an sf atlas to migrate needs sf.
dir <- file.path(tempdir(), "data")
dir.create(dir, showWarnings = FALSE)
dk_atlas <- as_sf_atlas(dk())
save(dk_atlas, file = file.path(dir, "dk_atlas.rda"))

migrate_atlas_files(dir, quiet = TRUE)

load(file.path(dir, "dk_atlas.rda"))
is_atlas_polygon(dk_atlas) # TRUE
unlink(dir, recursive = TRUE)

Description

Recursively reads in all stats files for an atlas (given a unique character string), for all subjects in the subjects directory. Will add hemisphere and subject id to the data.

Usage

read_atlas_files(subjects_dir, atlas)

Arguments

Value

data.frame with stats information for subjects from FreeSurfer

Examples

subj_dir <- "/path/to/freesurfer/7.2.0/subjects/"
read_atlas_files(subj_dir, "aseg.stats")
read_atlas_files(subj_dir, "lh.aparc.stats")

Description

FreeSurfer atlas stats files have a format that can be difficult to easily read in to R. This function takes a raw stats-file from the subjects directory and reads it in as a data.frame.

Usage

read_freesurfer_stats(path, rename = TRUE)

Arguments

Value

data.frame with stats information for subjects from FreeSurfer

Examples

subj_dir <- "/path/to/freesurfer/7.2.0/subjects/"
aseg_stats <- file.path(subj_dir, "bert/stats/aseg.stats")
read_freesurfer_stats(aseg_stats)

Description

FreeSurfer has functions to create tables from raw stats files. If you have data already merged using the aparcstats2table or asegstats2table from FreeSurfer, this function will read in the data and prepare it for ggseg.

Usage

read_freesurfer_table(path, measure = NULL, ...)

Arguments

Value

data.frame with stats information for subjects from FreeSurfer

Examples

file_path <- "all_subj_aseg.txt"
read_freesurfer_table(file_path)

Description

label is an atlas's join key: core, the palette's names and every geometry payload (geom, vertices, meshes, centerlines) are keyed on it. Rewriting it in one of those places and not the others silently decouples geometry from metadata, which is how a renamed region ends up drawn in the wrong colour or not at all, so this rewrites all of them together.

Usage

relabel_atlas(atlas, mapping)

Arguments

Details

Labels absent from mapping are left alone, so contextual geometry such as the cortex_ silhouette survives a partial re-key untouched.

This is the supported way to correct an atlas's identifiers – the operation tracula() itself needed when its .bbr.prep suffix was restored. Use atlas_region_rename() instead to change the display names in region, which is not a join key.

Value

The ggseg_atlas with mapping applied to core$label, the palette's names and every payload slot that carries a label column.

See Also

atlas_region_rename() to rename regions rather than re-key labels.

Other atlas manipulations: atlas_manipulation, atlas_structure_reorder()

Examples

a <- relabel_atlas(aseg(), c("Left-Thalamus" = "lh_thalamus"))
head(atlas_labels(a))

Description

Replaces the colour palette of a brain atlas, validating that value is a named character vector and warning if it does not cover every atlas label. This is the setter counterpart to the atlas_palette() accessor; it returns the modified atlas, so it composes with the pipe.

Usage

set_atlas_palette(atlas, value)

Arguments

Value

The ggseg_atlas with its palette replaced.

See Also

atlas_palette() to read the palette.

Other atlas setters: set_atlas_type()

Examples

a <- aseg()
labs <- atlas_labels(a)
a <- set_atlas_palette(a, setNames(grDevices::rainbow(length(labs)), labs))

Description

Replaces the type of a brain atlas. The type is held in three coupled places: the type field, the leading ⁠<type>_atlas⁠ class, and the ⁠ggseg_data_<type>⁠ class of the data payload. This setter reconstructs the atlas through ggseg_atlas() so all three stay in agreement – assigning the type field directly leaves the subclass stale and is_tract_atlas() and friends disagreeing with atlas_type().

Usage

set_atlas_type(atlas, value)

Arguments

Details

Because type and payload are coupled, the new type must match the data the atlas already carries: a "tract" atlas needs ggseg_data_tract() (centerlines), a "subcortical" atlas needs ggseg_data_subcortical() (meshes). Retyping an atlas whose payload does not match is an error – rebuild the payload with the matching ⁠ggseg_data_*()⁠ constructor first.

Value

The ggseg_atlas with its type, subclass and payload class in agreement.

See Also

atlas_type() to read the type.

Other atlas setters: set_atlas_palette()

Examples

a <- aseg()
a <- set_atlas_type(a, "subcortical")
atlas_type(a)

Description

Returns the SUIT cerebellar parcellation (Diedrichsen et al., 2009): the cerebellar cortex split into anatomical lobules plus the deep nuclei (dentate, interposed, fastigial).

Usage

suit()

Details

Surface lobules carry vertex indices into the shared SUIT cerebellar mesh (see get_cerebellar_mesh()); deep nuclei carry individual 3D meshes. The 2D geometry is stored in the sf-optional polygon (geom) representation, so the atlas renders with ggseg without requiring sf installed.

Value

A ggseg_atlas object with components:

atlas

Character. Atlas name ("suit")

type

Character. Atlas type ("cerebellar")

palette

Named character vector of colours for each region

data

A ggseg_data_cerebellar object containing:

geom

A brain_polygons table for 2D rendering

vertices

Vertex indices for surface lobules

meshes

Per-structure 3D meshes for the deep nuclei

Core columns

core carries one row per atlas region with the columns hemi, region, label and names, plus the atlas's own grouping column. label is the stable atlas identifier and the key the palette and the geometry are keyed on; region is a short, hemisphere-free key derived from it; names is the curated long-form display name, spelled out to read well in a figure legend.

region held the long-form name until version 0.1.0. names is not a record of those old values – use legacy_region_map() to translate them.

References

Diedrichsen J, Balsters JH, Flavell J, et al. (2009). A probabilistic MR atlas of the human cerebellum. NeuroImage, 46(1):39-46. doi:10.1016/j.neuroimage.2009.01.045

See Also

dk() for cortical parcellation, aseg() for subcortical structures, tracula() for white-matter tracts, ggseg_atlas() for the atlas class constructor

Other ggseg_atlases: aseg(), dk(), tracula()

Examples

suit()
atlas_regions(suit())
atlas_geometry_type(suit())

Description

Returns the TRACULA (TRActs Constrained by UnderLying Anatomy) white matter bundle atlas in MNI space.

Usage

tracula()

Details

This atlas contains major white matter tracts reconstructed from diffusion MRI using FreeSurfer's TRACULA training data. It works with both ggseg (2D slice projections) and ggseg3d (3D tube mesh visualizations).

Value

A ggseg_atlas object with components:

atlas

Character. Atlas name ("tracula")

type

Character. Atlas type ("tract")

palette

Named character vector of colours for each tract

data

A ggseg_data_tract object containing:

centerlines

List of centerline matrices per tract

sf

Simple features data frame for 2D rendering

Core columns

core carries one row per atlas region with the columns hemi, region, label and names, plus the atlas's own grouping column. label is the stable atlas identifier and the key the palette and the geometry are keyed on; region is a short, hemisphere-free key derived from it; names is the curated long-form display name, spelled out to read well in a figure legend.

region held the long-form name until version 0.1.0. names is not a record of those old values – use legacy_region_map() to translate them.

Tract labels

label is the name FreeSurfer's TRACULA writes its per-pathway outputs under, including the trailing .bbr.prep (for example lh.af.bbr.prep), so a table of TRACULA output joins to the atlas as it comes. label_short is the same identifier with the suffix stripped – the name FreeSurferColorLUT.txt gives the pathway at ids 5100-5399.

References

Yendiki A, Panneck P, Srinivasan P, et al. (2011). Automated probabilistic reconstruction of white-matter pathways in health and disease using an atlas of the underlying anatomy. Frontiers in Neuroinformatics, 5:23. doi:10.3389/fninf.2011.00023

See Also

dk() for cortical parcellation, aseg() for subcortical structures, ggseg_atlas() for the atlas class constructor

Other ggseg_atlases: aseg(), dk(), suit()

Examples

tracula()
plot(tracula())
atlas_regions(tracula())