spd_learn.models.GraphCSPNet#

class spd_learn.models.GraphCSPNet(n_chans: int = 22, n_outputs: int = 4, n_freqs: int = 9, n_patches: int = 4, *, bimap_dims: Sequence[int] | None = None, dims: Sequence[int] | None = None, epoch_duration: float = 1.0, graph: TimeFrequencyGraph | None = None, segments: Sequence[tuple[int, int, int]] | None = None, bandwidth: float = 50.0, time_radius: float | None = None, frequency_radius: float = 16.0, ridge: float = 1e-05, shrinkage: float = 0.01, center: bool = True, use_mlp: bool = False, require_fitted_graph: bool = True, device=None, dtype=None)[source]#

Bases: Module

Graph-CSPNet for externally filtered multiband EEG.

See [Ju and Guan, 2024].

Parameters:

  • n_chans (int, default=22) – Number of ordered input electrodes.

  • n_outputs (int, default=4) – Number of output classes.

  • n_freqs (int, default=9) – Number of ordered filter-bank bands.

  • n_patches (int, default=4) – Number of windows per low-frequency band.

  • bimap_dims (sequence of int or None) – Successive output subspace dimensions for GraphBiMap layers; None scales the default (36, 22).

  • dims (sequence of int or None) – Consecutive matrix dimensions starting with n_chans; None scales the default (22, 36, 22).

  • epoch_duration (float, default=1.0) – Duration of the complete input epoch in seconds.

  • graph (TimeFrequencyGraph or None) – Optional graph matching the ordered segmentation and construction dtype/device.

  • segments (sequence of tuple or None) – Explicit (band, start, stop) sample windows; requires a matching graph.

  • bandwidth (float, default=50.0) – Positive divisor of squared AIRM distances in Gaussian edge weights.

  • time_radius (float or None) – Temporal radius in seconds; None uses half the epoch duration.

  • frequency_radius (float, optional, default=16.0) – Frequency neighborhood radius in Hz for the default graph.

  • ridge (float, default=1e-05) – Absolute covariance loading in squared signal units.

  • shrinkage (float, default=0.01) – Mixture weight of the trace-scaled identity, in [0, 1].

  • center (bool, default=True) – Subtract each channel mean within its window.

  • use_mlp (bool, default=False) – Use the optional two-hidden-layer classifier.

  • require_fitted_graph (bool, default=True) – Require training-only graph fitting before forward.

  • device (torch.device or str, optional) – Device for parameters and buffers.

  • dtype (torch.dtype, optional) – Data type for parameters and buffers.

Notes

Input is (trial, band, channel, sample); output is class logits. The default nine-band segmentation uses four windows in the first six bands and eight in the last three when n_patches=4. Fit the graph on training trials only. Covariance ridge and the ReEig floor are absolute: use consistent signal units above these floors. The classifier uses all log-matrix entries. Adam updates the host constrained coordinates, rather than the released optimizer trajectory.

See also

spd_learn.modules.TimeFrequencyCovariances, spd_learn.modules.TimeFrequencyGraph, spd_learn.modules.GraphBiMap

Examples

See sphx_glr_generated_auto_examples_howto_plot_graphcspnet.py for a small synthetic update. It does not reproduce dataset accuracy.

covariances(input: Tensor) → Tensor[source]#

Estimate the ordered time-frequency covariance nodes.

Parameters:

input (torch.Tensor) – Filtered trials of shape (batch, bands, channels, samples).

Returns:

Covariances of shape (batch, nodes, channels, channels), in squared signal units.

Return type:

torch.Tensor

fit_graph(training_signals: Tensor) → GraphCSPNet[source]#

Fit the local graph topology weights on training trials.

Parameters:

training_signals (torch.Tensor) – Training-only filtered trials of shape (batch, bands, channels, samples).

Returns:

self – The model with fitted graph weights.

Return type:

GraphCSPNet

Notes

This fits the graph lattice without updating batch-normalization statistics.

forward(input: Tensor) → Tensor[source]#

Classify externally filtered EEG trials.

Parameters:

input (torch.Tensor) – Filtered trials of shape (batch, bands, channels, samples), in consistent units.

Returns:

Unnormalized class logits of shape (batch, n_outputs).

Return type:

torch.Tensor

forward_covariances(input: Tensor) → Tensor[source]#

Classify precomputed covariance nodes.

Parameters:

input (torch.Tensor) – SPD nodes of shape (batch, nodes, channels, channels), in fitted graph order.

Returns:

Unnormalized class logits of shape (batch, n_outputs).

Return type:

torch.Tensor

load_state_dict(state_dict, strict=True, assign=False)[source]#

Load a checkpoint while preserving state after a failed load.

Parameters:

  • state_dict (dict) – Parameters and buffers returned by state_dict.

  • strict (bool, default=True) – Require the checkpoint keys to match the module state.

  • assign (bool, default=False) – Use checkpoint tensor properties when assigning state.

Returns:

Missing and unexpected checkpoint keys.

Return type:

NamedTuple

Notes

Reconstruct the same graph and segmentation configuration before loading. Failed loads restore tensor values and ownership, including assign=True.