brain_join

brain_join(data, atlas, by=None)

Merge user data with atlas geometry.

Performs a left join, keeping all atlas regions with NaN for regions not in your data. Warns if data contains labels not found in the atlas.

For faceted plots, extra columns in your data (beyond join and value columns) are treated as facet variables. The atlas is replicated for each unique combination of facet values, ensuring the full brain appears in every facet.

Parameters

Name	Type	Description	Default
data	pd.DataFrame	DataFrame with values to map onto brain regions. Must contain a column that matches atlas labels.	required
atlas	BrainAtlas	Brain atlas to join with.	required
by	str | list[str] | None	Column(s) to join on. If None, auto-detects from common columns (label, region, hemi). Can be a single column name or list.	None

Returns

Name	Type	Description
	gpd.GeoDataFrame	Merged GeoDataFrame with atlas geometry and user data.

Examples

Join by label (includes hemisphere prefix):

>>> from ggsegpy import dk, brain_join
>>> import pandas as pd
>>> data = pd.DataFrame({
...     "label": ["lh_precentral", "rh_precentral"],
...     "thickness": [2.5, 2.1]
... })
>>> merged = brain_join(data, dk())

Join by region (applies to both hemispheres):

>>> data = pd.DataFrame({
...     "region": ["precentral", "postcentral"],
...     "value": [0.9, 0.7]
... })
>>> merged = brain_join(data, dk())

Faceted data (atlas replicated per group):

>>> data = pd.DataFrame({
...     "region": ["precentral", "precentral"],
...     "group": ["A", "B"],
...     "value": [0.9, 0.3]
... })
>>> merged = brain_join(data, dk())  # Full brain for each group