Scope and Data Representations#

What SPD Learn Targets#

SPDLearn focuses on geometric deep learning on symmetric positive definite (SPD) manifolds for neural decoding with covariance or connectivity matrices, with a primary emphasis on EEG and fMRI.

EEG covariance matrices from multichannel time series
fMRI functional connectivity matrices from regional time series

The library is designed to integrate with established EEG and fMRI workflows (e.g., MOABB and Nilearn) and to support reproducible pipelines built around SPDNet-based models.

SPD Data in Practice#

Given a multichannel signal matrix \(X \in \reals^{C \times T}\) (channels x time), a sample covariance matrix is:

\[C = \frac{1}{T - 1} (X - \bar{X})(X - \bar{X})^\top\]

This yields an SPD matrix when the sample count is sufficient. SPD Learn provides utility layers such as CovLayer to compute covariance matrices from raw signals and feed them to neural network layers. The following covariance estimation methods are supported:

covariance(): Empirical covariance.
sample_covariance(): Sample covariance with Bessel correction.
real_covariance(): Real part of the covariance for complex signals.
cross_covariance(): Cross-frequency covariance matrix.

Estimation Essentials#

Sample size: if the temporal dimension is smaller than the number of channels, i.e., \(T < C\), empirical covariances are rank-deficient. Use shrinkage or reduce dimensionality before forming covariances.
Regularization: Shrinkage estimators (e.g., ledoit_wolf() or OAS) stabilize covariance estimates when samples are limited.
Numerical safety: handling “bad values” (e.g., non-finite inputs or rank-deficient matrices) is critical for Riemannian stability. SPD Learn enforces positive definiteness through small diagonal jitter or eigenvalue clipping, ensuring that downstream operations like matrix logarithms and inversions remain well-conditioned [Higham, 2002].
Precision considerations: numerical precision (e.g., float32 vs float64) directly impacts the accuracy of geometric computations. While float32 is often sufficient for deep learning, double precision (float64) is recommended for ill-conditioned matrices to prevent numerical drift. The library provides stable alternatives like the Log-Cholesky representation [Lin, 2019], which avoids expensive eigendecompositions while maintaining stability. Please refer to Numerical Stability for more details on handling different precision data.

For practical examples, see User Guide and the API docs for CovLayer and Shrinkage.