spectralbrain.viz.brainplots#

Publication-quality brain surface visualisations for spectral morphometry.

Architecture#

yabplot (PyVista/VTK) renders 3D brain surfaces to high-resolution PNGs. matplotlib composites these PNGs into multi-row panels styled by scienceplots (science + no-latex).

Every public function: - Accepts nan_color, style, and display_type arguments. - Returns (fig, axes) for further customisation. - Accepts save= for automatic multi-format export (always PNG @600 dpi).

Figure types#

Single metric brain plot (cortical or subcortical)
Group comparison panel (A vs B vs A−B)
Normative deviation map (z-scores)
Atlas-free clustering map
Morphometric descriptor gallery (4–10 descriptors stacked)
Multi-descriptor comparison panel
Bilateral (L vs R) comparison
Spectral progression (HKS across t / WKS across e)
Tract visualisation
Subcortical structure panel

Module Attributes

`VIEWS_CORTEX`	Standard 6-view cortical row.
`VIEWS_FULL`	7-view cortical + subcortical row.
`VIEWS_MEDIAL`	Classic 4-view medial/lateral row.

Functions

`plot_bilateral_comparison`(left_spec, ...[, ...])	Side-by-side L vs R hemisphere comparison (2 rows).
`plot_brain`([data, atlas, plot_kind, cmap, ...])	Single-row brain surface plot.
`plot_brain_subcortical`([data, atlas, cmap, ...])	Single-row subcortical structure plot.
`plot_brain_tracts`([data, atlas, cmap, ...])	White matter tract visualisation.
`plot_clustering_map`(cluster_data, *[, ...])	Visualise atlas-free clustering on brain surface.
`plot_group_comparison`(group_a, group_b[, ...])	Two- or three-row group comparison panel.
`plot_morphometric_gallery`(specs, *[, views, ...])	Multi-row panel with one descriptor per row.
`plot_multi_descriptor_panel`(rows, *[, ...])	Generic multi-row panel — the workhorse compositor.
`plot_normative_map`(z_data, *[, atlas, ...])	Normative z-score map with optional thresholded view.
`plot_spectral_progression`(scale_specs, *[, ...])	Multi-scale spectral descriptor progression.
`plot_top10_morphometrics`(descriptor_data, *)	Pre-configured 10-row gallery for the canonical descriptors.

Classes

BrainPlotSpec([label, data, cmap, vminmax, ...])

Visual specification for one brain plot row.

class spectralbrain.viz.brainplots.BrainPlotSpec(label='', data=None, cmap='coolwarm', vminmax=<factory>, nan_color=(1.0, 1.0, 1.0), plot_kind='cortical', atlas=None, extra_kwargs=<factory>)[source]#

Bases: object

Visual specification for one brain plot row.

Keeps colour range, cmap, and labels consistent across panels.

Parameters:

label (str) – Row label (left margin annotation).
data (dict or ndarray or None) – Data for yabplot (parcellated dict or vertex-wise mesh).
cmap (str) – Matplotlib colourmap name.
vminmax (list) – [vmin, vmax]; [None, None] = auto from data.
nan_color (tuple or str) – Colour for NaN / medial wall / missing regions.
plot_kind (str) – "cortical", "subcortical", "tracts", "vertexwise".
atlas (str or None) – Atlas name for parcellated data.
extra_kwargs (dict) – Additional kwargs passed to the yabplot function.

classmethod from_descriptor(descriptor_name, data=None, **overrides)[source]#

Build a spec from a known descriptor name.

Parameters:

descriptor_name (str)
data (Any)
overrides (Any)

Return type:

BrainPlotSpec

atlas: str | None = None#

cmap: str = 'coolwarm'#

data: Any = None#

extra_kwargs: dict[str, Any]#

label: str = ''#

nan_color: Any = (1.0, 1.0, 1.0)#

plot_kind: str = 'cortical'#

vminmax: list[float | None]#

spectralbrain.viz.brainplots.plot_bilateral_comparison(left_spec, right_spec, *, style='matte', display_type='none', title='L vs R Comparison', save=None, formats=None)[source]#

Side-by-side L vs R hemisphere comparison (2 rows).

Parameters:

left_spec (BrainPlotSpec) – Specs for left and right hemisphere data.
right_spec (BrainPlotSpec) – Specs for left and right hemisphere data.
style (str)
display_type (str)
title (str)
save (str | PathLike | None)
formats (str | list[str] | None)

Return type:

tuple[Figure, list[Axes]]

