BrainAtlas

BrainAtlas(atlas, type, core, data, palette=dict())

Brain atlas container for 2D and 3D visualization.

This is the core class in ggsegpy, equivalent to R’s ggseg_atlas. It holds atlas metadata, region definitions, geometry data, and color palettes.

Parameters

Name	Type	Description	Default
atlas	str	Short name for the atlas (e.g., ‘dk’, ‘aseg’, ‘tracula’).	required
type	Literal['cortical', 'subcortical', 'tract']	Atlas type: ‘cortical’, ‘subcortical’, or ‘tract’.	required
core	pd.DataFrame	DataFrame with required columns: hemi, region, label. One row per unique region.	required
data	AtlasData	Type-specific data container (CorticalData, SubcorticalData, or TractData).	required
palette	dict[str, str]	Named dict mapping labels to hex colors.	dict()

Examples

>>> from ggsegpy import dk
>>> atlas = dk()
>>> print(atlas)
>>> atlas.labels[:5]
>>> atlas.to_dataframe()

Attributes

Name	Description
hemispheres	List of hemispheres in the atlas.
labels	List of all region labels.
regions	List of unique region names.

Methods

Name	Description
filter	Filter atlas by hemisphere or region.
plot	Quick plot of the atlas.
to_dataframe	Convert atlas to GeoDataFrame for plotting.

filter

BrainAtlas.filter(hemi=None, region=None)

Filter atlas by hemisphere or region.

Parameters

Name	Type	Description	Default
hemi	str | list[str] | None	Hemisphere(s) to keep: ‘left’, ‘right’, or list.	None
region	str | list[str] | None	Region(s) to keep.	None

Returns

Name	Type	Description
	BrainAtlas	Filtered atlas copy (preserves subclass type).

plot

BrainAtlas.plot(**kwargs)

Quick plot of the atlas.

Parameters

Name	Type	Description	Default
**kwargs	Any	Passed to geom_brain().	{}

Returns

Name	Type	Description
	ggplot	A plotnine ggplot object.

to_dataframe

BrainAtlas.to_dataframe()

Convert atlas to GeoDataFrame for plotting.

Merges core metadata with geometry data, similar to R’s as.data.frame.ggseg_atlas.

Returns

Name	Type	Description
	gpd.GeoDataFrame	Combined data with geometry, hemi, region, label, view, and atlas metadata columns.