spectralbrain.statistics.ddcrp#

Distance-dependent Chinese Restaurant Process (ddCRP) clustering.

SpectralBrain-harmonised entry points around the vendored ddCRP cores. The sampler restricts candidate links to mesh neighbours (enforcing spatial contiguity), scores partitions with the Normal-Inverse-Wishart collapsed marginal likelihood (Murphy 2007/2012), and modulates contiguity by real edge distance when mesh vertices are supplied.

These functions complement the existing spectralbrain.statistics.clustering algorithms and return the same ClusterResult container, so they slot into the clustering API uniformly.

Functions

autotune_ddcrp(H, *[, faces, adjacency, ...])

Optimise ddCRP hyperparameters from the data (avoids the K=1 collapse).

cluster_consensus(partitions, *[, ...])

Consensus partition from an ensemble of labelings (co-association + AC).

cluster_ddcrp(H, *[, faces, adjacency, ...])

Contiguous ddCRP clustering with a NIW collapsed marginal likelihood.

cluster_ddcrp_functional(curves_blocks, *[, ...])

ddCRP on fPCA-compressed curve blocks (e.g. HKS and WKS together).

Classes

DDCRPTuningResult(best_params, best_score, ...)

Result of autotune_ddcrp().
class spectralbrain.statistics.ddcrp.DDCRPTuningResult(best_params, best_score, history, backend, cluster_result=None, metadata=<factory>)[source]#

Bases: object

Result of autotune_ddcrp().

Parameters:
best_params#
Type:

dict

best_score#
Type:

float

history#
Type:

list of dict

backend#
Type:

str

cluster_result#

The refit partition at full sampling budget (if refit=True).

Type:

ClusterResult or None

backend: str#
best_params: dict#
best_score: float#
cluster_result: ClusterResult | None = None#
history: list#
metadata: dict#
spectralbrain.statistics.ddcrp.autotune_ddcrp(H, *, faces=None, adjacency=None, vertices=None, backend=None, n_trials=40, objective='silhouette', spatial_distance=None, eval_draws=30, eval_burn_in=20, eval_chains=1, random_state=42, progress=True, refit=True, refit_kwargs=None)[source]#

Optimise ddCRP hyperparameters from the data (avoids the K=1 collapse).

Searches psi_scale/kappa0/alpha/decay with an anti-degeneracy guard so partitions that collapse to one cluster or shatter into singletons are rejected. When vertices are given, the decay_scale search bounds are scaled to the mesh’s median edge length.

Parameters:

  • H (ndarray, shape (V, d))

  • faces (ndarray | None) – Mesh contiguity (see cluster_ddcrp()).

  • adjacency (Any) – Mesh contiguity (see cluster_ddcrp()).

  • vertices (ndarray | None) – Mesh contiguity (see cluster_ddcrp()).

  • backend ({"optuna", "hyperopt", "botorch", "random", None}) – Optimiser; falls back to reproducible random search if unavailable.

  • n_trials (int)

  • objective (str)

  • spatial_distance (ndarray | None)

  • eval_draws (int)

  • eval_burn_in (int)

  • eval_chains (int)

  • random_state (int)

  • progress (bool)

  • refit (bool)

  • refit_kwargs (dict | None)

Return type:

DDCRPTuningResult

:param : :param eval_chains: Forwarded to the tuner. :param random_state: Forwarded to the tuner. :param progress: Forwarded to the tuner. :param refit: Forwarded to the tuner. :param refit_kwargs: Forwarded to the tuner.

Returns:

DDCRPTuningResult

Parameters:
Return type:

DDCRPTuningResult

spectralbrain.statistics.ddcrp.cluster_consensus(partitions, *, n_clusters=None, threshold=None)[source]#

Consensus partition from an ensemble of labelings (co-association + AC).

Builds the co-association matrix (fraction of partitions in which two vertices co-cluster) and extracts a consensus partition either by cutting an average-linkage agglomeration to n_clusters or by thresholding the co-association graph and taking connected components.