spectralbrain.viz.brainplots.plot_brain(data=None, *, atlas=None, plot_kind='cortical', cmap='coolwarm', vminmax=None, nan_color=(1.0, 1.0, 1.0), style='matte', display_type='none', views=None, title='', save=None, formats=None, **kwargs)[source]#

Single-row brain surface plot.

The basic building block — renders one metric across 6–7 views.

Parameters:

data (dict or (lh_mesh, rh_mesh) or None) – Parcellated dict for cortical/subcortical, or (lh, rh) pyvista.PolyData tuple for vertex-wise.
atlas (str, optional)
plot_kind (str) – "cortical", "subcortical", "tracts", "vertexwise".
cmap (str)
vminmax ([vmin, vmax] or None)
nan_color (tuple or str)
style (str) – yabplot lighting ("matte", "glossy", "sculpted", "flat").
display_type (str) – "none" for batch, "static" for notebooks.
views (list of str, optional) – Default: 6-view cortical row.
title (str)
save (PathLike, optional)
formats (str or list, optional)
kwargs (Any)

Returns:

fig, ax

Return type:

tuple[Figure, Axes]

Examples

>>> plot_brain(z_scores, atlas='schaefer_200', cmap='RdBu_r',
...            vminmax=[-3, 3], save='cortical_z.png')

spectralbrain.viz.brainplots.plot_brain_subcortical(data=None, *, atlas='aseg', cmap='RdBu_r', vminmax=None, nan_color='#cccccc', nan_alpha=0.3, style='sculpted', bmesh_alpha=0.08, views=None, title='', save=None, display_type='none', **kwargs)[source]#

Single-row subcortical structure plot.

Parameters:

data (dict of {structure_name: value})
atlas (str)
nan_alpha (float) – Transparency for structures without data.
bmesh_alpha (float) – Ghost cortex translucency.
cmap (str)
vminmax (list[float] | None)
nan_color (str)
style (str)
views (list[str] | None)
title (str)
save (str | PathLike | None)
display_type (str)
kwargs (Any)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.brainplots.plot_brain_tracts(data=None, *, atlas='xtract_tiny', cmap='inferno', vminmax=None, nan_color='#BDBDBD', orientation_coloring=False, style='matte', display_type='none', views=None, title='', save=None, **kwargs)[source]#

White matter tract visualisation.

Parameters:

data (dict of {tract_name: value} or None)
atlas (str)
orientation_coloring (bool) – RGB directional encoding (ignores data).
cmap (str)
vminmax (list[float] | None)
nan_color (str)
style (str)
display_type (str)
views (list[str] | None)
title (str)
save (str | PathLike | None)
kwargs (Any)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.brainplots.plot_clustering_map(cluster_data, *, atlas=None, plot_kind='cortical', cmap='tab10', nan_color=(0.9, 0.9, 0.9), style='matte', display_type='none', views=None, title='Atlas-Free Clustering', save=None, **kwargs)[source]#

Visualise atlas-free clustering on brain surface.

Parameters:

cluster_data (dict or (lh, rh)) – Cluster labels per region or per vertex.
atlas (str | None)
plot_kind (str)
cmap (str)
nan_color (Any)
style (str)
display_type (str)
views (list[str] | None)
title (str)
save (str | PathLike | None)
kwargs (Any)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.brainplots.plot_group_comparison(group_a, group_b, difference=None, *, views=None, style='matte', display_type='none', title='Group Comparison', save=None, formats=None)[source]#

Two- or three-row group comparison panel.

Parameters:

group_a (BrainPlotSpec) – Control group (typically blue-ish cmap).
group_b (BrainPlotSpec) – Patient group.
difference (BrainPlotSpec, optional) – A − B difference map (diverging cmap, symmetric vminmax).
views (list of str)
style (str)
display_type (str)
title (str)
save (PathLike, optional)
formats (str | list[str] | None)

Returns:

fig, axes

Return type:

tuple[Figure, list[Axes]]

spectralbrain.viz.brainplots.plot_morphometric_gallery(specs, *, views=None, style='matte', display_type='none', title='Spectral Morphometry Gallery', panel_width_in=12.0, row_height_in=1.4, save=None, formats=None)[source]#

Multi-row panel with one descriptor per row.

The flagship figure for spectral morphometry papers — stack 4–10 descriptors with consistent views for visual comparison.

Parameters:

