Skip to contents

Manipulate brain atlas regions and views

Source: R/atlas_utils.R
atlas_manipulation.Rd

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

Usage

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

atlas_region_contextual(
  atlas,
  pattern,
  match_on = c("region", "label"),
  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)

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

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)

atlas_view_gather(atlas, gap = 0.15)

atlas_view_reorder(atlas, order, gap = 0.15)

Arguments

atlas

A ggseg_atlas object

pattern

Character pattern to match. Uses grepl(..., ignore.case = TRUE).

match_on

Column to match against: "region" or "label".

ignore.case

For atlas_region_contextual(): passed to grepl(). Defaults to TRUE for backwards compatibility, but note that a context pattern like "Thalamus" then also matches focus labels such as "hypothalamus"; set FALSE (and/or anchor the pattern) when that matters.

x, y

For atlas_region_op(): patterns selecting the two operands.

action

For atlas_region_op(): the boolean operation to apply.

into

For atlas_region_op(): label for the result region.

colour

For atlas_region_op(): optional fill for into. When supplied, into is registered in core and palette; when NULL, the result is contextual geometry only.

replacement

For atlas_region_rename(): replacement string or function.

data

For atlas_core_add(): data.frame with metadata to join.

by

For atlas_core_add(): column(s) to join by. Default "region".

views

For view functions: character vector of view names or patterns. Multiple values collapsed with "|" for matching.

min_area

For atlas_view_remove_small(): minimum polygon area to keep. Context geometries are never removed.

gap

Proportional gap between views (default 0.15 = 15% of max width).

order

For atlas_view_reorder(): character vector of desired view order. Unspecified views appended at end.

Value

Modified ggseg_atlas object

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 polygon fragments

  • 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

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 affects the region column, not label. If replacement is a function, it receives matched names and returns new names.

  • 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 region geometries below a minimum area threshold. Context geometries (labels not in core) are never removed. Optionally scope to specific views. Views are re-packed via atlas_view_gather() in case any view shrank.

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

Examples

dk() |>
  atlas_region_remove("bankssts") |>
  atlas_region_keep("frontal", match_on = "region")
#> 
#> ── dk ggseg atlas ──────────────────────────────────────────────────────────────
#> Type: cortical
#> Regions: 6
#> Hemispheres: left, right
#> Views: inferior, lateral, superior, medial
#> Palette: ✔
#> Rendering: ✔ ggseg
#> ✔ ggseg3d (vertices)
#> ────────────────────────────────────────────────────────────────────────────────
#>     hemi                 region                   label    lobe
#> 1   left  caudal middle frontal  lh_caudalmiddlefrontal frontal
#> 2   left  lateral orbitofrontal lh_lateralorbitofrontal frontal
#> 3   left   medial orbitofrontal  lh_medialorbitofrontal frontal
#> 4   left rostral middle frontal lh_rostralmiddlefrontal frontal
#> 5   left       superior frontal      lh_superiorfrontal frontal
#> 6   left           frontal pole          lh_frontalpole frontal
#> 7  right  caudal middle frontal  rh_caudalmiddlefrontal frontal
#> 8  right  lateral orbitofrontal rh_lateralorbitofrontal frontal
#> 9  right   medial orbitofrontal  rh_medialorbitofrontal frontal
#> 10 right rostral middle frontal rh_rostralmiddlefrontal frontal
#> ... with 2 more rows