eegproc.deep_learning.unsupervised.GNN.GCN module

class eegproc.deep_learning.unsupervised.GNN.GCN.GCNDecoder(timesteps, n_channels, n_bands, t_down, gcn_units, temporal_pool_sizes, emb_dim=128, dropout=0.1, activation='relu', use_batch_norm=False, graph_self_loop_bias=2.0, graph_identity_mix=0.0, graph_adjacency_reg_weight=0.0001, name='decoder_gcn', **kwargs)

Bases: Model

Graph-aware decoder for GCNEncoder latent sequences.

The decoder first restores temporal resolution. It then projects each latent timestep into a distinct feature vector for every electrode, reshapes that vector back to a graph, and applies residual graph-convolution blocks before reconstructing the frequency-band values at each node.

This is intentionally different from a purely temporal Conv1D decoder: the output is reconstructed as n_channels graph nodes rather than as one undifferentiated flat feature vector.

Parameters:

• timesteps (int)

• n_channels (int)

• n_bands (int)

• t_down (int)

• gcn_units (tuple[int, ...])

• temporal_pool_sizes (tuple[int, ...] | None)

• emb_dim (int, default: 128)

• dropout (float, default: 0.1)

• activation (str, default: 'relu')

• use_batch_norm (bool, default: False)

• graph_self_loop_bias (float, default: 2.0)

• graph_identity_mix (float, default: 0.0)

• graph_adjacency_reg_weight (float, default: 0.0001)

• name (str, default: 'decoder_gcn')

call(inputs, training=False)

Decode latent sequences into channel-specific EEG graph signals.

Parameters:

training (bool, default: False)

compute_output_shape(input_shape)

Return the decoder output shape.

fix_length(x)

Trim or pad the reconstructed sequence to exactly timesteps.

Parameters:

x (Tensor)

Return type:

Tensor

classmethod from_encoder(encoder, name='decoder_gcn')

Create a graph-aware decoder from a configured encoder.

Parameters:

• encoder (GCNEncoder)

• name (str, default: 'decoder_gcn')

Return type:

GCNDecoder

get_adjacency_matrices()

Return normalized decoder electrode graphs for diagnostics.

Return type:

dict[str, Tensor]

get_config()

Return serializable configuration for the decoder.

Return type:

dict

property n_features: int

Flattened number of reconstructed channel-band features.

class eegproc.deep_learning.unsupervised.GNN.GCN.GCNEncoder(timesteps, t_down, n_channels=14, n_bands=4, gcn_units=(64, 32), temporal_pool_sizes=None, emb_dim=128, dropout=0.1, activation='relu', use_batch_norm=False, graph_self_loop_bias=2.0, graph_identity_mix=0.0, graph_adjacency_reg_weight=0.0001, name='encoder_gcn', **kwargs)

Bases: BaseEncoder

Residual, node-preserving GCN encoder for EEG sequence data.

The input is a sequence of flattened channel-band vectors with shape (batch, timesteps, n_channels * n_bands). At each timestep, the vector is reshaped to (n_channels, n_bands) so that electrodes are graph nodes and frequency bands are node features. A single electrode adjacency is shared across theta, alpha, beta, and gamma; the feature projection can subsequently learn interactions among those four band features.

Unlike a global-average graph readout, this encoder retains every node’s representation by concatenating the node embeddings in the fixed electrode order before temporal pooling. Residual graph blocks provide a node-local path around adjacency mixing, which reduces graph over-smoothing and keeps electrode-specific information available to the latent representation.

The public output interface remains (batch, ceil(timesteps / t_down), emb_dim) so that the encoder remains compatible with the existing joint VAE/VC architecture and BiLSTM head.

Parameters:

• timesteps (int)

• t_down (int)

• n_channels (int, default: 14)

• n_bands (int, default: 4)

• gcn_units (tuple[int, ...], default: (64, 32))

• temporal_pool_sizes (tuple[int, ...] | None, default: None)

• emb_dim (int, default: 128)

• dropout (float, default: 0.1)

• activation (str, default: 'relu')

• use_batch_norm (bool, default: False)

• graph_self_loop_bias (float, default: 2.0)

• graph_identity_mix (float, default: 0.0)

• graph_adjacency_reg_weight (float, default: 0.0001)

• name (str, default: 'encoder_gcn')

call(inputs, training=False)

Encode EEG while retaining electrode-specific graph features.

Parameters:

training (bool, default: False)

get_adjacency_matrices()

Return normalized electrode adjacency matrices for diagnostics.

Return type:

dict[str, Tensor]

get_config()

Return serializable configuration for the encoder.

Return type:

dict

property n_features: int

Flattened number of channel-band features per timestep.