eegproc.deep_learning.supervised.variational_classifier module

Classification heads for EEG embeddings.

VariationalClassifier maintains learned Gaussian class priors and classifies via Bayes’ rule, with an optional auxiliary discriminator for latent-space alignment. DenseClassifier is a standard trainable linear logit head. HybridClassifier predicts with dense logits while retaining the variational latent, discriminator, and class-prior regularizers. All three heads expose the same loss-component interface, so a model with a custom train/test step can switch heads without changing that step.

class eegproc.deep_learning.supervised.variational_classifier.DenseClassifier(n_classes=2, use_bias=True, kernel_initializer='glorot_uniform', bias_initializer='zeros', label_smoothing=0.0, focal_gamma=1.0, focal_alpha=None, **kwargs)

Bases: Layer

Standard dense logit head with the VC-compatible loss interface.

It exposes n_classes, vc_loss_components(), and discriminator_loss() like the variational heads, while optimizing focal classification loss. All variational regularization components are returned as exact zeros, regardless of the supplied beta/gamma/lambda values, so selecting this head is an unambiguous dense-classifier ablation.

Parameters:

• n_classes (int, default: 2)

• use_bias (bool, default: True)

• kernel_initializer (str | dict, default: 'glorot_uniform')

• bias_initializer (str | dict, default: 'zeros')

• label_smoothing (float, default: 0.0)

• focal_gamma (float, default: 1.0)

• focal_alpha (float | Sequence[float] | None, default: None)

call(features, training=False)

Parameters:

• features (Tensor)

• training (bool, default: False)

Return type:

Tensor

discriminator_loss(mh, y)

Parameters:

• mh (Tensor)

• y (Tensor)

Return type:

Tensor

get_config()

Returns the config of the object.

An object config is a Python dictionary (serializable) containing the information needed to re-instantiate it.

Return type:

dict

supports_discriminator = False

supports_variational_regularization = False

vc_loss(mh, y, alpha=1.0, beta=0.0, gamma=0.0, lambda_=0.0, logits=None, sample_weight=None)

Parameters:

• mh (Tensor)

• y (Tensor)

• alpha (float, default: 1.0)

• beta (float, default: 0.0)

• gamma (float, default: 0.0)

• lambda_ (float, default: 0.0)

• logits (Tensor | None, default: None)

• sample_weight (Tensor | None, default: None)

Return type:

Tensor

vc_loss_components(mh, y, alpha=1.0, beta=0.0, gamma=0.0, lambda_=0.0, logits=None, sample_weight=None)

Return focal loss plus zero-valued VC regularization terms.

Parameters:

• mh (Tensor)

• y (Tensor)

• alpha (float, default: 1.0)

• beta (float, default: 0.0)

• gamma (float, default: 0.0)

• lambda_ (float, default: 0.0)

• logits (Tensor | None, default: None)

• sample_weight (Tensor | None, default: None)

Return type:

dict[str, Tensor]

class eegproc.deep_learning.supervised.variational_classifier.HybridClassifier(n_classes=2, latent_dim=None, use_bias=True, kernel_initializer='glorot_uniform', bias_initializer='zeros', **kwargs)

Bases: VariationalClassifier

Dense prediction head with variational representation regularization.

Predictions are produced by a conventional trainable dense layer:

logits = W h + b

The inherited vc_loss_components method then combines weighted dense focal loss with the same class-conditional latent KL, discriminator, and class-prior terms used by VariationalClassifier:

L = alpha * Focal_dense
    + beta * KL_latent
    + gamma * L_discriminator
    + lambda * KL_class_prior

Thus, unlike VariationalClassifier, Gaussian likelihoods do not define the decision boundary. The Gaussian class parameters instead regularize the input embedding. A class-prior weight of zero (lambda_=0) is a reasonable starting point, because the learned class prior is auxiliary to the dense logits.

Parameters:

• n_classes (int, default: 2)

