spectralbrain.statistics.atlas_stats

Cluster-vs-atlas comparison statistics.

Compare SpectralBrain’s data-driven partitions against reference atlases with the size-matched-null framework that the parcellation-evaluation literature (Arslan 2018; Eickhoff 2015; Craddock 2012) requires: ARI/AMI/NMI/VI and within-parcel homogeneity are all confounded by parcel number and size, so every quality number is reported against a size-matched random contiguous parcellation, never on its own.

This module complements spectralbrain.utils.atlas (which provides atlas label lookups) with the statistical comparison of partitions.

• compare_partitions() – ARI, AMI, NMI, VI.

• parcel_overlap() – Dice/Jaccard contingency + best-match mapping.

• spectral_homogeneity() – within-parcel descriptor homogeneity.

• random_parcellation() – contiguous size-matched null (graph Voronoi).

• homogeneity_vs_null() – observed homogeneity vs the null distribution.

• cluster_atlas_concordance() – full report with a size-matched null z/p.

• aggregate_across_subjects() – median + bootstrap CI for a cohort.

• spatial_rand_index() – spatially-aware ARI (spARI).

Functions

cluster_atlas_concordance(cluster_labels, ...)	Full cluster-vs-atlas concordance with a size-matched ARI null.
homogeneity_vs_null(features, labels, *[, ...])	Within-parcel homogeneity vs a size-matched random-parcellation null.
random_parcellation(n_parcels, *[, faces, ...])	Contiguous size-matched random parcellation (graph Voronoi).

spectralbrain.statistics.atlas_stats.adjusted_rand_index(labels_a, labels_b)

Classical Adjusted Rand Index (exact, via scikit-learn).

Parameters:

• labels_a (ndarray)

• labels_b (ndarray)

Return type:

float

spectralbrain.statistics.atlas_stats.aggregate_across_subjects(values, n_boot=5000, ci=0.95, seed=0)

Median + bootstrap CI of a per-subject metric (clinical-cohort summary).

For a small clinical cohort, prefer per-subject cluster-vs-atlas comparison followed by this aggregation over a single group statistic (Eickhoff 2015).

Returns:

dict – median, ci_low, ci_high, mean, n.

Parameters:

• values (Sequence[float])

• n_boot (int)

• ci (float)

• seed (int)

Return type:

Dict[str, float]

spectralbrain.statistics.atlas_stats.cluster_atlas_concordance(cluster_labels, atlas_labels, *, faces=None, adjacency_list=None, distance=None, coords=None, background=None, n_null=100, seed=0, progress=False)

Full cluster-vs-atlas concordance with a size-matched ARI null.

Computes ARI/AMI/NMI/VI and mean best-Dice between the data-driven clusters and the atlas, optionally spARI (if distance/coords given), and the distribution of ARI between a size-matched random contiguous parcellation and the atlas. A significant positive ARI z-score means the clusters match the atlas more than a random parcellation of the same granularity would (Arslan 2018). Accepts faces or adjacency_list for the null.

Parameters:

• cluster_labels (ndarray)

• atlas_labels (ndarray)

• faces (ndarray | None)

• adjacency_list (Sequence[ndarray] | None)

• distance (ndarray | None)

• coords (ndarray | None)

• background (int | None)

• n_null (int)

• seed (int)

• progress (bool)

Return type:

dict

spectralbrain.statistics.atlas_stats.compare_partitions(labels_a, labels_b, mask=None)

ARI, AMI, NMI and variation of information between two labellings.

Parameters:

• labels_a (np.ndarray, shape (V,))

• labels_b (np.ndarray, shape (V,))

• mask (np.ndarray of bool, optional) – If given, restrict to mask (e.g. drop medial-wall/background vertices).

Returns:

dict – Keys ari (Hubert & Arabie 1985), ami and nmi (Vinh 2010), vi_bits (Meila 2007), n_clusters_a, n_clusters_b.

Return type:

Dict[str, float]

Notes

All of these depend on cluster count/size; compare only granularity-matched partitions, or interpret against a size-matched null (see cluster_atlas_concordance()).

spectralbrain.statistics.atlas_stats.homogeneity_vs_null(features, labels, *, faces=None, adjacency_list=None, n_null=100, method='correlation', seed=0, progress=False)

