eegproc.deep_learning.supervised.rnn_architectures module

Supervised RNN classifier architectures for EEG sequence data.

The builders in this module can be used in three ways:

  1. build() creates a complete, compiled standalone classifier.

  2. build_feature_extractor() creates only the recurrent temporal encoder and pooling pathway, returning one sequence-level embedding per sample.

  3. build_sequence_summarizer() returns the final recurrent state without temporal pooling. This is useful when every ordered element in a sequence must contribute to a trial-level representation.

The feature-extractor form is meant for larger models in which another component, such as a variational classifier, owns the final classification head and loss.

class eegproc.deep_learning.supervised.rnn_architectures.BiGRUClassifier(timesteps, n_features, n_classes, gru_units=128, n_bigru_layers=2, dropout=0.1, loss='softmax_crossentropy', optimizer='adam', metrics=None, name='bigru_classifier', alpha=1.0, beta=1.0, gamma=0.0, lambda_=0.0)[source]

Bases: RNNClassifier

Bidirectional GRU classifier for EEG sequence data.

Parameters:

  • timesteps (int | None)

  • n_features (int)

  • n_classes (int)

  • gru_units (int | Sequence[int], default: 128)

  • n_bigru_layers (int, default: 2)

  • dropout (float, default: 0.1)

  • loss (str | Callable | Loss, default: 'softmax_crossentropy')

  • optimizer (str | Optimizer, default: 'adam')

  • metrics (list[str] | None, default: None)

  • name (str, default: 'bigru_classifier')

  • alpha (float, default: 1.0)

  • beta (float, default: 1.0)

  • gamma (float, default: 0.0)

  • lambda_ (float, default: 0.0)

recurrent_layer(layer_index, *, return_sequences)[source]

Create one recurrent layer/block for this architecture.

Parameters:

  • layer_index (int)

  • return_sequences (bool)

Return type:

Layer

class eegproc.deep_learning.supervised.rnn_architectures.BiLSTMClassifier(timesteps, n_features, n_classes, lstm_units=128, n_bilstm_layers=2, dropout=0.1, loss='softmax_crossentropy', optimizer='adam', metrics=None, name='bilstm_classifier', alpha=1.0, beta=1.0, gamma=0.0, lambda_=0.0)[source]

Bases: RNNClassifier

Bidirectional LSTM classifier for EEG sequence data.

Parameters:

  • timesteps (int | None)

  • n_features (int)

  • n_classes (int)

  • lstm_units (int | Sequence[int], default: 128)

  • n_bilstm_layers (int, default: 2)

  • dropout (float, default: 0.1)

  • loss (str | Callable | Loss, default: 'softmax_crossentropy')

  • optimizer (str | Optimizer, default: 'adam')

  • metrics (list[str] | None, default: None)

  • name (str, default: 'bilstm_classifier')

  • alpha (float, default: 1.0)

  • beta (float, default: 1.0)

  • gamma (float, default: 0.0)

  • lambda_ (float, default: 0.0)

recurrent_layer(layer_index, *, return_sequences)[source]

Create one recurrent layer/block for this architecture.

Parameters:

  • layer_index (int)

  • return_sequences (bool)

Return type:

Layer

class eegproc.deep_learning.supervised.rnn_architectures.GRUClassifier(timesteps, n_features, n_classes, gru_units=128, n_gru_layers=2, dropout=0.1, loss='softmax_crossentropy', optimizer='adam', metrics=None, name='gru_classifier', alpha=1.0, beta=1.0, gamma=0.0, lambda_=0.0)[source]

Bases: RNNClassifier

Unidirectional GRU classifier for EEG sequence data.

Parameters:

  • timesteps (int | None)

  • n_features (int)

  • n_classes (int)

  • gru_units (int | Sequence[int], default: 128)

  • n_gru_layers (int, default: 2)

  • dropout (float, default: 0.1)

  • loss (str | Callable | Loss, default: 'softmax_crossentropy')

  • optimizer (str | Optimizer, default: 'adam')

  • metrics (list[str] | None, default: None)

  • name (str, default: 'gru_classifier')

  • alpha (float, default: 1.0)

  • beta (float, default: 1.0)

  • gamma (float, default: 0.0)

  • lambda_ (float, default: 0.0)

recurrent_layer(layer_index, *, return_sequences)[source]

Create one recurrent layer/block for this architecture.

Parameters:

  • layer_index (int)

  • return_sequences (bool)

Return type:

Layer

class eegproc.deep_learning.supervised.rnn_architectures.LSTMClassifier(timesteps, n_features, n_classes, lstm_units=128, n_lstm_layers=2, dropout=0.1, loss='softmax_crossentropy', optimizer='adam', metrics=None, name='lstm_classifier', alpha=1.0, beta=1.0, gamma=0.0, lambda_=0.0)[source]

