Verbs that modify the regions core declares, and the geometry that does
or does not belong to them:
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"))Arguments
- atlas
A
ggseg_atlasobject- pattern
Character pattern to match. Uses
grepl(..., ignore.case = TRUE).- match_on
Column of
coreto match against:"label", the default, or"region".labelis the identifier that is unique within an atlas and stable across them, so every verb that selects rows by name or pattern reads it unless told otherwise.- ignore.case
For
atlas_region_contextual(): passed togrepl(). Defaults toTRUEfor backwards compatibility, but note that a context pattern like"Thalamus"then also matches focus labels such as"hypothalamus"; setFALSE(and/or anchor the pattern) when that matters.- x, y
For
atlas_region_op(): patterns selecting the two operands, or a selector such ascontext()orregions().- 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 forinto. When supplied,intois registered in core and palette; whenNULL, the result is contextual geometry only.- replacement
For
atlas_region_rename(): replacement string or function.
Details
atlas_region_remove(): completely remove regionsatlas_region_keep(): keep only matching regionsatlas_region_rename(): rename regions in coreatlas_region_contextual(): keep geometry but remove from core/paletteatlas_context_remove(): drop all contextual geometryatlas_region_op(): combine two regions' geometry with a boolean op (difference / intersection / union / symdifference)
To drop a region's drawing in some views while keeping the region itself, see drawing_manipulation.
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 (sfand/orpolygons), keeping both in sync, and needs nosffor 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 regioninto.xandyare patterns matched againstmatch_on; within each view their matching geometries are unioned, then combined viaaction:"difference"(x minus y, e.g. punching white matter out of a cortex silhouette),"intersection","union", or"symdifference". Inputs are left in place; any existingintogeometry is replaced. With acolour,intobecomes 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 requiressfinstalled; 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 whoselabelis not present incore. Covers labels marked viaatlas_region_contextual()plus pipeline-generated outlines (cortex_,Background,unknown). Remaining views are re-packed viaatlas_view_gather()so the plot focuses tightly on the labelled regions.atlas_region_rename(): Rename regions matching a pattern. Only ever writes to theregioncolumn, never tolabel.match_onchooses the rows: those whoselabel(the default) orregionmatchespattern. The edit is always made to the region text those rows already have. A stringreplacementis substituted forpatternwherever the region contains it, soatlas_region_rename(atlas, "Left-", "")strips the prefix from regions that still carry it. A functionreplacementreceives 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.
See also
atlas_manipulation for the other groups
Other atlas manipulations:
atlas_core_add(),
atlas_manipulation,
atlas_relabel(),
atlas_structure_reorder(),
drawing_manipulation,
view_manipulation
Examples
# Regions are named by the atlas, so take them from it rather than
# spelling them out here, where they would go stale unnoticed.
first_region <- atlas_regions(dk())[1]
dk() |> atlas_region_remove(first_region, match_on = "region")
#>
#> ── dk ggseg atlas ──────────────────────────────────────────────────────────────
#> Type: cortical
#> Regions: 34
#> Hemispheres: left, right
#> Views: inferior, lateral, medial, superior
#> Palette: ✔
#> Rendering: ✔ ggseg
#> ✔ ggseg3d (vertices)
#> ────────────────────────────────────────────────────────────────────────────────
#> hemi region label
#> 1 left caudalanteriorcingulate lh_caudalanteriorcingulate
#> 2 left caudalmiddlefrontal lh_caudalmiddlefrontal
#> 3 left corpuscallosum lh_corpuscallosum
#> 4 left cuneus lh_cuneus
#> 5 left entorhinal lh_entorhinal
#> 6 left fusiform lh_fusiform
#> 7 left inferiorparietal lh_inferiorparietal
#> 8 left inferiortemporal lh_inferiortemporal
#> 9 left isthmuscingulate lh_isthmuscingulate
#> 10 left lateraloccipital lh_lateraloccipital
#> display lobe
#> 1 caudal anterior cingulate cingulate
#> 2 caudal middle frontal frontal
#> 3 corpus callosum white matter
#> 4 cuneus occipital
#> 5 entorhinal temporal
#> 6 fusiform temporal
#> 7 inferior parietal parietal
#> 8 inferior temporal temporal
#> 9 isthmus cingulate cingulate
#> 10 lateral occipital occipital
#> ... with 58 more rows
