spectralbrain.viz.clusters#

Clustering visualisation — 3D mesh renders and 2D statistical plots.

Provides publication-quality figures for every output of spectralbrain.statistics.clustering: spatial cluster maps, GNMF components, persistence landscapes, temporal profiles, method comparisons, Bayesian confirmation diagnostics, and fused-descriptor panels.

Figure types#

3D mesh renders (vedo)

Cluster map — mesh coloured by integer labels, 3-pose panel
Cluster boundaries — wireframe with coloured boundary edges
Multi-method comparison — side-by-side cluster maps
GNMF spatial components — one panel per W column
Soft membership — mesh coloured by posterior probability
Exploded clusters — spatially separated cluster fragments
HKS + clusters progression — scalar + labels across t
Persistence basins — mesh coloured by persistence-based partition
Fusion panel — HKS / WKS / Fused side by side

2D statistical plots (matplotlib)

Cluster HKS time-profiles — mean ± SEM per cluster
Silhouette diagram — per-sample silhouette ordered by cluster
Cluster quality comparison — bar chart across methods
Method agreement heatmap — ARI / NMI matrix
Persistence diagram — birth vs death scatter
GNMF temporal factors — F matrix as line profiles
Bayesian confirmation — posterior probabilities + credible intervals
Cluster size distribution — bar chart
UMAP / PCA scatter — embedding coloured by clusters
Co-clustering checkerboard — vertex × time block structure

Architecture#

vedo for all 3D renders (offscreen VTK → PNG).
matplotlib for all 2D plots (publication style via graphics.py).
3D functions return (Path, dict) — PNG path + metadata.
2D functions return (Figure, Axes) for customisation.
Every function accepts save for auto-export.

Functions

`plot_agreement_heatmap`(agreement_matrix, ...)	Heatmap of pairwise clustering agreement.
`plot_bayesian_confirmation`(...[, title, ...])	Two-panel Bayesian confirmation diagnostic.
`plot_cluster_boundaries`(vertices, faces, ...)	Render mesh with cluster boundaries as coloured lines.
`plot_cluster_exploded`(vertices, faces, labels, *)	Exploded view — each cluster is displaced outward from centroid.
`plot_cluster_map`(vertices, faces, labels, *)	Render mesh coloured by cluster labels in a multi-view panel.
`plot_cluster_profiles`(H, labels[, t_values, ...])	Mean ± SEM HKS profiles per cluster.
`plot_cluster_scatter`(embedding, labels, *[, ...])	2D scatter of dimensionality-reduced embedding coloured by cluster.
`plot_cluster_sizes`(labels, *[, title, ...])	Bar chart of cluster sizes with noise count.
`plot_cluster_summary`(vertices, faces, H, labels)	Comprehensive 2×3 summary panel for a clustering result.
`plot_coclustering_heatmap`(H, row_labels, ...)	Reordered heatmap revealing vertex × time co-cluster blocks.
`plot_descriptor_evolution_comparison`(...[, ...])	Side-by-side HKS vs WKS evolution on the unfolded surface.
`plot_fusion_panel`(vertices, faces, ...[, ...])	Side-by-side render of HKS, WKS, and fused descriptor.
`plot_gnmf_components`(vertices, faces, W, *)	Render GNMF spatial factor columns as separate mesh panels.
`plot_gnmf_temporal_factors`(F[, t_values, ...])	Plot rows of the GNMF F matrix as temporal profiles.
`plot_hks_cluster_progression`(vertices, ...)	Show HKS scalar at selected time-scales alongside cluster map.
`plot_hovmoller`(unfolded_coords, H[, ...])	Hovmöller diagram: averaged descriptor along one spatial axis × scale.
`plot_kymograph`(unfolded_coords, faces, H[, ...])	Kymograph: descriptor values along a 1D line × scale.
`plot_method_comparison_3d`(vertices, faces, ...)	Compare multiple clustering methods on the same mesh.
`plot_persistence_diagram`(diagram, *[, ...])	Birth-death scatter for persistence-based clustering.
`plot_quality_comparison`(quality_dict, *[, ...])	Grouped bar chart comparing quality metrics across methods.
`plot_silhouette_diagram`(H, labels, *[, ...])	Per-sample silhouette plot ordered by cluster.
`plot_soft_membership`(vertices, faces, ...[, ...])	Render soft membership probability for one cluster.
`plot_spatiotemporal_animation`(...[, ...])	Animate descriptor field across scales on the unfolded surface.
`plot_spatiotemporal_field`(unfolded_coords, ...)	Small-multiples grid of a descriptor field on unfolded surface.
`plot_warped_surface`(unfolded_coords, faces, ...)	3D warped surface: unfolded (u, v) + height from descriptor.

