SPD-Metrics-ID: Geometry-Aware SPD Distances

• spd-metrics-id is a Python package that computes distances and divergences between symmetric positive-definite matrices treated as points on a Riemannian manifold.
• It implements a range of metrics including affine-invariant, log-Euclidean, and Bures–Wasserstein methods to improve the robustness of covariance comparisons.
• The package is designed for reproducibility and scalability, featuring both a Python API and CLI to support applications like connectome fingerprinting.

Searching arXiv for papers directly related to spd-metrics-id and closely connected SPD-metric frameworks. spd-metrics-id is a Python package for computing distances and divergences between symmetric positive-definite (SPD) matrices, designed as a unified, extensible, and reproducible framework for geometry-aware SPD distance computation in connectome fingerprinting and related covariance-based tasks (Uddin, 6 Oct 2025). Its central premise is that SPD matrices inhabit a smooth Riemannian manifold rather than a flat Euclidean space, so distance functions such as affine-invariant, log-Euclidean, and Bures–Wasserstein metrics can be more faithful than elementwise Euclidean or correlation-based comparisons when the objects of interest are covariance matrices, functional connectomes, diffusion tensors, or other SPD descriptors (Ju et al., 26 Apr 2025).

1. Mathematical setting and motivation

An SPD matrix $C$ is a symmetric matrix satisfying $C=C^\top$ and $x^\top C x>0$ for all non-zero vectors $x$. The set of all $n\times n$ SPD matrices, $\mathcal{S}_{++}^n$, forms a smooth manifold rather than a vector space, and this distinction is consequential for similarity computation, interpolation, and optimization (Ju et al., 26 Apr 2025). In covariance-based neuroimaging, SPD matrices arise as covariance or functional connectivity matrices between brain regions; in diffusion tensor imaging, each voxel is an SPD diffusion tensor; in statistics and machine learning, SPD matrices appear as covariance matrices, kernel matrices, or structure tensors (Uddin, 6 Oct 2025).

Two canonical metrics organize much of the broader literature. The affine-invariant Riemannian metric uses the geodesic distance

$$d_{\mathrm{AIRM}}(X,Y)=\left\| \log\left(X^{-1/2}YX^{-1/2}\right)\right\|_F,$$

and is characterized by affine invariance under congruence transforms, a property that is especially relevant when linear mixing or re-referencing should not alter distances (Uddin, 6 Oct 2025). The log-Euclidean metric instead maps SPD matrices into the vector space of symmetric matrices through the matrix logarithm, giving

$$d_{\mathrm{LE}}(X,Y)=\left\|\log X-\log Y\right\|_F,$$

which preserves SPD structure while making many computations Euclidean in the log domain (Ju et al., 26 Apr 2025). A third major geometry implemented in the package is the Bures–Wasserstein distance, whose squared form for $X,Y\in\mathcal{S}_{++}^n$ is

$$d_{\mathrm{BW}}^2(X,Y)=\operatorname{Tr}(X)+\operatorname{Tr}(Y)-2\operatorname{Tr}\big((X^{1/2}YX^{1/2})^{1/2}\big),$$

an optimal-transport-derived metric for zero-mean Gaussian covariances (Uddin, 6 Oct 2025).

This geometric viewpoint is the background against which spd-metrics-id is positioned. The package is task-oriented and focused on SPD distance computation at scale, especially for connectome fingerprinting workflows, whereas the surrounding literature also studies manifold statistics, pullback metrics, metric learning, and full SPD neural-network stacks (Uddin, 6 Oct 2025).

2. Implemented distances and metric families

The package exposes several distances and divergences through both a Python API and a command-line interface. The paper lists the following implemented metrics: Alpha-$C=C^\top$0 Bures–Wasserstein, Alpha-Procrustes, Bures–Wasserstein, affine-invariant Riemannian metric (“Geodesic” in the package tables), Log–Euclidean, Pearson-based distance, and Euclidean distance (Uddin, 6 Oct 2025).

Metric	CLI keyword	Note in package context
Alpha-$C=C^\top$1 Bures–Wasserstein	alpha_z	uses --alpha and --z
Alpha-Procrustes	alpha_pro	uses --alpha
Bures–Wasserstein	bw	optimal-transport covariance distance
Affine-invariant Riemannian metric	ai	appears as “Geodesic”
Log–Euclidean	log	uses matrix logarithms
Pearson-based distance	pearson	baseline comparator
Euclidean distance	euclid	baseline comparator

