vcnet.models
Module for the VCNet models
- class vcnet.models.VCNetBase(*args: Any, **kwargs: Any)[source]
Bases:
LightningModule,ABCClass for the general VCNet architecture, which handles immutable features. This class is abstract. It specifies a VCNet model made of a classifier and a conditional variational auto-encoder (cVAE), together with a training procedure. Training a VCNet architecture consists in training the cVAE in the classical way. The VCNet trick lies in generating counterfactuals by switching the predicted class of an example, and then generating a modified example with the cVAE.
The VCNet architecture natively handles immutable features.
Note
This VCNet architecture handles only numerical features. The user of this class has to encode the categorical features outside of this class.
VCNet also has a strategy to choose the class of the counterfactuals in the case of a classification problem with more than two classes. The way the probability vector is changed depends on two hyperparameters:
class_change (reverse by default, or second_max): defines the strategy used to find the most appropriate alternative class.
class_change_norm (“softmax” by default, “sum-norm” or “absolute”): defines how the changed probability vector is normalized.
Example
Let us assume that the vector of class probabilities is \([0.3, 0.6, 0.1]\). With the reverse strategy, the resulting vector will be \([0.7, 0.4, 0.9]\): it favors the class with the lowest predicted probability as the class of the counterfactuals. With the second_max strategy, it yields the vector \([0.3, 0.0, 0.1]\), and then the second most probable class is used to generate counterfactuals.
In practice, these vectors are not used as is, but are first normalized. There are three different ways to normalize them: “sum-norm” divides the vector by the sum of its elements (with the first strategy, we obtain the final vector \([0.35, 0.2, 0.45]\)); “softmax” applies the
softmax()function to make a similar normalization; while “absolute” yields the vector \([0.0, 0.0, 1.0]\), which forces the counterfactual to be purely an example of the third class.- encode(z: torch.tensor, x_mut: torch.tensor, x_immut: torch.tensor) torch.tensor[source]
C-VAE encoding.
- Parameters:
z (torch.tensor) –
pre-encoded input representation.
None or tensor of the size defined by latent_size_share
x_mut (torch.tensor) – mutable part of the input tensor
x_immut (torch.tensor) – immutable part of the input tensor
- Returns:
Representation of the Gaussian distribution in the latent space (mu, sigma). Tensors of dimension latent_size.
- Return type:
tuple (torch.tensor, torch.tensor)
- reparameterize(mu: torch.tensor, sigma: torch.tensor) torch.tensor[source]
C-VAE reparameterization trick.
- Parameters:
mu (torch.tensor) – size latent_size
sigma (torch.tensor) – size latent_size
- Returns:
size latent_size
- Return type:
torch.tensor
- decode(z_prime: torch.tensor, c: torch.tensor) torch.tensor[source]
C-VAE decoding, computes \(P(x|z, c)\).
- Parameters:
z_prime (torch.tensor) – vector to decode
c (torch.tensor) –
conditioning of the VAE.
For VCNet, the decoding is conditioned by the class and the immutable features [class, x_immutable]. Hence, its dimension is class_size + len(x_immutable)
- Returns:
instances decoded by the cVAE
- Return type:
torch.tensor
- pre_encode(x_mut: torch.tensor, x_immut: torch.tensor) torch.tensor[source]
Prepares the examples (x) with shared pre-encoding layers.
The default behavior is to pass x as is.
- abstractmethod classif(z: torch.tensor, x: torch.tensor, x_mut: torch.tensor, x_immut: torch.tensor) torch.tensor[source]
Forward function of the classification layers. It predicts the class of an example z prepared by the pre_encode function.
- Parameters:
z (torch.tensor) – examples represented in their latent space for classification.
- Returns:
example classification. Dimension of the output: self.class_size.
- Return type:
torch.tensor
- forward(x: torch.tensor)[source]
Forward function used during the training phase of a VCNet model. It goes through the three parts of the model: the pre-encoding, the C-VAE and the classification. It returns the reconstructed example, the VAE distribution parameters and the output class.
- Parameters:
x (torch.tensor) – input examples
- forward_pred(x: torch.tensor) torch.tensor[source]
Forward function for prediction in the test phase (prediction task). It prepares the examples and then classifies them.
- Parameters:
x (torch.tensor) – a tensor containing examples
- counterfactuals(x: torch.tensor, t: torch.tensor = None) torch.tensor[source]
Generates counterfactuals for the examples x.
- Parameters:
x (torch.tensor) – a batch of factual examples for which counterfactuals are generated
t (torch.tensor) – the targeted classes (probability vectors). If None, the class of the counterfactuals is chosen by the class change strategy.
- Returns:
the counterfactuals and their predicted class probabilities.
- Return type:
tuple (torch.tensor, torch.tensor)
- loss_functions(recon_x, x, mu, sigma, output_class=None, y_true=None)[source]
Evaluates the reconstruction losses.
- class vcnet.models.VCNet(*args: Any, **kwargs: Any)[source]
Bases:
VCNetBaseVCNet model architecture (version with immutable features). VCNet is a joint-learning architecture: during the training phase, both the classifier and the counterfactual generator are fitted.
- pre_encode(x_mut: torch.tensor, x_immut: torch.tensor) torch.tensor[source]
Prepares the examples (x) with shared pre-encoding layers.
The default behavior is to pass x as is.
- classif(z: torch.tensor, x: torch.tensor, x_mut: torch.tensor, x_immut: torch.tensor) torch.tensor[source]
Forward function of the classification layers. It predicts the class of an example z prepared by the pre_encode function.
- Parameters:
z (torch.tensor) – examples represented in their latent space for classification.
- Returns:
example classification. Dimension of the output: self.class_size.
- Return type:
torch.tensor
- class vcnet.models.PHVCNet(*args: Any, **kwargs: Any)[source]
Bases:
VCNetBasePost-hoc VCNet model architecture (version with immutable features). Post-hoc VCNet uses a classifier already trained on a classification task, and trains only the counterfactual generator.
The classifier provided to this class is assumed to take as input the examples to classify and to return class probabilities.
- classif(z: torch.tensor, x: torch.tensor, x_mut: torch.tensor, x_immut: torch.tensor) torch.tensor[source]
Forward function of the classification layers. It predicts the class of an example z prepared by the pre_encode function.
- Parameters:
z (torch.tensor) – examples represented in their latent space for classification.
- Returns:
example classification. Dimension of the output: self.class_size.
- Return type:
torch.tensor