spectralbrain.viz.graphics#

Publication-quality graphics and statistical visualisations.

Foundation module for all SpectralBrain visualisations: palettes, colormaps, figure factory, multi-format export (always PNG @600 dpi), a custom distplot, and figure functions directly linked to spectralbrain.statistics.analysis.

Every plot_* returns (fig, ax) for customisation before saving. Every function accepts an optional save parameter for auto-export.

Functions

`distplot`(data, *[, labels, colors, hist, ...])	Custom distribution plot — histogram + KDE + rug.
`figure`([preset, width, height, nrows, ...])	Create a publication-ready figure.
`plot_connectome_matrix`(matrix, *[, labels, ...])	Connectome heatmap — visualises `build_geometric_connectome()`.
`plot_effect_size_distribution`(effect_sizes, *)	Cohen's d distribution — visualises `cohens_d_map()`.
`plot_embedding`(coords, *[, labels, ...])	2D scatter — visualises PCA/MDS/UMAP from analysis.py.
`plot_laterality`(left, right, *[, labels, ...])	Paired violin L vs R — visualises `asymmetry_test()`.
`plot_pvalue_histogram`(p_values, *[, alpha, ...])	P-value diagnostic histogram — for `vertexwise_ttest()`.
`plot_rdm`(rdm_matrix, *[, labels, cmap, ...])	RDM heatmap — visualises `rdm()`.
`plot_roc_curve`(y_true, y_scores, *[, label, ...])	ROC curve with AUC — visualises `classify()`.
`plot_volcano`(effect_sizes, p_values, *[, ...])	Volcano plot: effect size vs −log₁₀(p).
`savefig`(fig, path, *[, formats, dpi, ...])	Save figure — always PNG, plus optional PDF/SVG/JPG.
`set_style`([context, font_scale])	Apply SpectralBrain matplotlib style globally.

spectralbrain.viz.graphics.distplot(data, *, labels=None, colors=None, hist=True, kde=True, rug=False, bins='auto', alpha_hist=0.35, alpha_kde=0.9, fill_kde=True, alpha_fill=0.15, vertical_lines=None, xlabel='', ylabel='Density', title='', ax=None, save=None, **save_kw)[source]#

Custom distribution plot — histogram + KDE + rug.

Drop-in replacement for seaborn’s deprecated distplot with SpectralBrain styling and multi-group support.

Parameters:

data (ndarray | list[ndarray])
labels (list[str] | None)
colors (list[str] | None)
hist (bool)
kde (bool)
rug (bool)
bins (int | str)
alpha_hist (float)
alpha_kde (float)
fill_kde (bool)
alpha_fill (float)
vertical_lines (dict[str, float] | None)
xlabel (str)
ylabel (str)
title (str)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.figure(preset=None, *, width=None, height=None, nrows=1, ncols=1, unit='mm', **subplot_kw)[source]#

Create a publication-ready figure.

Parameters:

preset (str | None)
width (float | None)
height (float | None)
nrows (int)
ncols (int)
unit (str)

Return type:

tuple[Figure, Any]

spectralbrain.viz.graphics.plot_connectome_matrix(matrix, *, labels=None, network_boundaries=None, cmap='sb_spectral', title='Geometric Connectome', ax=None, save=None)[source]#

Connectome heatmap — visualises build_geometric_connectome().

Parameters:

matrix (ndarray)
labels (list[str] | None)
network_boundaries (list[int] | None)
cmap (str)
title (str)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.plot_effect_size_distribution(effect_sizes, *, threshold=0.5, title='Vertex-wise effect sizes', ax=None, save=None)[source]#

Cohen’s d distribution — visualises cohens_d_map().

Parameters:

effect_sizes (ndarray)
threshold (float)
title (str)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.plot_embedding(coords, *, labels=None, group_names=None, colors=None, method_name='Embedding', alpha=0.7, size=15, ax=None, save=None)[source]#

2D scatter — visualises PCA/MDS/UMAP from analysis.py.

Parameters:

coords (ndarray)
labels (ndarray | None)
group_names (dict[int, str] | None)
colors (list[str] | None)
method_name (str)
alpha (float)
size (float)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.plot_laterality(left, right, *, labels=None, group_names=None, title='Lateralisation', ax=None, save=None)[source]#

Paired violin L vs R — visualises asymmetry_test().

Parameters:

left (ndarray)
right (ndarray)
labels (ndarray | None)
group_names (dict[int, str] | None)
title (str)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.plot_pvalue_histogram(p_values, *, alpha=0.05, title='P-value distribution', ax=None, save=None)[source]#

P-value diagnostic histogram — for vertexwise_ttest().

Parameters:

p_values (ndarray)
alpha (float)
title (str)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.plot_rdm(rdm_matrix, *, labels=None, cmap='sb_sequential', title='Representational Dissimilarity Matrix', ax=None, save=None)[source]#

RDM heatmap — visualises rdm().

Parameters:

rdm_matrix (ndarray)
labels (list[str] | None)
cmap (str)
title (str)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.plot_roc_curve(y_true, y_scores, *, label=None, color=None, ax=None, save=None)[source]#

ROC curve with AUC — visualises classify().

Parameters:

y_true (ndarray)
y_scores (ndarray)
label (str | None)
color (str | None)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.plot_volcano(effect_sizes, p_values, *, alpha=0.05, effect_threshold=0.0, xlabel="Effect size (Cohen's d)", title='Volcano plot', ax=None, save=None)[source]#

Volcano plot: effect size vs −log₁₀(p).

Visualises vertexwise_ttest().

Parameters:

effect_sizes (ndarray)
p_values (ndarray)
alpha (float)
effect_threshold (float)
xlabel (str)
title (str)
ax (Axes | None)
save (str | PathLike | None)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.graphics.savefig(fig, path, *, formats=None, dpi=600, transparent=False, bbox_inches='tight', pad_inches=0.05)[source]#

Save figure — always PNG, plus optional PDF/SVG/JPG.

Parameters:

fig (Figure)
path (str | PathLike)
formats (str | list[str] | None)
dpi (int)
transparent (bool)
bbox_inches (str)
pad_inches (float)

Return type:

list[Path]

spectralbrain.viz.graphics.set_style(context='paper', font_scale=1.0)[source]#

Apply SpectralBrain matplotlib style globally.

Parameters:

context (Literal['paper', 'poster', 'talk'])
font_scale (float)

Return type:

None