Parameters:

  • partitions (sequence of (V,) label arrays) – Ensemble of partitions of the same vertices.

  • n_clusters (int, optional) – Cut the dendrogram to this many clusters.

  • threshold (float, optional) – Co-association threshold for the connected-components route. If neither n_clusters nor threshold is given, threshold=0.5 is used.

Returns:

ClusterResult – metadata holds the co_association matrix and per-vertex stability (mean within-cluster co-association).

Return type:

ClusterResult

spectralbrain.statistics.ddcrp.cluster_ddcrp(H, *, faces=None, adjacency=None, vertices=None, decay_kind='exponential', decay_scale=None, alpha=1.0, prior=None, n_components=None, n_draws=200, burn_in=100, thin=2, chains=4, random_state=42, progress=True)[source]#

Contiguous ddCRP clustering with a NIW collapsed marginal likelihood.

Parameters:

  • H (ndarray, shape (V, d)) – Per-vertex descriptor / feature matrix (e.g. fused HKS/WKS scores).

  • faces (ndarray, shape (F, 3), optional) – Mesh triangles; used to build the neighbour list and (with vertices) the edge distances. Provide this or adjacency.

  • adjacency (sparse matrix, optional) – Pre-built vertex adjacency (alternative to faces).

  • vertices (ndarray, shape (V, 3), optional) – Mesh coordinates; if given, the decay kernel uses real Euclidean edge distances and decay_scale defaults to the median edge length.

  • decay_kind ({"window", "exponential", "logistic"}) – Distance-decay form of the ddCRP link prior.

  • decay_scale (float, optional) – Decay length scale (mesh units). Defaults to the median edge length when vertices is given, else 1.0.

  • alpha (float) – ddCRP self-link concentration (higher -> more, smaller clusters).

  • prior (NIWPrior, optional) – Custom NIW prior; by default fit from the data.

  • n_components (int, optional) – If set, PCA-whiten H to this many components before sampling. HKS/WKS descriptors are highly redundant across scales, so a small value (e.g. 6-10) loses little information while making each marginal-likelihood evaluation dramatically cheaper (the cost is cubic in the feature dimension). Strongly recommended for dense surfaces; None keeps the full feature space.

  • n_draws (int) – Collapsed-Gibbs sampling budget.

  • burn_in (int) – Collapsed-Gibbs sampling budget.

  • thin (int) – Collapsed-Gibbs sampling budget.

  • chains (int) – Collapsed-Gibbs sampling budget.

  • random_state (int)

  • progress (bool)

Returns:

ClusterResult – metadata carries the posterior co_association matrix, n_clusters_trace and the decay settings.

Return type:

ClusterResult

spectralbrain.statistics.ddcrp.cluster_ddcrp_functional(curves_blocks, *, faces=None, adjacency=None, vertices=None, n_fpca=5, decay_kind='exponential', decay_scale=None, alpha=1.0, prior=None, n_draws=200, burn_in=100, thin=2, chains=4, random_state=42, progress=True)[source]#

ddCRP on fPCA-compressed curve blocks (e.g. HKS and WKS together).

Each block is fPCA-compressed independently and the scores are concatenated with MFA-style first-singular-value balancing, then clustered by the spatial NIW ddCRP. Blocks must share the vertex axis.

Parameters:

  • curves_blocks (sequence of (V, T_b) arrays) – Curve stacks to fuse (e.g. [hks_VxT, wks_VxE]).

  • faces (ndarray | None)

  • adjacency (Any)

  • vertices (ndarray | None)

  • decay_kind (str)

  • decay_scale (float | None)

  • alpha (float)

  • prior (Any)

  • n_fpca (int)

  • n_draws (int)

  • burn_in (int)

  • thin (int)

  • chains (int)

  • random_state (int)

  • progress (bool)

Return type:

ClusterResult

:param : :param n_draws: As in cluster_ddcrp(). :param burn_in: As in cluster_ddcrp(). :param thin: As in cluster_ddcrp(). :param chains: As in cluster_ddcrp(). :param random_state: As in cluster_ddcrp(). :param progress: As in cluster_ddcrp(). :param n_fpca: fPCA components kept per block. :type n_fpca: int

Returns:

ClusterResult

Parameters:
Return type:

ClusterResult