specs (list of BrainPlotSpec) – One spec per row. Use BrainPlotSpec.from_descriptor() for standard styling.
views (list of str) – Default: 6-view cortical.
style (str)
title (str)
panel_width_in (float)
row_height_in (float)
save (PathLike, optional)
display_type (str)
formats (str | list[str] | None)

Returns:

fig, axes

Return type:

tuple[Figure, list[Axes]]

Examples

>>> specs = [
...     BrainPlotSpec.from_descriptor("hks",       data=hks_dict),
...     BrainPlotSpec.from_descriptor("wks",       data=wks_dict),
...     BrainPlotSpec.from_descriptor("bks",       data=bks_dict),
...     BrainPlotSpec.from_descriptor("shape_idx", data=si_dict),
...     BrainPlotSpec.from_descriptor("casorati",  data=cas_dict),
... ]
>>> fig, axes = plot_morphometric_gallery(specs, save='gallery.png')

spectralbrain.viz.brainplots.plot_multi_descriptor_panel(rows, *, views=None, style='matte', display_type='none', title='', panel_width_in=12.0, row_height_in=1.5, save=None, formats=None)[source]#

Generic multi-row panel — the workhorse compositor.

Parameters:

rows (list of BrainPlotSpec) – 4–8 rows (or more).
views (list[str] | None)
style (str)
display_type (str)
title (str)
panel_width_in (float)
row_height_in (float)
save (str | PathLike | None)
formats (str | list[str] | None)

Return type:

tuple[Figure, list[Axes]]

spectralbrain.viz.brainplots.plot_normative_map(z_data, *, atlas=None, plot_kind='cortical', threshold=2.0, cmap='coolwarm', vminmax=None, nan_color=(0.85, 0.85, 0.85), style='matte', display_type='none', views=None, title='Normative Deviation', show_thresholded=True, save=None, formats=None)[source]#

Normative z-score map with optional thresholded view.

Parameters:

z_data (dict or (lh, rh)) – Z-score values.
threshold (float) – Threshold for the second row (if show_thresholded=True).
show_thresholded (bool) – Show a second row with only extreme deviations.
atlas (str | None)
plot_kind (str)
cmap (str)
vminmax (list[float] | None)
nan_color (Any)
style (str)
display_type (str)
views (list[str] | None)
title (str)
save (str | PathLike | None)
formats (str | list[str] | None)

Returns:

fig, axes

Return type:

tuple[Figure, list[Axes]]

spectralbrain.viz.brainplots.plot_spectral_progression(scale_specs, *, descriptor_name='HKS', views=None, style='matte', display_type='none', title=None, save=None, formats=None)[source]#

Multi-scale spectral descriptor progression.

One row per scale parameter (time for HKS, energy for WKS). Visually demonstrates how the descriptor captures geometry at different spatial frequencies.

Parameters:

scale_specs (list of BrainPlotSpec) – One per scale. Label should include the scale value (e.g. "t=10", "e=2.5").
descriptor_name (str) – For the title.
views (list[str] | None)
style (str)
display_type (str)
title (str | None)
save (str | PathLike | None)
formats (str | list[str] | None)

Return type:

tuple[Figure, list[Axes]]

spectralbrain.viz.brainplots.plot_top10_morphometrics(descriptor_data, *, atlas=None, plot_kind='cortical', views=None, style='matte', display_type='none', title='Top 10 Spectral Morphometrics', save=None, formats=None)[source]#

Pre-configured 10-row gallery for the canonical descriptors.

Parameters:

descriptor_data (dict of {name: data}) – Keys from: "hks", "wks", "si_hks", "bks", "gps", "shapedna", "bates_sp", "gaussian_k", "mean_k", "shape_idx", "casorati", "curvedness".
atlas (str)
plot_kind (str)
views (list[str] | None)
style (str)
display_type (str)
title (str)
save (str | PathLike | None)
formats (str | list[str] | None)

Returns:

fig, axes

Return type:

tuple[Figure, list[Axes]]

spectralbrain.viz.brainplots.VIEWS_CORTEX: list[str] = ['right_lateral', 'anterior', 'left_lateral', 'posterior', 'superior', 'inferior']#: Standard 6-view cortical row.

spectralbrain.viz.brainplots.VIEWS_FULL: list[str] = ['right_lateral', 'anterior', 'left_lateral', 'posterior', 'superior', 'inferior', 'subcortex']#: 7-view cortical + subcortical row.

spectralbrain.viz.brainplots.VIEWS_MEDIAL: list[str] = ['left_lateral', 'left_medial', 'right_medial', 'right_lateral']#: Classic 4-view medial/lateral row.