spectralbrain.viz.hipp#

Hippocampal surface visualisation — 3D multi-view + unfolded flatmaps.

Combines two rendering engines: - hippunfold_plot (nilearn/matplotlib backend) — for 2D unfolded

flatmap views and standard 3D views via plot_hipp_surf().

hippomaps (BrainSpace/VTK backend) — for high-quality 3D folded renders via surfplot_sub_foldunfold().

HippUnfold version compatibility#

All functions accept both v1 ("0p5mm", "1mm", "2mm") and v2 ("2k", "8k", "18k") density labels. The default changed from "0p5mm" to ``”8k”`` to match HippUnfold v2’s vertex-count-based naming convention.

v1 labels still work but emit a DeprecationWarning.
"8k" ≈ v1 "0p5mm" (~8,000 combined hipp + dentate vertices).
v2 merges label-hipp + label-dentate → label-hippdentate; all label variants are accepted.

See DENSITIES for the full mapping and HIPP_LABELS for recognised structure labels.

Each panel row shows 3D views of the hippocampus in the main columns and an unfolded flatmap in the first or last column, enabling simultaneous inspection of spatial localisation (3D) and subfield identity (unfolded).

Figure types#

Single metric on one hippocampus (3D views + flatmap)
Bilateral panel (L + R side by side)
Group comparison (control vs patient vs difference)
Spectral descriptor gallery (HKS, WKS, BKS, … stacked)
Multi-subject normative deviation panel

Module Attributes

`HIPP_VIEWS_3D`	Standard 3D views for hippocampal surface.
`HIPP_VIEWS_FULL`	3D views + unfolded flatmap.
`DENSITIES`	Recognised HippUnfold density labels (v1 and v2).
`HIPP_LABELS`	Recognised HippUnfold structure labels.

Functions

`plot_hippocampus`(surf_map, *[, hemi, ...])	Single hippocampus: 3D multi-view + unfolded flatmap.
`plot_hippocampus_bilateral`(surf_map_left, ...)	Two-row bilateral panel: L (top) + R (bottom).
`plot_hippocampus_comparison`(group_a_map, ...)	2–3 row group comparison: A, B, [A−B].
`plot_hippocampus_gallery`(descriptors, *[, ...])	Multi-row descriptor gallery — one row per descriptor.
`plot_hippocampus_hovmoller`(H, *[, hemi, ...])	Hovmöller diagram of descriptor along hippocampal axis × scale.
`plot_hippocampus_normative`(z_map, *[, hemi, ...])	Normative z-score map with thresholded view.
`plot_hippocampus_spatiotemporal`(H, *[, ...])	Spatio-temporal descriptor field on the HippUnfold unfolded sheet.

spectralbrain.viz.hipp.plot_hippocampus(surf_map, *, hemi='left', density='8k', views=None, show_flatmap=True, flatmap_position='last', cmap='inferno', vmin=None, vmax=None, nan_color=(0.85, 0.85, 0.85), style='default', display_type='static', title='', save=None, formats=None)[source]#

Single hippocampus: 3D multi-view + unfolded flatmap.

Parameters:

surf_map (str or ndarray) – GIfTI path or per-vertex array.
hemi (str) – "left" or "right".
density (str) – HippUnfold density ("8k", "2k", "8k", "18k").
views (list of str, optional) – 3D view names. Default: lateral, medial, dorsal, ventral, anterior.
show_flatmap (bool) – Include unfolded flatmap column.
flatmap_position (str) – "first" or "last" column.
cmap (str)
vmin (float)
vmax (float)
nan_color (styling.)
style (styling.)
display_type (styling.)
title (str)
save (PathLike, optional)
formats (str | list[str] | None)

Returns:

fig, axes

Return type:

tuple[Figure, list[Axes]]

Examples

>>> plot_hippocampus(
...     "sub-01_hemi-L_thickness.shape.gii",
...     hemi="left", density="8k",
...     cmap="inferno", vmin=1.0, vmax=4.0,
...     save="hippo_thickness.png",
... )