Within-parcel homogeneity vs a size-matched random-parcellation null.

Accepts faces or adjacency_list. Returns observed, null_mean, null_std, z and one-sided empirical p.

Parameters:

• features (ndarray)

• labels (ndarray)

• faces (ndarray | None)

• adjacency_list (Sequence[ndarray] | None)

• n_null (int)

• method (str)

• seed (int)

• progress (bool)

Return type:

dict

spectralbrain.statistics.atlas_stats.normalized_mutual_info(labels_a, labels_b)

Classical Normalized Mutual Information (exact, via scikit-learn).

Parameters:

• labels_a (ndarray)

• labels_b (ndarray)

Return type:

float

spectralbrain.statistics.atlas_stats.parcel_overlap(cluster_labels, atlas_labels, background=None)

Dice/Jaccard overlap between data-driven clusters and atlas ROIs.

Parameters:

• cluster_labels (np.ndarray, shape (V,))

• atlas_labels (np.ndarray, shape (V,))

• background (int, optional) – Atlas label to exclude (e.g. 0 medial wall).

Returns:

dict – dice (C x A matrix), jaccard (C x A), cluster_ids, atlas_ids, best_atlas_for_cluster (mapping + Dice), mean_best_dice (mean over clusters of their best atlas Dice).

Return type:

Dict[str, object]

spectralbrain.statistics.atlas_stats.random_parcellation(n_parcels, *, faces=None, adjacency_list=None, n_vertices=None, seed=0)

Contiguous size-matched random parcellation (graph Voronoi).

Accepts either faces (preferred) or a precomputed adjacency_list.

Parameters:

• n_parcels (int)

• faces (ndarray | None)

• adjacency_list (Sequence[ndarray] | None)

• n_vertices (int | None)

• seed (int)

spectralbrain.statistics.atlas_stats.spatial_rand_index(labels_a, labels_b, coords=None, distance=None, length_scale=None, adjusted=True)

Spatially-aware (adjusted) Rand index.

Concordant pairs (same/same or different/different in both partitions) score 1; disagreement pairs score a distance-dependent weight w_ij in [0, 1] (closer disagreements are treated as less severe). The raw spRI is the mean pair score; the adjusted spARI rescales against a permutation chance baseline.

Parameters:

• labels_a (np.ndarray, shape (V,))

• labels_b (np.ndarray, shape (V,))

• coords (np.ndarray, shape (V, k), optional) – Vertex coordinates; used to derive distances if distance is None.

• distance (np.ndarray, shape (V, V), optional) – Precomputed (e.g. geodesic) distance matrix; preferred for surfaces.

• length_scale (float, optional) – Kernel length scale; defaults to the median pairwise distance.

• adjusted (bool) – If True also compute spARI against a label-permutation baseline.

Returns:

dict – Keys: spRI, spARI (NaN if adjusted=False), length_scale, validated_against_R (always False here).

Return type:

Dict[str, object]

spectralbrain.statistics.atlas_stats.spectral_homogeneity(features, labels, method='correlation', size_weighted=True)

Within-parcel descriptor homogeneity (Schaefer/Gordon/Craddock style).

Parameters:

• features (np.ndarray, shape (V, d)) – Per-vertex descriptors (e.g. HKS/WKS/SI-HKS).

• labels (np.ndarray, shape (V,))

• method ({"correlation", "first_eigenvalue"}) – "correlation": mean pairwise correlation of member feature vectors within a parcel. "first_eigenvalue": fraction of variance explained by the first principal component within a parcel.

• size_weighted (bool) – Weight parcels by size when averaging.

Returns:

float – Mean within-parcel homogeneity in [0, 1] (approx).

Return type:

float

Notes

Homogeneity rises mechanically as parcels shrink; ALWAYS compare against a size-matched null (homogeneity_vs_null()).

spectralbrain.statistics.atlas_stats.variation_of_information(labels_a, labels_b)

Variation of Information (Meila 2007), a true metric on partitions (bits).

Returns:

float – VI = H(A) + H(B) - 2 I(A; B) in bits (0 = identical partitions).

Parameters:

• labels_a (ndarray)

• labels_b (ndarray)

Return type:

float