spd-metrics-id: A Python Package for SPD-Aware Distance Metrics in Connectome Fingerprinting and Beyond

TL;DR

spd-metrics-id addresses the need for reliable SPD-aware distance computation across domains by unifying multiple geometry-aware metrics in a single Python package. It provides a CLI and Python API for reproducible analyses, with reproducibility secured via Docker images and a Zenodo DOI. The framework implements metrics such as Alpha-Z Bures-Wasserstein, Alpha-Procrustes, affine-invariant Riemannian, and log-Euclidean distances, enabling robust comparison of $SPD$ matrices in connectomics and beyond. The work demonstrates the package on connectome fingerprinting, highlighting improved identification performance compared with Euclidean or Pearson-based measures, and offers a broadly applicable tool for covariance analysis, diffusion tensor imaging, and other SPD-based tasks.

Abstract

We present spd-metrics-id, a Python package for computing distances and divergences between symmetric positive-definite (SPD) matrices. Unlike traditional toolkits that focus on specific applications, spd-metrics-id provides a unified, extensible, and reproducible framework for SPD distance computation. The package supports a wide variety of geometry-aware metrics, including Alpha-z Bures-Wasserstein, Alpha-Procrustes, affine-invariant Riemannian, log-Euclidean, and others, and is accessible both via a command-line interface and a Python API. Reproducibility is ensured through Docker images and Zenodo archiving. We illustrate usage through a connectome fingerprinting example, but the package is broadly applicable to covariance analysis, diffusion tensor imaging, and other domains requiring SPD matrix comparison. The package is openly available at https://pypi.org/project/spd-metrics-id/.

Figures (1)

• Figure 1: Pairwise distance matrix using Alpha-$z$ Bures--Wasserstein divergence ($\alpha=0.99, z=1.0$) for 30 subjects. Correct within-subject matches appear along the diagonal.