eegproc.deep_learning.unsupervised.VariationalAutoencoderLoss module

class eegproc.deep_learning.unsupervised.VariationalAutoencoderLoss.GradientReversal(adversarial_weight=1.0, **kwargs)

Bases: Layer

Identity layer in the forward pass that reverses encoder gradients.

The layer returns its input unchanged during the forward pass. During backpropagation, the incoming gradient is multiplied by -adversarial_weight. Place it between the encoder representation and the subject-identification head:

subject_logits = subject_head(GradientReversal(weight)(z_mean))

The subject head can then minimize ordinary subject cross-entropy, while the encoder receives the opposite gradient and learns to make subject identity harder to recover.

Parameters:

adversarial_weight (float, default: 1.0) – Non-negative strength of the reversed gradient reaching the encoder. This is the main hyperparameter controlling subject invariance. A value of 0.0 disables the adversarial encoder gradient; 1.0 reverses it at full strength.

call(inputs)

Parameters:

inputs (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

class eegproc.deep_learning.unsupervised.VariationalAutoencoderLoss.VariationalAutoencoderLoss(reconstruction='mse', beta=1.0, feature_reduction='mean', kl_reduction=None, huber_delta=1.0, log_var_clip_min=-20.0, log_var_clip_max=20.0, subject_loss_weight=0.0, subject_from_logits=True)

Bases: object

Compute a configurable VAE objective with optional subject adversity.

For each sample, the implemented scalar objective is

reconstruction + beta * latent_kl + subject_loss_weight * subject_ce.

The subject term is deliberately positive. To make it adversarial for the encoder, subject_pred must be produced by a subject head whose input passes through GradientReversal. This gives the desired parameter-specific optimization:

• the subject head minimizes subject cross-entropy;

• the encoder maximizes subject cross-entropy, scaled by the gradient- reversal adversarial_weight;

• the decoder is unaffected by the subject term.

Both VAE terms can be reduced with either "sum" or "mean" across their non-batch coordinates:

• sum/sum is the usual summed ELBO convention;

• mean/mean is a dimension-normalized objective that is often easier to combine with O(1) classifier losses.

Parameters:

• reconstruction (Literal['mse', 'mae', 'huber'], default: 'mse') – Element-wise reconstruction penalty: "mse", "mae", or "huber".

• beta (float, default: 1.0) – Non-negative multiplier on the reduced KL term.

• feature_reduction (Literal['sum', 'mean'], default: 'mean') – Reduction across every non-batch reconstruction dimension.

• kl_reduction (Optional[Literal['sum', 'mean']], default: None) – Reduction across latent coordinates. When omitted, defaults to feature_reduction.

• huber_delta (float, default: 1.0) – Positive transition point for Huber loss.

• log_var_clip_min (float, default: -20.0) – Bounds applied to log variance before exponentiation.

• log_var_clip_max (float, default: 20.0) – Bounds applied to log variance before exponentiation.

• subject_loss_weight (float, default: 0.0) – Non-negative multiplier on subject cross-entropy in the scalar loss. Keep this at 1.0 in the usual gradient-reversal setup so the subject head remains strong. Control the encoder-side adversarial pressure primarily through GradientReversal(adversarial_weight=...). Set this to 0.0 to exclude the subject term from the objective.

• subject_from_logits (bool, default: True) – Whether subject_pred contains unnormalized logits. Using logits is recommended for numerical stability.

static compute_huber_loss(error, delta=1.0)

Return element-wise Huber loss.

Parameters:

• error (Tensor)

• delta (float, default: 1.0)

Return type:

Tensor

compute_kl_loss(z_mean, z_log_var)

Compute one reduced KL value for every sample.

z_log_var must contain log(sigma**2), not log(sigma).

Parameters:

• z_mean (Tensor)

• z_log_var (Tensor)

Return type:

Tensor

compute_reconstruction_loss(x_true, x_pred)

Compute one reduced reconstruction loss for every sample.

Parameters:

• x_true (Tensor)

• x_pred (Tensor)

Return type:

Tensor

compute_subject_loss(subject_true, subject_pred)

Compute sparse subject cross-entropy for every batch sample.

Subject targets are ordinary integer subject IDs. They are not inverted, randomized, or replaced with uniform targets. The gradient reversal applied before the subject head creates the adversarial encoder update.

Parameters:

• subject_true (Tensor)

• subject_pred (Tensor)

Return type:

Tensor

get_config()

Return a Keras-serializable configuration.

Return type:

dict