---
title: 'SPD-Metrics-ID: Geometry-Aware SPD Distances'
url: https://www.emergentmind.com/topics/spd-metrics-id
type: topic
---

# SPD-Metrics-ID: Geometry-Aware SPD Distances

Searching arXiv for recent 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 [2510.04438]. 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 [2504.18882].

## 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 [2504.18882]. 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 [2510.04438].

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 [2510.04438]. 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 [2504.18882]. 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 [2510.04438].

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 [2510.04438].

## 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-\(z\) Bures–Wasserstein, Alpha-Procrustes, Bures–Wasserstein, affine-invariant Riemannian metric (“Geodesic” in the package tables), Log–Euclidean, Pearson-based distance, and Euclidean distance [2510.04438].

| Metric | CLI keyword | Note in package context |
|---|---|---|
| Alpha-\(z\) 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-\(z\) 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 \(\alpha=0.99\) and \(z=1.0\) in the connectome fingerprinting demonstration; when \(\alpha\to 1\) and \(z=1\), the divergence approaches the standard Bures–Wasserstein distance [2510.04438]. 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) [2510.04438].

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 [2504.18882]. More abstractly, there are power-affine and deformed-affine continuums of affine-invariant metrics [1906.01349], pullback Euclidean metrics underlying log-Euclidean and Log-Cholesky constructions [2305.11288], and adaptive Log-Euclidean families with learnable parameters [2303.15477]. 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)` [2510.04438]. A representative distance function shown explicitly is `alpha_z_bw(A, B, 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` [2510.04438]. The parameter `--tau` is an SPD regularization parameter intended to nudge matrices away from singularity, for example through a transformation of the form \(\tilde X = X + \tau I\), which is relevant when empirical covariance matrices are ill-conditioned or only positive semidefinite [2510.04438].

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` [2510.04438]. The same note explicitly frames the package as complementing more general toolkits such as Nilearn, Brain Connectivity Toolbox, or geomstats, rather than replacing them [2510.04438].

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 [2602.22895].

## 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 [2510.04438]. Each subject-scan pair is represented by an SPD functional-connectivity matrix, and pairwise cross-scan distances are computed:
\[
D^{(1\to 2)}_{ij}=d(X_i^{(1)},X_j^{(2)}), \qquad
D^{(2\to 1)}_{ij}=d(X_i^{(2)},X_j^{(1)}).
\]
For each row, the nearest subject under the chosen metric determines whether identification is correct; `compute_id_rate(D)` implements this logic [2510.04438].

The paper’s Python example uses:
```python
import numpy as np
from spd_metrics_id.io import find_subject_paths, load_matrix
from spd_metrics_id.distance import alpha_z_bw
from spd_metrics_id.id_rate import compute_id_rate

base = "connectomes_100/"
lr_paths = find_subject_paths(base, "REST", "LR", [100], n=30)
rl_paths = find_subject_paths(base, "REST", "RL", [100], n=30)

mats_lr = [load_matrix(p) for p in lr_paths]
mats_rl = [load_matrix(p) for p in rl_paths]

D12 = np.array([[alpha_z_bw(A, B, alpha=0.99, z=1.0) for B in mats_rl]
                for A in mats_lr])
D21 = np.array([[alpha_z_bw(A, B, alpha=0.99, z=1.0) for B in mats_lr]
                for A in mats_rl])

id1 = compute_id_rate(D12)
id2 = compute_id_rate(D21)
print("ID_Rate:", (id1 + id2) / 2)
```

The package note reports that the Alpha-\(z\) 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 [2510.04438]. 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-\(z\), Alpha Procrustes, BW, Geodesic, and Log–Euclidean identify the correct self-match, while Pearson and Euclidean do not [2510.04438]. 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 [2510.04438].

## 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 [2504.18882]. 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 \(\mathcal S_{++}^n\); LEM is a pullback Euclidean metric induced by the matrix logarithm; Bures–Wasserstein is an optimal-transport geometry on Gaussian covariances [2504.18882]. 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 [2305.11288]. 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 [2303.15477].

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 [2602.22895]. 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-\(z\) 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 [2510.04438]. Pearson-based and Euclidean distances are retained as baselines and debugging comparators rather than as geometry-aware defaults [2510.04438].

Computationally, the package inherits the familiar costs of SPD geometry. AIRM, BW, Alpha-\(z\), and Alpha-Procrustes require matrix square roots, logarithms, or eigendecompositions, with roughly \(O(n^3)\) cost per distance for \(n\times n\) matrices; this is manageable for typical connectome sizes such as 100–300 ROIs but can become burdensome at higher resolutions [2510.04438]. Ill-conditioning is a second practical issue, which is why the software exposes `--tau` to regularize matrices toward strict positive-definiteness [2510.04438].

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 [2510.04438]. 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 [2504.18882]. 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.

Source: https://www.emergentmind.com/topics/spd-metrics-id