spd_learn.models.SPDTransNet#

class spd_learn.models.SPDTransNet(matrix_size=9, n_bands=7, n_subwindows=30, context_epochs=21, token_matrix_size=26, feature_tokens=10, intra_heads=9, inter_heads=3, intra_layers=5, inter_layers=4, feedforward_dim=1035, classifier_dim=1035, n_outputs=5, dropout=0.1, *, preserve_norm=False, eigenvalue_floor=0.01, matrix_scale=1.01, device=None, dtype=None)[source]#

Bases: Module

Structure-preserving contextual classifier for prepared SPD sequences.

See [Seraphim et al., 2024].

Parameters:

matrix_size (int, default=9) – Prepared SPD size (8 electrodes plus augmentation in the publication).
n_bands (int, default=7) – Number of ordered filtered signal channels, distinct from electrodes.
n_subwindows (int, default=30) – Chronological subwindows per epoch (publication: thirty 1-second windows).
context_epochs (int, default=21) – Odd total epoch count L, in chronological order; predict epoch L//2. The author’s extra_epochs_on_each_side equals (L-1)/2.
token_matrix_size (int, default=26) – Symmetric dimension m after the affine token projection; D=m(m+1)/2.
feature_tokens (int, default=10) – t contiguous groups per epoch, dividing n_bands*n_subwindows.
intra_heads (int, default=9) – Number of intra-epoch attention heads; must divide the embedding dimension.
inter_heads (int, default=3) – Number of inter-epoch attention heads; must divide the embedding dimension.
intra_layers (int, default=5) – Number of intra-epoch encoder layers.
inter_layers (int, default=4) – Number of inter-epoch encoder layers.
feedforward_dim (int, default=1035) – Triangular intermediate dimension in both encoder FF networks.
classifier_dim (int, default=1035) – Width of each of two Linear/ReLU/Dropout classifier blocks.
n_outputs (int, default=5) – Logit class count; author label order is N3, N2, N1, REM, Awake.
dropout (float, default=0.1) – Encoder attention/FF/residual and classifier dropout probability.
preserve_norm (bool, default=False) – Raw upper log coordinates match the author implementation. True chooses isometric sqrt(2)-weighted upper coordinates; this changes parametrization.
eigenvalue_floor (float or None, default=0.01) – Floor after scaling at tokenizer boundary; explicit PSD regularization.
matrix_scale (float, default=1.01) – Positive multiplier before flooring and matrix log.
device (torch.device or str, optional) – Device for parameters and buffers.
dtype (torch.dtype, optional) – Data type for parameters and buffers.

Notes

Input has axes (batch, epoch, band, window, row, column); prediction targets the central epoch. Past and future context are used, so the model is noncausal. Keep contexts within recording and split boundaries. Filtering, covariance augmentation and whitening are external. Published full-recording whitening uses unlabeled target data and must be declared as transductive.