spectralbrain.viz.clusters.plot_agreement_heatmap(agreement_matrix, method_names, *, metric_name='ARI', cmap='YlGnBu', title='Inter-Method Agreement', figsize=(6, 5), save=None)[source]#

Heatmap of pairwise clustering agreement.

Parameters:

agreement_matrix ((M, M) array) – Pairwise ARI or NMI scores.
method_names (list of str)
metric_name (str)
cmap (str)
title (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_bayesian_confirmation(label_probabilities, credible_intervals, agreement_ari, *, title='Bayesian Cluster Confirmation', figsize=(10, 4), save=None)[source]#

Two-panel Bayesian confirmation diagnostic.

Left: stacked area of posterior membership probabilities. Right: credible intervals (94% HDI) of cluster centroid norms.

Parameters:

label_probabilities ((N, K) array)
credible_intervals (dict[int, dict]) – Per-cluster HDI summaries from confirm_clusters_bayesian.
agreement_ari (float)
title (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, (Axes, Axes))

Return type:

tuple[Figure, tuple[Axes, Axes]]

spectralbrain.viz.clusters.plot_cluster_boundaries(vertices, faces, labels, *, mesh_color='ivory', mesh_alpha=0.6, boundary_width=3.0, views=None, lighting='default', bg='white', size=None, scale=2, save=None)[source]#

Render mesh with cluster boundaries as coloured lines.

Identifies edges where adjacent triangles have different cluster labels and renders them as coloured tubes on a semi-transparent surface.

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
labels ((V,) int array)
mesh_color (str) – Base mesh colour.
mesh_alpha (float) – Base mesh opacity.
boundary_width (float) – Width of boundary lines.
views (list[str] | None) – Standard render parameters.
lighting (str) – Standard render parameters.
bg (str) – Standard render parameters.
size (tuple[int, int] | None) – Standard render parameters.
scale (int) – Standard render parameters.
save (str | PathLike | None) – Standard render parameters.

Returns:

(Path, dict)

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.clusters.plot_cluster_exploded(vertices, faces, labels, *, explosion_factor=1.5, view='oblique_left', lighting='default', bg='white', size=(1600, 1200), scale=2, save=None)[source]#

Exploded view — each cluster is displaced outward from centroid.

Useful for inspecting cluster topology on convoluted structures like the hippocampus where clusters may overlap visually.

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
labels ((V,) int array)
explosion_factor (float) – Distance multiplier for displacement. 1.0 = in place.
view (str) – Standard parameters.
lighting (str) – Standard parameters.
bg (str) – Standard parameters.
size (tuple[int, int]) – Standard parameters.
scale (int) – Standard parameters.
save (str | PathLike | None) – Standard parameters.

Returns:

(Path, dict)

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.clusters.plot_cluster_map(vertices, faces, labels, *, views=None, noise_color='lightgray', lighting='default', show_scalarbar=True, title=None, bg='white', size=None, scale=2, save=None)[source]#

Render mesh coloured by cluster labels in a multi-view panel.

Each cluster gets a distinct colour from the colorblind-safe palette. Noise vertices (label = -1) are rendered in grey.

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
labels ((V,) int array) – Cluster labels. -1 = noise / unassigned.
views (list of str or None) – Camera preset names. None → 3-pose (lateral, anterior, superior).
noise_color (str) – Colour for noise vertices.
lighting (str)
show_scalarbar (bool)
title (str or None)
bg (str) – Standard render parameters.
size (tuple[int, int] | None) – Standard render parameters.
scale (int) – Standard render parameters.
save (str | PathLike | None) – Standard render parameters.

Returns:

(Path, dict) – PNG path and metadata.

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.clusters.plot_cluster_profiles(H, labels, t_values=None, *, log_t=True, show_sem=True, title='Cluster HKS Profiles', xlabel='Diffusion time t', ylabel='HKS(x, t)', figsize=(7, 4), save=None)[source]#

Mean ± SEM HKS profiles per cluster.

Parameters:

H ((N, T) array)
labels ((N,) int array)
t_values ((T,) array or None)
log_t (bool) – Use log-scale on x-axis.
show_sem (bool) – Show shaded SEM bands.
title (str)
xlabel (str)
ylabel (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_cluster_scatter(embedding, labels, *, method_name='UMAP', noise_color='lightgray', noise_alpha=0.3, point_size=3.0, title=None, figsize=(6, 5), save=None)[source]#

2D scatter of dimensionality-reduced embedding coloured by cluster.

Parameters:

embedding ((N, 2) array)
labels ((N,) int array)
method_name (str) – For axis labels (e.g., “UMAP”, “PCA”, “t-SNE”).
noise_color (str)
noise_alpha (float)
point_size (float)
title (str | None)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_cluster_sizes(labels, *, title='Cluster Size Distribution', figsize=(6, 3.5), save=None)[source]#

Bar chart of cluster sizes with noise count.

Parameters:

labels ((N,) int array)
title (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_cluster_summary(vertices, faces, H, labels, t_values=None, *, method_name='GNMF', figsize=(14, 10), save=None)[source]#

Comprehensive 2×3 summary panel for a clustering result.

Layout:: [0,0] 3D cluster map (embedded PNG) [0,1] Cluster sizes bar chart [0,2] UMAP scatter coloured by cluster [1,0] HKS profiles per cluster [1,1] Silhouette diagram [1,2] Persistence diagram (if available)

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
H ((V, T) array)
labels ((V,) int array)
t_values ((T,) or None)
method_name (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, ndarray of Axes)

Return type:

tuple[Figure, ndarray]

spectralbrain.viz.clusters.plot_coclustering_heatmap(H, row_labels, col_labels, *, cmap='viridis', title='Co-Clustering Structure', figsize=(8, 6), save=None)[source]#

Reordered heatmap revealing vertex × time co-cluster blocks.

Sorts rows and columns by their cluster labels so that the checkerboard block structure of the co-clustering is visible.

Parameters:

H ((N, T) array)
row_labels ((N,) int array) – Vertex cluster labels.
col_labels ((T,) int array) – Time/scale cluster labels.
cmap (str)
title (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_descriptor_evolution_comparison(unfolded_coords, faces, H_hks, H_wks, t_values_hks=None, e_values_wks=None, *, n_scales=4, cmap_hks='inferno', cmap_wks='cividis', log_norm=True, subfield_labels=None, figsize=None, save=None)[source]#

Side-by-side HKS vs WKS evolution on the unfolded surface.

Two-row layout: top = HKS at selected t, bottom = WKS at matched energies. Each with its own colourmap and independent colourbar.

Parameters:

unfolded_coords ((V, 2) array)
faces ((F, 3) array)
H_hks ((V, T_h) array)
H_wks ((V, T_w) array)
t_values_hks ((T_h,) or None)
e_values_wks ((T_w,) or None)
n_scales (int) – Number of scale panels per descriptor.
cmap_hks (str)
cmap_wks (str)
log_norm (bool)
subfield_labels ((V,) or None)
figsize (tuple[float, float] | None)
save (str | PathLike | None)

Returns:

(Figure, ndarray of Axes)

Return type:

tuple[Figure, ndarray]

spectralbrain.viz.clusters.plot_fusion_panel(vertices, faces, hks_scalar, wks_scalar, fused_scalar, *, cmap_hks='inferno', cmap_wks='cividis', cmap_fused='magma', view='left_lateral', lighting='default', bg='white', size=(1800, 600), scale=2, save=None)[source]#

Side-by-side render of HKS, WKS, and fused descriptor.

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
hks_scalar ((V,) arrays) – Single-scale scalars for each descriptor type.
wks_scalar ((V,) arrays) – Single-scale scalars for each descriptor type.
fused_scalar ((V,) arrays) – Single-scale scalars for each descriptor type.
cmap_hks (str)
cmap_wks (str)
cmap_fused (str)
view (str)
lighting (str)
bg (str)
size (tuple[int, int])
scale (int)
save (str | PathLike | None)

Returns:

(Path, dict)

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.clusters.plot_gnmf_components(vertices, faces, W, *, cmap='inferno', max_components=8, view='left_lateral', lighting='default', bg='white', size=None, scale=2, save=None)[source]#

Render GNMF spatial factor columns as separate mesh panels.

Each column of W represents the soft membership weight for one spatial component. Displayed as scalar overlays on the mesh.

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
W ((V, K) array) – Spatial factors from cluster_gnmf.
cmap (str)
max_components (int) – Show at most this many components.
view (str) – Standard parameters.
lighting (str) – Standard parameters.
bg (str) – Standard parameters.
size (tuple[int, int] | None) – Standard parameters.
scale (int) – Standard parameters.
save (str | PathLike | None) – Standard parameters.

Returns:

(Path, dict)

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.clusters.plot_gnmf_temporal_factors(F, t_values=None, *, log_t=True, title='GNMF Temporal Factors', figsize=(7, 4), save=None)[source]#

Plot rows of the GNMF F matrix as temporal profiles.

Each row of F is a canonical HKS-like curve for one component.

Parameters:

F ((K, T) array)
t_values ((T,) array or None)
log_t (bool)
title (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_hks_cluster_progression(vertices, faces, H, labels, t_indices=None, *, n_panels=4, view='left_lateral', cmap_hks='inferno', lighting='default', bg='white', size=None, scale=2, save=None)[source]#

Show HKS scalar at selected time-scales alongside cluster map.

Top row: HKS at different t. Bottom row: cluster labels.

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
H ((V, T) array) – HKS matrix.
labels ((V,) int array)
t_indices (list of int or None) – Column indices into H to show. None → linearly spaced.
n_panels (int) – Number of time-scale panels.
view (str) – Standard parameters.
cmap_hks (str) – Standard parameters.
lighting (str) – Standard parameters.
bg (str) – Standard parameters.
size (tuple[int, int] | None) – Standard parameters.
scale (int) – Standard parameters.
save (str | PathLike | None) – Standard parameters.

Returns:

(Path, dict)

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.clusters.plot_hovmoller(unfolded_coords, H, t_values=None, *, axis='AP', n_bins=100, cmap='viridis', log_norm=True, log_t=True, descriptor_name='HKS', title=None, figsize=(8, 4), save=None)[source]#

Hovmöller diagram: averaged descriptor along one spatial axis × scale.

Collapses the orthogonal spatial axis by averaging, producing a 2D heatmap of (position along AP or PD) × (diffusion scale t). Reveals how the multi-scale spectral signature varies along the hippocampal long axis (AP) or proximal-distal axis (PD).

Parameters:

unfolded_coords ((V, 2) array) – Column 0 = AP, column 1 = PD.
H ((V, T) array) – Per-vertex descriptor matrix.
t_values ((T,) array or None)
axis (str) – Which spatial axis to retain: "AP" (column 0) or "PD" (column 1). The other is averaged out.
n_bins (int) – Number of bins along the retained spatial axis.
cmap (str)
log_norm (bool)
log_t (bool) – Log-scale the t-axis.
descriptor_name (str)
title (str or None)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_kymograph(unfolded_coords, faces, H, t_values=None, *, line_axis='AP', line_position=0.5, n_samples=200, cmap='viridis', log_norm=True, log_t=True, descriptor_name='HKS', title=None, figsize=(8, 4), save=None)[source]#

Kymograph: descriptor values along a 1D line × scale.

Unlike the Hovmöller diagram (which averages over the orthogonal axis), the kymograph traces a single line through the unfolded surface — e.g. the midline of PD — and plots the descriptor along that line for each scale t.

Parameters:

unfolded_coords ((V, 2) array)
faces ((F, 3) array)
H ((V, T) array)
t_values ((T,) array or None)
line_axis (str) – Axis along which the line runs. "AP" → horizontal line at fixed PD = line_position; "PD" → vertical line at fixed AP.
line_position (float) – Position on the orthogonal axis (0–1 in normalised coords).
n_samples (int) – Number of sample points along the line.
cmap (str, bool, bool)
log_norm (str, bool, bool)
log_t (str, bool, bool)
descriptor_name (str)
title (str | None)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_method_comparison_3d(vertices, faces, results, *, view='left_lateral', noise_color='lightgray', lighting='default', bg='white', size=None, scale=2, save=None)[source]#

Compare multiple clustering methods on the same mesh.

Each method gets one panel, all from the same camera angle.

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
results (dict[str, ndarray]) – Method name → (V,) label array.
view (str) – Camera preset for all panels.
noise_color (str) – Standard parameters.
lighting (str) – Standard parameters.
bg (str) – Standard parameters.
size (tuple[int, int] | None) – Standard parameters.
scale (int) – Standard parameters.
save (str | PathLike | None) – Standard parameters.

Returns:

(Path, dict)

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.clusters.plot_persistence_diagram(diagram, *, title='Persistence Diagram', figsize=(5, 5), save=None)[source]#

Birth-death scatter for persistence-based clustering.

Parameters:

diagram ((n_pairs, 2) array) – Each row is (birth, death).
title (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_quality_comparison(quality_dict, *, metrics=None, title='Clustering Quality Comparison', figsize=(8, 4), save=None)[source]#

Grouped bar chart comparing quality metrics across methods.

Parameters:

quality_dict (dict[str, dict[str, float]]) – Outer key = method name, inner dict = metric → value. Example: {"hdbscan": {"silhouette": 0.42}, ...}
metrics (list of str or None) – Which metrics to plot. None → all common metrics.
title (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_silhouette_diagram(H, labels, *, metric='euclidean', title='Silhouette Diagram', figsize=(6, 5), save=None)[source]#

Per-sample silhouette plot ordered by cluster.

Parameters:

H ((N, T) array or (N, N) precomputed distance)
labels ((N,) int array)
metric (str)
title (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.clusters.plot_soft_membership(vertices, faces, probabilities, cluster_idx=0, *, cmap='YlOrRd', views=None, lighting='default', bg='white', size=None, scale=2, save=None)[source]#

Render soft membership probability for one cluster.

Parameters:

vertices ((V, 3) array)
faces ((F, 3) array)
probabilities ((V, K) array) – Soft membership matrix.
cluster_idx (int) – Which cluster’s probability to display.
cmap (str) – Standard parameters.
views (list[str] | None) – Standard parameters.
lighting (str) – Standard parameters.
bg (str) – Standard parameters.
size (tuple[int, int] | None) – Standard parameters.
scale (int) – Standard parameters.
save (str | PathLike | None) – Standard parameters.

Returns:

(Path, dict)

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.clusters.plot_spatiotemporal_animation(unfolded_coords, faces, H, t_values=None, *, cmap='magma', log_norm=True, vmin=None, vmax=None, subfield_labels=None, descriptor_name='HKS', fps=8, figsize=(6, 3.5), save=None)[source]#

Animate descriptor field across scales on the unfolded surface.

Produces a GIF or MP4 (determined by file extension of save) showing how HKS/WKS evolves from fine-scale (local curvature) to coarse-scale (global topology) as the diffusion time increases.

Uses FuncAnimation with a single tripcolor artist and set_array updates for efficient rendering.

Parameters:

unfolded_coords ((V, 2) array)
faces ((F, 3) array)
H ((V, T) array)
t_values ((T,) array or None)
cmap (str)
log_norm (bool)
vmin (float or None)
vmax (float or None)
subfield_labels ((V,) int array or None)
descriptor_name (str)
fps (int) – Frames per second for the output animation.
figsize (tuple)
save (PathLike or None) – Output path. Extension determines format: .gif → Pillow writer, .mp4 → ffmpeg writer.

Returns:

matplotlib.animation.FuncAnimation or None – The animation object (for notebook display). None if save-only.

Return type:

Any | None

spectralbrain.viz.clusters.plot_spatiotemporal_field(unfolded_coords, faces, H, t_values=None, *, n_panels=8, t_indices=None, cmap='magma', log_norm=True, vmin=None, vmax=None, subfield_labels=None, boundary_color='k', boundary_width=0.6, descriptor_name='HKS', xlabel='AP coordinate', ylabel='PD coordinate', n_cols=4, figsize=None, save=None)[source]#

Small-multiples grid of a descriptor field on unfolded surface.

Renders per-vertex spectral descriptor values (HKS, WKS) on the 2D unfolded coordinate system (e.g., HippUnfold’s AP × PD sheet) at log-spaced diffusion times, producing a publication-ready panel that shows the local-to-global progression of HKS.

Each panel is rendered with tripcolor directly on the mesh triangulation — no interpolation to a regular grid is needed, preserving vertex-exact values.

Parameters:

unfolded_coords ((V, 2) array) – Per-vertex 2D coordinates in unfolded space. Column 0 = AP (or u), column 1 = PD (or v).
faces ((F, 3) array) – Triangle indices (same mesh topology as the folded surface).
H ((V, T) array) – Per-vertex descriptor matrix across T scales.
t_values ((T,) array or None) – Scale parameter values for axis labels. None → integer indices.
n_panels (int) – Number of panels to show (overridden by t_indices).
t_indices (list of int or None) – Specific column indices into H. None → geometrically spaced.
cmap (str) – Colourmap for the descriptor field.
log_norm (bool) – Use LogNorm for colour scaling (recommended for HKS).
vmin (float or None) – Colour range. None → robust 2nd/98th percentiles of full H.
vmax (float or None) – Colour range. None → robust 2nd/98th percentiles of full H.
subfield_labels ((V,) int array or None) – If provided, overlay subfield boundaries via tricontour.
boundary_color (str) – Colour for subfield boundary lines.
boundary_width (float) – Width of boundary lines.
descriptor_name (str) – Label for colourbar (e.g. "HKS", "WKS").
xlabel (str) – Axis labels for the unfolded coordinate axes.
ylabel (str) – Axis labels for the unfolded coordinate axes.
n_cols (int) – Number of columns in the panel grid.
figsize (tuple or None) – Figure size. None → auto from n_panels.
save (PathLike or None)

Returns:

(Figure, ndarray of Axes)

Return type:

tuple[Figure, ndarray]

spectralbrain.viz.clusters.plot_warped_surface(unfolded_coords, faces, scalars, *, warp_factor=0.5, cmap='magma', vmin=None, vmax=None, descriptor_name='HKS', views=None, lighting='default', bg='white', size=None, scale=2, save=None)[source]#

3D warped surface: unfolded (u, v) + height from descriptor.

Creates a 3D surface where x = AP, y = PD, and z = warp_factor × descriptor_value. The surface is coloured by the same descriptor. Useful as a “hero figure” showing the spatial distribution of a spectral descriptor.

Parameters:

unfolded_coords ((V, 2) array)
faces ((F, 3) array)
scalars ((V,) array) – Descriptor values to warp by and colour with.
warp_factor (float) – Height scaling factor.
cmap (str)
vmin (float or None)
vmax (float or None)
descriptor_name (str)
views (list of str or None) – Camera presets. None → ["oblique_left"].
lighting (str)
bg (str)
size (tuple[int, int] | None)
scale (int)
save (str | PathLike | None)

Returns:

(Path, dict)

Return type:

tuple[Path, dict[str, Any]]