The Alpha-$C=C^\top$2 Bures–Wasserstein divergence is the package’s principal parametric family. The software note states that it references Dinh et al. (2021), is exposed as --metric alpha_z, and commonly uses $C=C^\top$3 and $C=C^\top$4 in the connectome fingerprinting demonstration; when $C=C^\top$5 and $C=C^\top$6, the divergence approaches the standard Bures–Wasserstein distance (Uddin, 6 Oct 2025). Alpha-Procrustes is likewise parameterized by --alpha and is included as a geometry-aware alternative, though the software note delegates the precise closed form to Minh (2022) (Uddin, 6 Oct 2025).

The metric menu reflects a wider literature in which SPD geometry is not unique. Reviews of covariance-based neuroimaging center AIRM and log-Euclidean geometry, but also note Fisher information metrics of elliptical distributions, power-Euclidean, Log-Cholesky, Bures–Wasserstein, Thompson’s metric, and others (Ju et al., 26 Apr 2025). More abstractly, there are power-affine and deformed-affine continuums of affine-invariant metrics (Thanwerdas et al., 2019), pullback Euclidean metrics underlying log-Euclidean and Log-Cholesky constructions (Chen et al., 2023), and adaptive Log-Euclidean families with learnable parameters (Chen et al., 2023). Within that landscape, spd-metrics-id concentrates on a finite set of practically usable comparison functions rather than on learnable or task-specific metric tensors.

3. Software architecture, interfaces, and reproducibility