spectralbrain.viz.hipp.plot_hippocampus_bilateral(surf_map_left, surf_map_right, *, density='8k', views=None, show_flatmap=True, cmap='inferno', vmin=None, vmax=None, nan_color=(0.85, 0.85, 0.85), style='default', display_type='static', title='Bilateral Hippocampus', save=None, formats=None)[source]#

Two-row bilateral panel: L (top) + R (bottom).

Parameters:

surf_map_left (str or ndarray)
surf_map_right (str or ndarray)
density (str)
views (list[str] | None)
show_flatmap (bool)
cmap (str)
vmin (float | None)
vmax (float | None)
nan_color (Any)
style (str)
display_type (str)
title (str)
save (str | PathLike | None)
formats (str | list[str] | None)

Return type:

tuple[Figure, ndarray]

spectralbrain.viz.hipp.plot_hippocampus_comparison(group_a_map, group_b_map, diff_map=None, *, hemi='left', density='8k', views=None, show_flatmap=True, cmap_groups='inferno', cmap_diff='RdBu_r', vmin=None, vmax=None, vmin_diff=-3.0, vmax_diff=3.0, nan_color=(0.85, 0.85, 0.85), style='default', display_type='static', row_labels=None, title='Group Comparison', save=None, formats=None)[source]#

2–3 row group comparison: A, B, [A−B].

Parameters:

group_a_map (str or ndarray) – Mean descriptor map per group.
group_b_map (str or ndarray) – Mean descriptor map per group.
diff_map (str or ndarray, optional) – A − B difference (or t-map / z-map).
hemi (str)
density (str)
views (list[str] | None)
show_flatmap (bool)
cmap_groups (str)
cmap_diff (str)
vmin (float | None)
vmax (float | None)
vmin_diff (float)
vmax_diff (float)
nan_color (Any)
style (str)
display_type (str)
row_labels (list[str] | None)
title (str)
save (str | PathLike | None)
formats (str | list[str] | None)

Return type:

tuple[Figure, ndarray]

spectralbrain.viz.hipp.plot_hippocampus_gallery(descriptors, *, hemi='left', density='8k', views=None, show_flatmap=True, nan_color=(0.85, 0.85, 0.85), style='default', display_type='static', title='Hippocampal Spectral Gallery', save=None, formats=None)[source]#

Multi-row descriptor gallery — one row per descriptor.

Parameters:

descriptors (dict of {name: surf_map}) – Keys should match HIPP_DESCRIPTOR_STYLES for auto-styling. Values are GIfTI paths or per-vertex arrays.
hemi (str)
density (str)
views (list of str)
show_flatmap (bool)
title (str)
save (PathLike, optional)
nan_color (Any)
style (str)
display_type (str)
formats (str | list[str] | None)

Returns:

fig, axes

Return type:

tuple[Figure, ndarray]

Examples

>>> plot_hippocampus_gallery(
...     {"thickness": thick_gii, "hks": hks_array,
...      "wks": wks_array, "bks": bks_array},
...     hemi="left", density="8k",
...     save="hippo_gallery.png",
... )

spectralbrain.viz.hipp.plot_hippocampus_hovmoller(H, *, hemi='left', density='8k', t_values=None, axis='AP', unfolded_surf_path=None, cmap='viridis', descriptor_name='HKS', figsize=(8, 4), save=None)[source]#

Hovmöller diagram of descriptor along hippocampal axis × scale.

Wraps spectralbrain.viz.clusters.plot_hovmoller() with HippUnfold-aware coordinate loading.

Parameters:

H ((V, T) array)
hemi (str)
density (str)
t_values ((T,) or None)
axis (str) – "AP" or "PD".
unfolded_surf_path (str or None)
cmap (str)
descriptor_name (str)
figsize (tuple[float, float])
save (str | PathLike | None)

Returns:

(Figure, Axes)

Return type:

tuple[Figure, Axes]