Bases: RNNClassifier

Unidirectional LSTM classifier for EEG sequence data.

Parameters:

  • timesteps (int | None)

  • n_features (int)

  • n_classes (int)

  • lstm_units (int | Sequence[int], default: 128)

  • n_lstm_layers (int, default: 2)

  • dropout (float, default: 0.1)

  • loss (str | Callable | Loss, default: 'softmax_crossentropy')

  • optimizer (str | Optimizer, default: 'adam')

  • metrics (list[str] | None, default: None)

  • name (str, default: 'lstm_classifier')

  • alpha (float, default: 1.0)

  • beta (float, default: 1.0)

  • gamma (float, default: 0.0)

  • lambda_ (float, default: 0.0)

recurrent_layer(layer_index, *, return_sequences)[source]

Create one recurrent layer/block for this architecture.

Parameters:

  • layer_index (int)

  • return_sequences (bool)

Return type:

Layer

class eegproc.deep_learning.supervised.rnn_architectures.RNNClassifier(timesteps, n_features, n_classes, rnn_units=128, n_rnn_layers=2, dropout=0.1, loss='softmax_crossentropy', optimizer='adam', metrics=None, name='rnn_classifier', alpha=1.0, beta=1.0, gamma=0.0, lambda_=0.0)[source]

Bases: ABC

Base builder for RNN-based EEG sequence classifiers.

Parameters:

  • timesteps (int | None) – Number of temporal samples in each input sequence. None allows a variable-length sequence.

  • n_features (int) – Number of features at each timestep.

  • n_classes (int) – Number of target classes used by the standalone classifier.

  • rnn_units (int | Sequence[int], default: 128) – A scalar repeats one hidden width across n_rnn_layers. A sequence gives the width of each recurrent layer, for example (128, 64).

  • n_rnn_layers (int, default: 2) – Number of recurrent layers in the stack.

  • dropout (float, default: 0.1) – Dropout applied after each recurrent layer.

  • loss (str | Callable | Loss, default: 'softmax_crossentropy') – Standalone-model loss. Use "variational" to attach a VariationalClassifier head.

  • optimizer (str | Optimizer, default: 'adam') – Optimizer for the standalone compiled model.

  • metrics (list[str] | None, default: None) – Metrics for the standalone compiled model.

  • name (str, default: 'rnn_classifier') – Base name used for the model and its layers.

  • alpha (float, default: 1.0) – Coefficients forwarded to VariationalClassifier.keras_loss when loss="variational".

  • beta (float, default: 1.0) – Coefficients forwarded to VariationalClassifier.keras_loss when loss="variational".

  • gamma (float, default: 0.0) – Coefficients forwarded to VariationalClassifier.keras_loss when loss="variational".

  • lambda_ (float, default: 0.0) – Coefficients forwarded to VariationalClassifier.keras_loss when loss="variational".

build()[source]

Build and compile a complete standalone RNN classifier.

Return type:

Model

build_feature_extractor()[source]

Build the RNN stack without a final classification head.

Return type:

Model

Returns:

tf.keras.Model – Model mapping (batch, timesteps, n_features) to a 2D sequence-level embedding (batch, embedding_features).

Notes

Use this form inside a larger model that supplies its own head, such as an autoencoder combined with a variational classifier. It is intentionally not compiled and does not create a dense, softmax, or variational classification layer.

build_sequence_summarizer()[source]

Build a recurrent sequence-to-vector model without temporal pooling.

Every element is processed in order by the recurrent stack. All intermediate recurrent layers retain the sequence; only the final layer returns its state. For bidirectional architectures, Keras concatenates the forward and backward final states.

Return type:

Model

classifier_head(embedding)[source]

Attach the standalone standard or variational classifier head.

Parameters:

embedding (Tensor)

Return type:

tuple[Tensor, VariationalClassifier | None]

abstractmethod recurrent_layer(layer_index, *, return_sequences)[source]

Create one recurrent layer/block for this architecture.

Parameters:

  • layer_index (int)

  • return_sequences (bool)

Return type:

Layer

recurrent_stack(x, *, return_sequences=True)[source]

Apply the recurrent stack with an optional final temporal axis.

Parameters:

  • x (Tensor)

  • return_sequences (bool, default: True)

Return type:

Tensor

static resolve_loss(loss)[source]

Map friendly loss aliases to Keras-compatible losses.

Parameters:

loss (str | Callable | Loss)

Return type:

str | Callable | Loss

temporal_embedding(x)[source]

Collapse an RNN output sequence into one embedding per sample.

This retains the temporal pooling structure used by the original standalone RNN classifiers: two max-pooling stages followed by global average pooling.

Parameters:

x (Tensor)

Return type:

Tensor

uses_variational_head()[source]

Return whether the standalone model should use the VC head.

Return type:

bool