spectralbrain.statistics.landmarking#

Morphometric Gaussian Process (M-GP) active-learning landmarking.

Bayesian feature selection for spectral shape analysis: reduce a shape to a concise, interpretable set of landmarks — the vertices of maximal Gaussian Process posterior variance — together with the full residual-variance map. After Fan, Wang, Dong, Liu, Leporé & Wang, Med. Image Anal. 72 (2021) 102123, “Tetrahedral spectral feature-Based bayesian manifold learning”.

The GP kernel fuses two spectral cues, both derived from the same SpectralDecomposition that powers the rest of spectral/:

  • SIWKS — Scale-Invariant Wave Kernel Signature (compute_si_wks()), the Wave Kernel Signature multiplied by 1/λ_K for scale invariance;

  • HFE — Heat Flow Entropy (heat_flow_entropy()), the Shannon entropy of heat-gradient magnitudes across the 1-ring, a per-vertex saliency.

Kernel (Eq. 11/13): K = M̄ H M̄ᵀ with M̄ the row-normalised, KNN-sparse SIWKS distance map and H = diag(HFE). The symmetric form is PSD because HFE ≥ 0 — a valid covariance.

Landmarking (Eq. 15–18) is greedy maximisation of the GP posterior variance, implemented as a pivoted Cholesky of K: the residual diagonal after l pivots equals the posterior variance exactly and its argmax is the next landmark. Cost O(N·L); the dense N×N kernel is never formed — its columns come from sparse mat-vecs.

Concatenating the SIWKS of the landmarks yields a compact per-subject global descriptor with strong statistical power and clear anatomical localisation.

Functions

compute_si_wks(decomp[, e_values, ...])

Scale-Invariant Wave Kernel Signature (SIWKS).

heat_flow_entropy(decomp, *[, t, heat, faces])

Heat Flow Entropy (HFE) — per-vertex structural saliency.

mgp_landmarks(decomp, *[, faces, ...])

Select landmarks by M-GP active learning from a spectral decomposition.

Classes

MGPLandmarkResult(landmarks, descriptor, ...)

Output of mgp_landmarks().
class spectralbrain.statistics.landmarking.MGPLandmarkResult(landmarks, descriptor, uncertainty, selection_scores, siwks, hfe, metadata=<factory>)[source]#

Bases: object

Output of mgp_landmarks().

Parameters:
landmarks#

Vertex indices, in selection order.

Type:

ndarray (L,)

descriptor#

Concatenated SIWKS of the landmarks — the concise subject descriptor.

Type:

ndarray (L * E,)

uncertainty#

Residual GP posterior variance after the L landmarks.

Type:

ScalarMap (N,)

selection_scores#

Posterior variance at each landmark’s selection (saturation curve).

Type:

ndarray (L,)

siwks#

Per-vertex SIWKS feature matrix.

Type:

DescriptorMatrix (N, E)

hfe#

Heat Flow Entropy per vertex.

Type:

ScalarMap (N,)

metadata#
Type:

dict

descriptor: ndarray#
hfe: NDArray[floating]#
landmarks: ndarray#
metadata: dict#
property n_landmarks: int#
selection_scores: ndarray#
siwks: NDArray[floating]#
uncertainty: NDArray[floating]#
spectralbrain.statistics.landmarking.compute_si_wks(decomp, e_values=None, *, n_energies=100, sigma=None)[source]#

Scale-Invariant Wave Kernel Signature (SIWKS).

The WKS rescaled by the inverse of the largest used eigenvalue,

\[\mathrm{SIWKS}(x, e) = \frac{1}{\lambda_K}\, \mathrm{WKS}(x, e),\]

which makes the descriptor invariant to global scaling of the shape (under \(\beta M\), \(\lambda \to \beta^2 \lambda\)). Complements compute_si_hks() on the WKS side.

Parameters:

  • decomp (SpectralDecomposition)

  • e_values (ndarray (E,), optional) – Log-energy levels; None -> auto from eigenvalues.

  • n_energies (int) – Number of auto energy levels.

  • sigma (float, optional) – Gaussian bandwidth; None -> Aubry convention.

Returns:

DescriptorMatrix, shape (N, E)

Return type:

NDArray[floating]

spectralbrain.statistics.landmarking.heat_flow_entropy(decomp, *, t=None, heat=None, faces=None)[source]#

Heat Flow Entropy (HFE) — per-vertex structural saliency.

Diffuses heat on the surface (HKS field at time t) and measures the Shannon entropy of the heat-gradient magnitudes across the 1-ring,

\[\mathrm{HFE}(v_i) = -\sum_{j \in N(i)} p_{ij} \log p_{ij}, \quad p_{ij} = \frac{|h_j - h_i|}{\sum_{j} |h_j - h_i|} \ge 0.\]

High HFE marks structurally disordered regions (e.g. pial/white-matter transitions), used as the GP kernel weight in mgp_landmarks().

Parameters:

  • decomp (SpectralDecomposition)

  • t (float, optional) – Heat diffusion time; None -> spectral mid-time.

  • heat (ndarray (N,), optional) – Precomputed heat field (overrides t).

  • faces (ndarray (m, 3), optional) – Faces for the neighbourhood graph; if omitted, the stiffness sparsity pattern is used.

Returns:

ScalarMap, shape (N,)

Return type:

NDArray[floating]

spectralbrain.statistics.landmarking.mgp_landmarks(decomp, *, faces=None, n_landmarks=50, n_energies=100, knn=20, sigma=None, heat_t=None, heat=None, jitter=1e-10)[source]#

Select landmarks by M-GP active learning from a spectral decomposition.

Parameters:

  • decomp (SpectralDecomposition) – The central SpectralBrain object (eigenpairs; stiffness enables the HFE neighbourhood when faces is not supplied).

  • faces (ndarray (m, 3), optional) – Triangular faces for the HFE 1-ring; if omitted, taken from the stiffness sparsity pattern.

  • n_landmarks (int) – Number of landmarks L to select.

  • n_energies (int) – SIWKS energy scales (per-landmark descriptor length).

  • knn (int) – Neighbours in the SIWKS distance-map graph.

  • sigma (float, optional) – SIWKS bandwidth (None -> Aubry rule).

  • heat_t (float, optional) – Heat-field diffusion time for HFE (None -> spectral mid-time).

  • heat (ndarray (N,), optional) – Precomputed heat field (overrides heat_t).

  • jitter (float) – Pivot floor for the Cholesky stop.

Returns:

MGPLandmarkResult

Return type:

MGPLandmarkResult