The package structure is deliberately lightweight. The paper identifies three main modules: spd_metrics_id.io for I/O utilities, spd_metrics_id.distance for metric functions, and spd_metrics_id.id_rate for connectome fingerprinting utilities such as compute_id_rate(D) (Uddin, 6 Oct 2025). A representative distance function shown explicitly is alpha_z_bw(A, B, [alpha](https://www.emergentmind.com/topics/ai-autonomy-coefficient-alpha), z), used through the Python API.

The main console script is spd-id. The documented interface includes --base-path, --tasks, --scan-types, --resolutions, --metric, --alpha, --z, --tau, and --num-subjects; the supported metric keywords are alpha_z, alpha_pro, bw, ai, log, pearson, and euclid (Uddin, 6 Oct 2025). The parameter --tau is an SPD regularization parameter intended to nudge matrices away from singularity, for example through a transformation of the form $C=C^\top$7, which is relevant when empirical covariance matrices are ill-conditioned or only positive semidefinite (Uddin, 6 Oct 2025).

Reproducibility is treated as a first-class design principle. The software note states that the package is distributed through PyPI, source code is hosted on GitHub, a Docker image is provided for environment encapsulation, and a Zenodo archival snapshot is available as KaosarUddin/b_f: spd-metrics-id v1.0.1 with DOI 10.5281/zenodo.15891140 (Uddin, 6 Oct 2025). The same note explicitly frames the package as complementing more general toolkits such as Nilearn, Brain Connectivity Toolbox, or geomstats, rather than replacing them (Uddin, 6 Oct 2025).

This focus distinguishes spd-metrics-id from broader SPD software stacks. For example, “SPD Learn” provides core SPD operators, neural-network layers, and reference SPDNet-based models, while spd-metrics-id remains centered on distance computation, connectome comparison, and identification-rate workflows (Aristimunha et al., 26 Feb 2026).

4. Connectome fingerprinting workflow

The package’s canonical application is connectome fingerprinting. In the demonstration described in the software note, 30 Human Connectome Project subjects are used, a 100-region parcellation is employed, and two scans per subject—LR and RL—are compared for resting-state fMRI (Uddin, 6 Oct 2025). Each subject-scan pair is represented by an SPD functional-connectivity matrix, and pairwise cross-scan distances are computed: $C=C^\top$8 For each row, the nearest subject under the chosen metric determines whether identification is correct; compute_id_rate(D) implements this logic (Uddin, 6 Oct 2025).

The paper’s Python example uses: $x^\top C x>0$6

The package note reports that the Alpha-$C=C^\top$9 Bures–Wasserstein distance yields a prominent low-distance diagonal in the LR–RL pairwise matrix and consistently assigns the lowest within-subject distance across subjects in the demonstration (Uddin, 6 Oct 2025). By contrast, the same note reports that Pearson-based and Euclidean baselines can assign spuriously low distances between different individuals, producing misidentifications. In the table for distances from one anchor subject, all of Alpha-$x^\top C x>0$0, Alpha Procrustes, BW, Geodesic, and Log–Euclidean identify the correct self-match, while Pearson and Euclidean do not (Uddin, 6 Oct 2025). The package’s central empirical claim is therefore narrow but consequential: geometry-aware SPD metrics are crucial for reliable connectome fingerprinting in the illustrated workflow (Uddin, 6 Oct 2025).

5. Relation to the broader SPD-metric literature

spd-metrics-id belongs to a larger methodological tradition in which SPD matrices are treated as first-class geometric objects. In covariance-based neuroimaging, SPD matrices encode inter-channel relationships and functional connectivity across EEG, MEG, ECoG, fMRI, DTI, and deformation-tensor settings; the review literature organizes the field around manifold-aware statistics, tangent-space models, kernel methods, and geometric deep learning (Ju et al., 26 Apr 2025). Connectome fingerprinting is one specific use case within that broader family of covariance comparison problems.

The package’s implemented metrics map cleanly onto major theoretical families. AIRM is the canonical congruence-invariant Riemannian metric on $x^\top C x>0$1; LEM is a pullback Euclidean metric induced by the matrix logarithm; Bures–Wasserstein is an optimal-transport geometry on Gaussian covariances (Ju et al., 26 Apr 2025). Theoretical work further shows that the log-Euclidean and Log-Cholesky metrics can be treated as pullback Euclidean metrics, enabling intrinsic multinomial logistic regression and other classifiers directly on SPD manifolds (Chen et al., 2023). Other work extends the idea by learning the geometry itself, for example through Adaptive Log-Euclidean Metrics, which replace the fixed matrix logarithm by a learnable family of log-like maps while preserving a pullback construction (Chen et al., 2023).

At the software level, these distinctions matter because a package restricted to pairwise distance computation occupies a different layer of the stack from libraries intended for end-to-end SPD neural networks. “SPD Learn,” for instance, includes CovLayer, BiMap, ReEig, LogEig, SPDBatchNormMean, SPDBatchNormMeanVar, and reference SPDNet-based models for neural decoding; spd-metrics-id, by contrast, is intentionally lightweight and specialized for SPD-aware comparison and identification-rate analysis (Aristimunha et al., 26 Feb 2026). A plausible implication is that spd-metrics-id can serve as the distance-computation component inside broader SPD pipelines, but the package note itself restricts its claims to comparison, fingerprinting, and reproducibility infrastructure.

6. Practical considerations, limitations, and usage boundaries

Metric choice remains application-dependent. The package note recommends Alpha-$x^\top C x>0$2 Bures–Wasserstein when strong discriminative power for individual differences is desired, standard BW when an optimal-transport interpretation is preferred, AIRM when affine invariance is critical, and Log–Euclidean when computational efficiency and numerical simplicity are prioritized (Uddin, 6 Oct 2025). Pearson-based and Euclidean distances are retained as baselines and debugging comparators rather than as geometry-aware defaults (Uddin, 6 Oct 2025).

Computationally, the package inherits the familiar costs of SPD geometry. AIRM, BW, Alpha-$x^\top C x>0$3, and Alpha-Procrustes require matrix square roots, logarithms, or eigendecompositions, with roughly $x^\top C x>0$4 cost per distance for $x^\top C x>0$5 matrices; this is manageable for typical connectome sizes such as 100–300 ROIs but can become burdensome at higher resolutions (Uddin, 6 Oct 2025). Ill-conditioning is a second practical issue, which is why the software exposes --tau to regularize matrices toward strict positive-definiteness (Uddin, 6 Oct 2025).

The paper is also explicit about scope. Its demonstration is centered on a single dataset configuration—30 Human Connectome Project subjects, a 100-region parcellation, and LR/RL resting-state scans—and does not claim exhaustive benchmarking across all neuroimaging settings (Uddin, 6 Oct 2025). A broader limitation, emphasized by the surrounding literature, is that no single SPD metric is universally optimal: the neuroimaging review highlights AIRM’s mixing invariance and log-Euclidean efficiency, while also noting that Bures/Wasserstein and Cholesky-type metrics remain under-explored in many decoding tasks (Ju et al., 26 Apr 2025). This suggests that spd-metrics-id is best understood not as a final answer to metric selection, but as a reproducible and extensible environment in which such selections can be tested systematically.