Say you are preparing a figure that focuses on the subcortical structures visible in a single sagittal slice. You want to drop the views you don’t need, remove small polygon fragments that clutter the image, turn some regions into non-legend context, and add a metadata column so you can facet by structure type. Every one of those steps is a single function call, and they all pipe together.
ggseg.formats provides three groups of manipulation functions.
Region functions (atlas_region_*) control
which regions are active in the atlas. View functions
(atlas_view_*) control the 2D geometry—which views are
present and how they are arranged. Core functions
(atlas_core_*) enrich the region metadata. All of them
accept a ggseg_atlas as the first argument, return a new
ggseg_atlas, and play nicely with the pipe.
atlas_region_remove() strips a region entirely—from
core, palette, 2D geometry, and 3D data. The pattern
argument is passed to grepl() with
ignore.case = TRUE, so partial matches work:
no_cc <- atlas_region_remove(dk(), "corpuscallosum")
"corpuscallosum" %in% atlas_regions(no_cc)
#> [1] FALSEatlas_region_keep() is the inverse: it keeps only the
regions that match and turns everything else into context geometry (the
geometry is preserved for surface continuity, but non-matching regions
leave core and palette):
frontal <- atlas_region_keep(dk(), "frontal")
unique(atlas_regions(frontal))
#> [1] "caudalmiddlefrontal" "lateralorbitofrontal" "medialorbitofrontal"
#> [4] "rostralmiddlefrontal" "superiorfrontal" "frontalpole"Both functions match the pattern against label by
default: the identifier that is unique within an atlas and spelled the
same way wherever the atlas is used. That is what makes a hemisphere
prefix something you can select on:
lh_only <- atlas_region_keep(dk(), "^lh_")
head(atlas_labels(lh_only))
#> [1] "lh_bankssts" "lh_caudalanteriorcingulate"
#> [3] "lh_caudalmiddlefrontal" "lh_corpuscallosum"
#> [5] "lh_cuneus" "lh_entorhinal"Pass match_on = "region" to match the hemisphere-free
region key instead:
Sometimes you want a region’s polygon to stay visible (rendered in
grey) but not appear in the legend or carry data. This is what
atlas_region_contextual() does. It removes the region from
core, palette, and 3D data but leaves the 2D geometry in place:
ctx <- atlas_region_contextual(aseg(), "ventricle")
#> Warning in atlas_region_contextual(aseg(), "ventricle"): No regions matched "ventricle".
#> ℹ No region was made contextual.
"lateral ventricle" %in% atlas_regions(ctx)
#> [1] FALSECompare that to atlas_region_remove(), which would
delete the ventricle polygons entirely, leaving gaps in the 2D
slices.
atlas_region_rename() changes the region
column without touching label (so geometry links stay
intact). Like the other verbs it picks its rows by label,
and it edits the region those rows already have. A string is substituted
for the pattern wherever the region contains it:
renamed <- atlas_region_rename(dk(), "bankssts", "STS banks")
"STS banks" %in% atlas_regions(renamed)
#> [1] TRUEA function receives the regions of the matching rows and returns the new ones. That is the way to set a region outright for a label, whatever it was called before:
outright <- atlas_region_rename(
dk(),
"^[lr]h_bankssts$",
\(region) "STS banks"
)
"STS banks" %in% atlas_regions(outright)
#> [1] TRUEPass match_on = "region" to pick the rows by their
region text instead:
atlas_views() tells you what 2D views an atlas has:
atlas_views(aseg())
#> [1] "axial_3" "axial_4" "axial_5" "axial_6" "coronal_1" "coronal_2"
#> [7] "sagittal"atlas_view_keep() and atlas_view_remove()
filter views by pattern. If you only want the sagittal slice:
Or remove several views at once by passing a vector:
After filtering regions you may have small polygon fragments left
over—tiny slivers where a region just barely crossed a slice plane.
atlas_view_remove_small() removes region polygons below a
minimum area threshold. Context polygons (those not in core) are never
removed:
You can scope the removal to specific views:
cleaned_sag <- atlas_view_remove_small(
aseg(),
min_area = 50,
views = "sagittal"
)
#> ℹ Removed 4 geometries below area 50atlas_view_remove_region() removes a specific region’s
2D geometry without touching core, palette, or 3D data. This is useful
when a region’s 2D projection is misleading but you still want it in
3D:
When you remove views, the remaining geometry keeps its original
coordinates, which can leave awkward gaps.
atlas_view_gather() repositions views side-by-side with a
configurable gap:
trimmed <- aseg() |>
atlas_view_keep(c("sagittal", "coronal_2", "axial_3")) |>
atlas_view_gather()
atlas_views(trimmed)
#> [1] "axial_3" "coronal_2" "sagittal"atlas_view_reorder() lets you choose the left-to-right
order and repositions at the same time. Views not mentioned in
order are appended at the end:
atlas_core_add() left-joins a data frame onto the core
table. This is useful for attaching grouping variables, statistical
results, or any other per-region information. Here we add a custom
network column to a handful of regions:
network_info <- data.frame(
region = c(
"superiorfrontal",
"precuneus",
"inferiorparietal",
"posteriorcingulate"
),
network = "default mode"
)
enriched <- atlas_core_add(dk(), network_info)
enriched$core[!is.na(enriched$core$network), c("region", "network")]
#> region network
#> 8 inferiorparietal default mode
#> 23 posteriorcingulate default mode
#> 25 precuneus default mode
#> 28 superiorfrontal default mode
#> 43 inferiorparietal default mode
#> 58 posteriorcingulate default mode
#> 60 precuneus default mode
#> 63 superiorfrontal default modeThe by argument defaults to "region" but
you can join on any shared column.
Here is a realistic pipeline that prepares the aseg
atlas for a compact two-view figure of deep grey matter structures:
publication_aseg <- aseg() |>
atlas_view_keep(c("sagittal", "coronal_2")) |>
atlas_region_contextual("ventricle|choroid|white|cc") |>
atlas_view_remove_small(min_area = 30) |>
atlas_view_gather(gap = 0.1)
#> ℹ Removed 3 geometries below area 30
publication_aseg
#>
#> ── aseg ggseg atlas ────────────────────────────────────────────────────────────
#> Type: subcortical
#> Regions: 11
#> Hemispheres: left, NA, right
#> Views: coronal_2, sagittal
#> Palette: ✔
#> Rendering: ✔ ggseg
#> ✔ ggseg3d (meshes)
#> ────────────────────────────────────────────────────────────────────────────────
#> hemi region label display
#> 1 left cerebellum cortex Left-Cerebellum-Cortex cerebellum cortex
#> 2 left thalamus Left-Thalamus thalamus
#> 3 left caudate Left-Caudate caudate
#> 4 left putamen Left-Putamen putamen
#> 5 left pallidum Left-Pallidum pallidum
#> 6 <NA> brain stem Brain-Stem brain stem
#> 7 left hippocampus Left-Hippocampus hippocampus
#> 8 left amygdala Left-Amygdala amygdala
#> 9 left ventraldc Left-VentralDC ventral diencephalon
#> 10 left vessel Left-vessel vessel
#> structure
#> 1 cerebellum
#> 2 basal ganglia
#> 3 basal ganglia
#> 4 basal ganglia
#> 5 basal ganglia
#> 6 brainstem
#> 7 limbic
#> 8 limbic
#> 9 diencephalon
#> 10 other
#> ... with 10 more rowsEach function returns a valid ggseg_atlas, so you can
inspect intermediate results, branch the pipeline, or hand the final
object straight to ggseg for plotting.