Brain atlases ship with dozens of regions. Often you only need a subset—motor cortex for a movement study, or frontal regions for an executive function analysis. ggsegpy provides utilities to filter, rename, and reorganize atlas regions without touching the underlying data files.
Start by seeing what’s in an atlas:
from ggsegpy import dk, atlas_regions, atlas_labels, atlas_views
atlas = dk()
print(f"Regions: {len(atlas_regions(atlas))}")
print(f"Labels: {len(atlas_labels(atlas))}")
print(f"Views: {atlas_views(atlas)}")Regions: 36
Labels: 72
Views: ['inferior', 'lateral', 'medial', 'superior']Regions are the anatomical names (e.g., “precentral”), labels include hemisphere prefixes (e.g., “lh_precentral”):
print("First 5 regions:", atlas_regions(atlas)[:5])
print("First 5 labels:", atlas_labels(atlas)[:5])First 5 regions: ['banks of superior temporal sulcus', 'caudal anterior cingulate', 'caudal middle frontal', 'corpus callosum', 'cuneus']
First 5 labels: ['lh_bankssts', 'lh_caudalanteriorcingulate', 'lh_caudalmiddlefrontal', 'lh_corpuscallosum', 'lh_cuneus']atlas_region_keep() filters to regions matching a pattern:
from plotnine import ggplot
from ggsegpy import geom_brain, atlas_region_keep
frontal = atlas_region_keep(dk(), "frontal")
print(f"Frontal regions: {atlas_regions(frontal)}")
ggplot() + geom_brain(atlas=frontal)Frontal regions: ['caudal middle frontal', 'frontal pole', 'lateral orbitofrontal', 'medial orbitofrontal', 'rostral middle frontal', 'superior frontal']
The plot shows only frontal regions colored—everything else appears as grey context.
atlas_region_remove() does the opposite:
from ggsegpy import atlas_region_remove
no_frontal = atlas_region_remove(dk(), "frontal")
print(f"Regions after removing frontal: {len(atlas_regions(no_frontal))}")
ggplot() + geom_brain(atlas=no_frontal)Regions after removing frontal: 30
Use regex OR syntax to match multiple patterns:
motor_regions = atlas_region_keep(dk(), "precentral|postcentral")
ggplot() + geom_brain(atlas=motor_regions)
By default, patterns match against region names. Use match_on="label" to match against full labels:
left_only = atlas_region_keep(dk(), "lh_", match_on="label")
print(f"Left hemisphere labels: {len(atlas_labels(left_only))}")Left hemisphere labels: 36Shorten region names for cleaner legends:
from ggsegpy import atlas_region_rename
renamed = atlas_region_rename(dk(), "superior", "sup.")
renamed = atlas_region_rename(renamed, "inferior", "inf.")
# Check the changes
print([r for r in atlas_regions(renamed) if "sup." in r or "inf." in r])['banks of sup. temporal sulcus', 'inf. parietal', 'inf. temporal', 'sup. frontal', 'sup. parietal', 'sup. temporal']Use a function for complex transformations:
uppercase = atlas_region_rename(dk(), ".*", lambda x: x.upper())
print(atlas_regions(uppercase)[:5])['BANKS OF SUPERIOR TEMPORAL SULCUS', 'CAUDAL ANTERIOR CINGULATE', 'CAUDAL MIDDLE FRONTAL', 'CORPUS CALLOSUM', 'CUNEUS']atlas_region_contextual() removes regions from the data but keeps them visible as grey context:
from ggsegpy import atlas_region_contextual
# Remove temporal regions from data, keep them visible
no_temporal = atlas_region_contextual(dk(), "temporal")
print(f"Data regions: {len(atlas_regions(no_temporal))}")
ggplot() + geom_brain(atlas=no_temporal)Data regions: 30
Temporal regions appear grey rather than disappearing entirely.
Keep only specific views:
from ggsegpy import atlas_view_keep, atlas_view_remove
lateral_only = atlas_view_keep(dk(), "lateral")
print(f"Views: {atlas_views(lateral_only)}")
ggplot() + geom_brain(atlas=lateral_only)Views: ['lateral']
Remove views:
medial_only = atlas_view_remove(dk(), "lateral")
ggplot() + geom_brain(atlas=medial_only)
atlas_view_gather() repositions views into a compact layout:
from ggsegpy import atlas_view_gather
gathered = atlas_view_gather(dk())
ggplot() + geom_brain(atlas=gathered)
Adjust spacing with the gap parameter (0.0 to 2.0):
compact = atlas_view_gather(dk(), gap=0.05)
ggplot() + geom_brain(atlas=compact)
Change the order views appear:
from ggsegpy import atlas_view_reorder
reordered = atlas_view_reorder(dk(), ["medial", "lateral"])
ggplot() + geom_brain(atlas=reordered)
Clean up tiny fragments that sometimes appear in atlas data:
from ggsegpy import atlas_view_remove_small
# Remove geometries smaller than median area
areas = dk().data.ggseg.geometry.area
cleaned = atlas_view_remove_small(dk(), min_area=areas.median())All functions return a new atlas, so chain them with intermediate variables:
atlas = dk()
atlas = atlas_region_keep(atlas, "frontal")
atlas = atlas_view_keep(atlas, "lateral")
atlas = atlas_view_gather(atlas, gap=0.1)
ggplot() + geom_brain(atlas=atlas)
Enrich atlas regions with external data:
import pandas as pd
from ggsegpy import atlas_core_add
lobe_data = pd.DataFrame({
"region": ["precentral", "postcentral", "superiorfrontal", "inferiorparietal"],
"lobe": ["frontal", "parietal", "frontal", "parietal"]
})
enriched = atlas_core_add(dk(), lobe_data, by="region")
print(enriched.core[["region", "lobe"]].dropna().head()) region lobe
20 postcentral parietal
21 precentral frontal
55 postcentral parietal
56 precentral frontalAll manipulation functions preserve the atlas subclass:
from ggsegpy import atlas_region_remove
filtered = atlas_region_remove(dk(), "banks")
print(f"Original type: {type(dk()).__name__}")
print(f"Filtered type: {type(filtered).__name__}")Original type: CorticalAtlas
Filtered type: CorticalAtlasA CorticalAtlas stays a CorticalAtlas through all transformations.