alibi.explainers.cfrl_tabular module

class alibi.explainers.cfrl_tabular.ConcatTabularPostprocessing[source]

Bases: Postprocessing

Tabular feature columns concatenation post-processing.

__call__(X_cf, X, C)[source]

Performs a concatenation of the counterfactual feature columns along the axis 1.

Parameters:
  • X_cf (List[ndarray]) – List of counterfactual feature columns.

  • X (ndarray) – Input instance. Not used. Included for consistency.

  • C (Optional[ndarray]) – Conditional vector. Not used. Included for consistency.

Return type:

ndarray

Returns:

Concatenation of the counterfactual feature columns.

class alibi.explainers.cfrl_tabular.CounterfactualRLTabular(predictor, encoder, decoder, encoder_preprocessor, decoder_inv_preprocessor, coeff_sparsity, coeff_consistency, feature_names, category_map, immutable_features=None, ranges=None, weight_num=1.0, weight_cat=1.0, latent_dim=None, backend='tensorflow', seed=0, **kwargs)[source]

Bases: CounterfactualRL

Counterfactual Reinforcement Learning Tabular.

__init__(predictor, encoder, decoder, encoder_preprocessor, decoder_inv_preprocessor, coeff_sparsity, coeff_consistency, feature_names, category_map, immutable_features=None, ranges=None, weight_num=1.0, weight_cat=1.0, latent_dim=None, backend='tensorflow', seed=0, **kwargs)[source]

Constructor.

Parameters:
  • predictor (Callable[[ndarray], ndarray]) – A callable that takes a numpy array of N data points as inputs and returns N outputs. For classification task, the second dimension of the output should match the number of classes. Thus, the output can be either a soft label distribution or a hard label distribution (i.e. one-hot encoding) without affecting the performance since argmax is applied to the predictor’s output.

  • encoder (Union[Model, Module]) – Pretrained heterogeneous encoder network.

  • decoder (Union[Model, Module]) – Pretrained heterogeneous decoder network. The output of the decoder must be a list of tensors.

  • encoder_preprocessor (Callable) – Auto-encoder data pre-processor. Depending on the input format, the pre-processor can normalize numerical attributes, transform label encoding to one-hot encoding etc.

  • decoder_inv_preprocessor (Callable) – Auto-encoder data inverse pre-processor. This is the inverse function of the pre-processor. It can denormalize numerical attributes, transform one-hot encoding to label encoding, feature type casting etc.

  • coeff_sparsity (float) – Sparsity loss coefficient.

  • coeff_consistency (float) – Consistency loss coefficient.

  • feature_names (List[str]) – List of feature names. This should be provided by the dataset.

  • category_map (Dict[int, List[str]]) – Dictionary of category mapping. The keys are column indexes and the values are lists containing the possible values for a feature. This should be provided by the dataset.

  • immutable_features (Optional[List[str]]) – List of immutable features.

  • ranges (Optional[Dict[str, Tuple[int, int]]]) – Numerical feature ranges. Note that exist numerical features such as 'Age', which are allowed to increase only. We denote those by 'inc_feat'. Similarly, there exist features allowed to decrease only. We denote them by 'dec_feat'. Finally, there are some free feature, which we denote by 'free_feat'. With the previous notation, we can define range = {'inc_feat': [0, 1], 'dec_feat': [-1, 0], 'free_feat': [-1, 1]}. 'free_feat' can be omitted, as any unspecified feature is considered free. Having the ranges of a feature {‘feat’: [a_low, a_high}, when sampling is performed the numerical value will be clipped between [a_low * (max_val - min_val), a_high * [max_val - min_val]], where a_low and a_high are the minimum and maximum values the feature 'feat'. This implies that a_low and a_high are not restricted to {-1, 0} and {0, 1}, but can be any float number in-between [-1, 0] and [0, 1].

  • weight_num (float) – Numerical loss weight.

  • weight_cat (float) – Categorical loss weight.

  • latent_dim (Optional[int]) – Auto-encoder latent dimension. Can be omitted if the actor network is user specified.

  • backend (str) – Deep learning backend: 'tensorflow' | 'pytorch'. Default 'tensorflow'.

  • seed (int) – Seed for reproducibility. The results are not reproducible for 'tensorflow' backend.

  • **kwargs – Used to replace any default parameter from alibi.explainers.cfrl_base.DEFAULT_BASE_PARAMS.

explain(X, Y_t, C=None, batch_size=100, diversity=False, num_samples=1, patience=1000, tolerance=0.001)[source]

Computes counterfactuals for the given instances conditioned on the target and the conditional vector.

Parameters:
  • X (ndarray) – Input instances to generate counterfactuals for.

  • Y_t (ndarray) – Target labels.

  • C (Optional[List[Dict[str, List[Union[float, str]]]]]) – List of conditional dictionaries. If None, it means that no conditioning was used during training (i.e. the conditional_func returns None). If conditioning was used during training but no conditioning is desired for the current input, an empty list is expected.

  • diversity (bool) – Whether to generate diverse counterfactual set for the given instance. Only supported for a single input instance.

  • num_samples (int) – Number of diversity samples to be generated. Considered only if diversity=True.

  • batch_size (int) – Batch size to use when generating counterfactuals.

  • patience (int) – Maximum number of iterations to perform diversity search stops. If -1, the search stops only if the desired number of samples has been found.

  • tolerance (float) – Tolerance to distinguish two counterfactual instances.

Return type:

Explanation

Returns:

explanationExplanation object containing the counterfactual with additional metadata as attributes. See usage CFRL examples for details.

fit(X)[source]

Fit the model agnostic counterfactual generator.

Parameters:

X (ndarray) – Training data array.

Return type:

Explainer

Returns:

self – The explainer itself.

class alibi.explainers.cfrl_tabular.SampleTabularPostprocessing(category_map, stats)[source]

Bases: Postprocessing

Tabular sampling post-processing. Given the output of the heterogeneous auto-encoder the post-processing functions samples the output according to the conditional vector. Note that the original input instance is required to perform the conditional sampling.

__call__(X_cf, X, C)[source]

Performs counterfactual conditional sampling according to the conditional vector and the original input.

Parameters:
  • X_cf (List[ndarray]) – Decoder reconstruction of the counterfactual instance. The decoded instance is a list where each element in the list correspond to the reconstruction of a feature.

  • X (ndarray) – Input instance.

  • C (Optional[ndarray]) – Conditional vector.

Return type:

List[ndarray]

Returns:

Conditional sampled counterfactual instance.

__init__(category_map, stats)[source]

Constructor.

Parameters:
  • category_map (Dict[int, List[str]]) – Dictionary of category mapping. The keys are column indexes and the values are lists containing the possible feature values.

  • stats (Dict[int, Dict[str, float]]) – Dictionary of statistic of the training data. Contains the minimum and maximum value of each numerical feature in the training set. Each key is an index of the column and each value is another dictionary containing 'min' and 'max' keys.