spd_learn.models.SPDResNet#

class spd_learn.models.SPDResNet(n_chans: int = 22, n_outputs: int = 2, bimap_dims: tuple[int, ...]=(16, 12), num_res_blocks: int = 2, use_alem: bool = True, drop_prob: float = 0.0, input_type: str = 'raw', cov_method=<function covariance>, threshold: float = 0.0001, upper: bool = True, device: device | None = None, dtype: dtype | None = None)[source]#

Bases: Module

Riemannian Residual Network on the SPD Manifold (SPDResNet).

This class implements the Riemannian Residual Network architecture on the Symmetric Positive Definite (SPD) manifold, integrating spectral 1D-CNN residual blocks [Chen et al., 2024] with learnable Adaptive Log-Euclidean Metric (ALEM) deformation.

The architecture consists of:

  1. Preprocessing: Covariance estimation via CovLayer, trace normalization via TraceNorm, and learnable shrinkage regularization via Shrinkage.

  2. Riemannian Residual Stages: Dimension reduction via BiMap and non-linear eigenvalue rectification via ReEig, followed by SPDResBlock residual blocks on the SPD manifold.

  3. Riemannian-to-Euclidean Projection: Eigenvalue deformation via AdaptiveLogEuclidean followed by upper triangular vectorization via Vech (or standard LogEig when use_alem=False).

  4. Classification Head: Dropout regularization and a fully connected linear layer.

Parameters:

  • n_chans (int, default=22) – Number of input channels (electrodes in EEG).

  • n_outputs (int, default=2) – Number of output classes for classification.

  • bimap_dims (tuple of int, default=(16, 12)) – Subspace dimensions for successive BiMap stages.

  • num_res_blocks (int, default=2) – Number of SPDResBlock modules in each stage.

  • use_alem (bool, default=True) – Whether to use the Adaptive Log-Euclidean Metric (AdaptiveLogEuclidean) deformation before vectorization. If False, standard LogEig is used.

  • drop_prob (float, default=0.0) – Dropout probability applied before the linear classification layer.

  • input_type ({"raw", "cov"}, default="raw") – Format of input data (‘raw’ time series or precomputed ‘cov’ matrices).

  • cov_method (callable, default=covariance) – Method to compute covariance when input_type is ‘raw’.

  • threshold (float, default=1e-4) – Eigenvalue rectification threshold for ReEig.

  • upper (bool, default=True) – If True, only upper-triangular elements are used in tangent projection.

  • device (torch.device, optional) – Device on which module parameters are allocated. Default is None.

  • dtype (torch.dtype, optional) – Data type of module parameters. Default is None.

See also

SPDResBlock

Riemannian residual block with spectral 1D-CNN.

AdaptiveLogEuclidean

Learnable eigenvalue deformation metric.

GyroSPD

Manifold neural network using gyrovector space operations.

References

[1]

Ziheng Chen, Yue Song, Tianyang Xu, Zhiwu Huang, Xiao-Jun Wu, and Nicu Sebe. Adaptive log-euclidean metrics for SPD matrix learning. IEEE Transactions on Image Processing, 2024. doi:10.1109/TIP.2024.3496924.

Examples

>>> import torch
>>> from spd_learn.models import SPDResNet
>>> model = SPDResNet(n_chans=22, n_outputs=2)
>>> x = torch.randn(2, 22, 1000)
>>> out = model(x)
>>> out.shape
torch.Size([2, 2])
forward(x: Tensor) → Tensor[source]#

Forward pass of the SPDResNet model.

Parameters:

x (torch.Tensor) – Input tensor. If raw signal, shape is (batch_size, n_chans, n_times). If precomputed covariance, shape is (batch_size, n_chans, n_chans).

Returns:

Class logits of shape (batch_size, n_outputs).

Return type:

torch.Tensor