geom_brain

geom_brain

Functions

Name	Description
annotate_brain	Add view labels to brain atlas plots.
geom_brain	Create a plotnine-compatible layer for brain atlas visualization.

annotate_brain

geom_brain.annotate_brain(
    atlas=None,
    position=None,
    hemi=None,
    view=None,
    size=3,
    colour='grey30',
    family='monospace',
    nudge_y=0,
    **kwargs,
)

Add view labels to brain atlas plots.

Annotates each brain view with a text label positioned above the view’s bounding box. For cortical atlases, labels show hemisphere and view (e.g., “left lateral”). For subcortical and tract atlases, labels show the view name directly.

Labels respect the repositioning done by position_brain(), so the same position argument should be passed to both geom_brain() and annotate_brain().

Parameters

Name	Type	Description	Default
atlas	BrainAtlas | None	A brain atlas object (e.g. dk(), aseg()).	None
position	position_brain | None	A position_brain() object matching the one used in geom_brain().	None
hemi	str | list[str] | None	Hemisphere(s) to include. If None, all hemispheres are included.	None
view	str | list[str] | None	View(s) to include. If None, all views are included.	None
size	float	Text size in points. Default is 3.	3
colour	str	Text colour. Default is ‘grey30’.	'grey30'
family	str	Font family. Default is ‘monospace’.	'monospace'
nudge_y	float	Additional vertical offset for labels. Default is 0.	0
**kwargs	Any	Additional arguments passed to annotate().	{}

Returns

Name	Type	Description
	list	A list of plotnine annotation layers.

Examples

>>> from plotnine import ggplot
>>> from ggsegpy import geom_brain, annotate_brain, dk, position_brain
>>> pos = position_brain()
>>> p = (
...     ggplot()
...     + geom_brain(atlas=dk(), position=pos, show_legend=False)
...     + annotate_brain(atlas=dk(), position=pos)
... )

geom_brain

geom_brain.geom_brain(
    atlas=None,
    mapping=None,
    data=None,
    hemi=None,
    view=None,
    position=None,
    color='black',
    size=0.1,
    na_fill='grey',
    show_legend=True,
    **kwargs,
)

Create a plotnine-compatible layer for brain atlas visualization.

Use with ggplot() to create 2D brain atlas plots. The atlas geometry is automatically extracted and rendered as polygons.

Parameters

Name	Type	Description	Default
atlas	BrainAtlas | None	Brain atlas to plot. Defaults to dk() if not specified.	None
mapping	aes_class | None	Aesthetic mappings created by aes(). Use fill= for coloring regions.	None
data	pd.DataFrame | None	DataFrame with values to map onto brain regions.	None
hemi	str | list[str] | None	Hemisphere(s) to show: ‘left’, ‘right’, or list of both.	None
view	str | list[str] | None	View(s) to show: ‘lateral’, ‘medial’, or list of both.	None
position	position_brain | None	Layout arrangement as a position_brain() object. Controls how hemispheres and views are arranged in the plot grid. Default is position_brain() (hemispheres as rows, views as columns).	None
color	str	Outline color for regions. Default is ‘black’.	'black'
size	float	Outline width. Default is 0.1.	0.1
na_fill	str	Color for regions with missing data. Default is ‘grey’.	'grey'
show_legend	bool	Whether to show the legend. Default is True.	True
**kwargs	Any	Additional arguments passed to geom_polygon.	{}

Returns

Name	Type	Description
	_BrainLayers	A set of layers that can be added to a ggplot with +.

Examples

Basic atlas plot:

>>> from plotnine import ggplot
>>> from ggsegpy import geom_brain, dk
>>> ggplot() + geom_brain(atlas=dk())

Plot with custom data:

>>> from plotnine import ggplot, aes
>>> import pandas as pd
>>> data = pd.DataFrame({
...     "label": ["lh_precentral", "rh_precentral"],
...     "value": [2.5, 2.1]
... })
>>> ggplot(data) + geom_brain(atlas=dk(), mapping=aes(fill="value"))

Filter by hemisphere and view:

>>> ggplot() + geom_brain(atlas=dk(), hemi="left", view="lateral")