• latent_dim (int | None, default: None)

• use_bias (bool, default: True)

• kernel_initializer (str | dict, default: 'glorot_uniform')

• bias_initializer (str | dict, default: 'zeros')

build(input_shape)

Return type:

None

call(mh, training=False)

Parameters:

• mh (Tensor)

• training (bool, default: False)

Return type:

Tensor

get_config()

Returns the config of the object.

An object config is a Python dictionary (serializable) containing the information needed to re-instantiate it.

Return type:

dict

supports_discriminator = True

supports_variational_regularization = True

class eegproc.deep_learning.supervised.variational_classifier.VariationalClassifier(n_classes=2, latent_dim=None, label_smoothing=0.0, focal_gamma=1.0, focal_alpha=None, logit_scale=1.0, **kwargs)

Bases: Layer

Variational classification head with separately reportable loss terms.

Parameters:

• n_classes (int, default: 2)

• latent_dim (int | None, default: None)

• label_smoothing (float, default: 0.0)

• focal_gamma (float, default: 1.0)

• focal_alpha (float | Sequence[float] | None, default: None)

• logit_scale (float, default: 1.0)

build(input_shape)

Return type:

None

call(mh, training=False)

Parameters:

• mh (Tensor)

• training (bool, default: False)

Return type:

Tensor

discriminator(z, y)

Return the trainable discriminator score T_psi^y(z).

Parameters:

• z (Tensor)

• y (int)

Return type:

Tensor

discriminator_loss(mh, y)

Train T_psi to distinguish q_phi(z|y) from prior samples.

Parameters:

• mh (Tensor)

• y (Tensor)

Return type:

Tensor

get_config()

Returns the config of the object.

An object config is a Python dictionary (serializable) containing the information needed to re-instantiate it.

Return type:

dict

keras_loss(alpha=1.0, beta=1.0, gamma=0.0, lambda_=0.0)

Return a Keras-compatible wrapper around vc_loss().

The model output y_pred is not used as logits: models usually expose class probabilities (RNNClassifier applies a softmax after this head), and treating those as logits would apply the softmax twice. The logits are recomputed from the latent features stored by the latest call, which is exact because the head is deterministic.

Parameters:

• alpha (float, default: 1.0)

• beta (float, default: 1.0)

• gamma (float, default: 0.0)

• lambda_ (float, default: 0.0)

supports_discriminator = True

supports_variational_regularization = True

vc_loss(mh, y, alpha=1.0, beta=1.0, gamma=0.0, lambda_=0.0, logits=None, sample_weight=None)

Return the complete VC objective (total_loss of the components).

Parameters:

• mh (Tensor)

• y (Tensor)

• alpha (float, default: 1.0)

• beta (float, default: 1.0)

• gamma (float, default: 0.0)

• lambda_ (float, default: 0.0)

• logits (Tensor | None, default: None)

• sample_weight (Tensor | None, default: None)

Return type:

Tensor

vc_loss_components(mh, y, alpha=1.0, beta=1.0, gamma=0.0, lambda_=0.0, logits=None, sample_weight=None, include_classification=True)

Return every raw and weighted component of the VC objective.

The returned total_loss is exactly the sum of the four weighted terms. Passing the logits already produced by the model avoids a duplicate classifier call and guarantees that the logged focal loss corresponds to the logits used for the accuracy metric.

Set include_classification=False when a parent model supplies its own deterministic classifier objective. In that mode this method does not calculate or add a categorical classification loss; it returns only the variational regularizers.

Parameters:

• mh (Tensor)

• y (Tensor)

• alpha (float, default: 1.0)

• beta (float, default: 1.0)

• gamma (float, default: 0.0)

• lambda_ (float, default: 0.0)

• logits (Tensor | None, default: None)

• sample_weight (Tensor | None, default: None)

• include_classification (bool, default: True)

Return type:

dict[str, Tensor]