spectralbrain.viz.hipp.plot_hippocampus_normative(z_map, *, hemi='left', density='8k', views=None, show_flatmap=True, threshold=2.0, cmap='RdBu_r', vmin=-3.0, vmax=3.0, nan_color=(0.85, 0.85, 0.85), style='default', display_type='static', title='Hippocampal Normative Deviation', save=None, formats=None)[source]#

Normative z-score map with thresholded view.

Two rows: full z-map (top), thresholded |Z| > threshold (bottom).

Parameters:

z_map (str or ndarray) – Per-vertex z-scores.
threshold (float) – Threshold for the second row.
hemi (str)
density (str)
views (list[str] | None)
show_flatmap (bool)
cmap (str)
vmin (float)
vmax (float)
nan_color (Any)
style (str)
display_type (str)
title (str)
save (str | PathLike | None)
formats (str | list[str] | None)

Return type:

tuple[Figure, ndarray]

spectralbrain.viz.hipp.plot_hippocampus_spatiotemporal(H, *, hemi='left', density='8k', t_values=None, n_panels=8, t_indices=None, cmap='magma', log_norm=True, show_subfields=True, descriptor_name='HKS', unfolded_surf_path=None, subfield_label_path=None, figsize=None, save=None, formats=('png', 'pdf'))[source]#

Spatio-temporal descriptor field on the HippUnfold unfolded sheet.

Wraps spectralbrain.viz.clusters.plot_spatiotemporal_field() with HippUnfold-aware defaults: loads the canonical unfolded mid-thickness surface and subfield labels automatically when paths are provided, applies the AP × PD coordinate convention, and uses neuroimaging-standard axis labels.

This is the hippocampal-specific version of the general spatio-temporal small-multiples visualization. Each panel shows how HKS/WKS varies across the unfolded hippocampal sheet at a different diffusion time, revealing the local → global progression and how it relates to subfield boundaries.

Parameters:

H ((V, T) array) – Per-vertex spectral descriptor matrix. V must match the number of vertices in the unfolded surface.
hemi (str) – "left" or "right".
density (str) – HippUnfold density label ("8k", "2k", "18k"; v1: "0p5mm", "1mm", "2mm").
t_values ((T,) array or None) – Scale parameter values.
n_panels (int)
t_indices (list of int or None)
cmap (str)
log_norm (bool)
show_subfields (bool) – Overlay subfield boundary lines.
descriptor_name (str)
unfolded_surf_path (str or Path or None) – Path to the unfolded midthickness.surf.gii. If None, attempts to load from hippunfold_plot’s bundled data.
subfield_label_path (str or Path or None) – Path to subfields.label.gii. If None and show_subfields is True, attempts to load from hippunfold_plot’s bundled data.
figsize (tuple or None)
save (PathLike or None)
formats (tuple of str) – Export formats.

Returns:

(Figure, ndarray of Axes)

Return type:

tuple[Figure, ndarray]

Notes

The unfolded surface from HippUnfold uses Laplace-solved coordinates (AP × PD), not physical millimetres. Axes are labelled accordingly as “AP coordinate” and “PD coordinate” to avoid misleading the reader. Metric distortion between folded and unfolded spaces does not affect the plotted descriptor values (HKS/WKS are isometry- invariant), but it does affect area-based statistics — use folded- surface vertex areas for any integration.

spectralbrain.viz.hipp.DENSITIES: dict[str, str] = {'0p5mm': '0p5mm', '18k': '18k', '1mm': '1mm', '2k': '2k', '2mm': '2mm', '8k': '8k'}#: Recognised HippUnfold density labels (v1 and v2).

spectralbrain.viz.hipp.HIPP_LABELS: list[str] = ['hipp', 'dentate', 'hippdentate']#: Recognised HippUnfold structure labels.

spectralbrain.viz.hipp.HIPP_VIEWS_3D: list[str] = ['lateral', 'medial', 'dorsal', 'ventral', 'anterior']#: Standard 3D views for hippocampal surface.

spectralbrain.viz.hipp.HIPP_VIEWS_FULL: list[str] = ['lateral', 'medial', 'dorsal', 'ventral', 'anterior', 'flatmap']#: 3D views + unfolded flatmap.