dice_ml.explainer_interfaces package

Submodules

dice_ml.explainer_interfaces.dice_KD module

Module to generate counterfactual explanations from a KD-Tree This code is similar to ‘Interpretable Counterfactual Explanations Guided by Prototypes’: https://arxiv.org/pdf/1907.02584.pdf

class dice_ml.explainer_interfaces.dice_KD.DiceKD(data_interface, model_interface)[source]

Bases: ExplainerBase

do_sparsity_check(cfs, query_instance, sparsity_weight)[source]
duplicates(cfs, final_indices, i)[source]
find_counterfactuals(data_df_copy, query_instance, query_instance_orig, desired_range, desired_class, total_CFs, features_to_vary, permitted_range, sparsity_weight, stopping_threshold, posthoc_sparsity_param, posthoc_sparsity_algorithm, verbose, limit_steps_ls)[source]

Finds counterfactuals by querying a K-D tree for the nearest data points in the desired class from the dataset.

predict_fn(input_instance)[source]

returns predictions

predict_fn_scores(input_instance)[source]

Returns prediction scores.

vary_valid(KD_query_instance, total_CFs, features_to_vary, permitted_range, query_instance, sparsity_weight)[source]

This function ensures that we only vary features_to_vary when generating counterfactuals

dice_ml.explainer_interfaces.dice_genetic module

Module to generate diverse counterfactual explanations based on genetic algorithm This code is similar to ‘GeCo: Quality Counterfactual Explanations in Real Time’: https://arxiv.org/pdf/2101.01292.pdf

class dice_ml.explainer_interfaces.dice_genetic.DiceGenetic(data_interface, model_interface)[source]

Bases: ExplainerBase

compute_loss(cfs, desired_range, desired_class)[source]

Computes the overall loss

compute_proximity_loss(x_hat_unnormalized, query_instance_normalized)[source]

Compute weighted distance between two vectors.

compute_sparsity_loss(cfs)[source]

Compute weighted distance between two vectors.

compute_yloss(cfs, desired_range, desired_class)[source]

Computes the first part (y-loss) of the loss function.

do_KD_init(features_to_vary, query_instance, cfs, desired_class, desired_range)[source]
do_cf_initializations(total_CFs, initialization, algorithm, features_to_vary, desired_range, desired_class, query_instance, query_instance_df_dummies, verbose)[source]

Intializes CFs and other related variables.

do_loss_initializations(yloss_type, diversity_loss_type, feature_weights, encoding='one-hot')[source]

Intializes variables related to main loss function

do_param_initializations(total_CFs, initialization, desired_range, desired_class, query_instance, query_instance_df_dummies, algorithm, features_to_vary, permitted_range, yloss_type, diversity_loss_type, feature_weights, proximity_weight, sparsity_weight, diversity_weight, categorical_penalty, verbose)[source]
do_random_init(num_inits, features_to_vary, query_instance, desired_class, desired_range)[source]
find_counterfactuals(query_instance, desired_range, desired_class, features_to_vary, maxiterations, thresh, verbose)[source]

Finds counterfactuals by generating cfs through the genetic algorithm

get_valid_feature_range(normalized=False)[source]
label_decode(labelled_input)[source]

Transforms label encoded data back to categorical values

label_decode_cfs(cfs_arr)[source]
label_encode(input_instance)[source]
mate(k1, k2, features_to_vary, query_instance)[source]

Performs mating and produces new offsprings

predict_fn(input_instance)[source]

Returns actual prediction.

predict_fn_scores(input_instance)[source]

Returns prediction scores.

update_hyperparameters(proximity_weight, sparsity_weight, diversity_weight, categorical_penalty)[source]

Update hyperparameters of the loss function

dice_ml.explainer_interfaces.dice_pytorch module

Module to generate diverse counterfactual explanations based on PyTorch framework

class dice_ml.explainer_interfaces.dice_pytorch.DicePyTorch(data_interface, model_interface)[source]

Bases: ExplainerBase

compute_dist(x_hat, x1)[source]

Compute weighted distance between two vectors.

compute_diversity_loss()[source]

Computes the third part (diversity) of the loss function.

compute_loss()[source]

Computes the overall loss

compute_proximity_loss()[source]

Compute the second part (distance from x1) of the loss function.

compute_regularization_loss()[source]

Adds a linear equality constraints to the loss functions - to ensure all levels of a categorical variable sums to one

compute_yloss()[source]

Computes the first part (y-loss) of the loss function.

do_cf_initializations(total_CFs, algorithm, features_to_vary)[source]

Intializes CFs and other related variables.

do_loss_initializations(yloss_type, diversity_loss_type, feature_weights)[source]

Intializes variables related to main loss function

do_optimizer_initializations(optimizer, learning_rate)[source]

Initializes gradient-based PyTorch optimizers.

dpp_style(submethod)[source]

Computes the DPP of a matrix.

find_counterfactuals(query_instance, desired_class, optimizer, learning_rate, min_iter, max_iter, project_iter, loss_diff_thres, loss_converge_maxiter, verbose, init_near_query_instance, tie_random, stopping_threshold, posthoc_sparsity_param, posthoc_sparsity_algorithm, limit_steps_ls)[source]

Finds counterfactuals by gradient-descent.

get_model_output(input_instance, transform_data=False, out_tensor=True)[source]

get output probability of ML model

initialize_CFs(query_instance, init_near_query_instance=False)[source]

Initialize counterfactuals.

predict_fn(input_instance)[source]

prediction function

predict_fn_for_sparsity(input_instance)[source]

prediction function for sparsity correction

round_off_cfs(assign=False)[source]

function for intermediate projection of CFs.

stop_loop(itr, loss_diff)[source]

Determines the stopping condition for gradient descent.

update_hyperparameters(proximity_weight, diversity_weight, categorical_penalty)[source]

Update hyperparameters of the loss function

dice_ml.explainer_interfaces.dice_random module

Module to generate diverse counterfactual explanations based on random sampling. A simple implementation.

class dice_ml.explainer_interfaces.dice_random.DiceRandom(data_interface, model_interface)[source]

Bases: ExplainerBase

get_continuous_samples(low, high, precision, size=1000, seed=None)[source]
get_samples(fixed_features_values, feature_range, sampling_random_seed, sampling_size)[source]

dice_ml.explainer_interfaces.dice_tensorflow1 module

Module to generate diverse counterfactual explanations based on tensorflow 1.x

class dice_ml.explainer_interfaces.dice_tensorflow1.DiceTensorFlow1(data_interface, model_interface)[source]

Bases: ExplainerBase

compute_dist(x_hat, x1)[source]

Compute weighted distance between two vectors.

compute_diversity_loss(method)[source]

Computes the third part (diversity) of the loss function.

compute_proximity_loss()[source]

Compute the second part (distance from x1) of the loss function.

compute_regularization_loss()[source]

Adds a linear equality constraints to the loss functions - to ensure all levels of a categorical variable sums to one

compute_yloss(method)[source]

Computes the first part (y-loss) of the loss function.

do_cf_initializations(total_CFs, algorithm, features_to_vary)[source]

Intializes TF variables required for CF generation.

do_loss_initializations(yloss_type='hinge_loss', diversity_loss_type='dpp_style:inverse_dist', feature_weights='inverse_mad')[source]

Defines the optimization loss

do_optimizer_initializations(optimizer)[source]

Initializes gradient-based TF optimizers.

dpp_style(submethod)[source]

Computes the DPP of a matrix.

find_counterfactuals(query_instance, limit_steps_ls, desired_class='opposite', learning_rate=0.05, min_iter=500, max_iter=5000, project_iter=0, loss_diff_thres=1e-05, loss_converge_maxiter=1, verbose=False, init_near_query_instance=False, tie_random=False, stopping_threshold=0.5, posthoc_sparsity_param=0.1, posthoc_sparsity_algorithm='linear')[source]

Finds counterfactuals by gradient-descent.

initialize_CFs(query_instance, init_near_query_instance=False)[source]

Initialize counterfactuals.

predict_fn(input_instance)[source]

prediction function

predict_fn_for_sparsity(input_instance)[source]

prediction function for sparsity correction

round_off_cfs(assign=False)[source]

function for intermediate projection of CFs.

scipy_optimizers(method='Nelder-Mead')[source]
stop_loop(itr, loss_diff)[source]

Determines the stopping condition for gradient descent.

tensorflow_optimizers(method='adam')[source]

Initializes tensorflow optimizers.

update_hyperparameters(proximity_weight=0.5, diversity_weight=0.5, categorical_penalty=0.1)[source]

Updates hyperparameters.

dice_ml.explainer_interfaces.dice_tensorflow2 module

Module to generate diverse counterfactual explanations based on tensorflow 2.x

class dice_ml.explainer_interfaces.dice_tensorflow2.DiceTensorFlow2(data_interface, model_interface)[source]

Bases: ExplainerBase

compute_dist(x_hat, x1)[source]

Compute weighted distance between two vectors.

compute_diversity_loss()[source]

Computes the third part (diversity) of the loss function.

compute_loss()[source]

Computes the overall loss

compute_proximity_loss()[source]

Compute the second part (distance from x1) of the loss function.

compute_regularization_loss()[source]

Adds a linear equality constraints to the loss functions - to ensure all levels of a categorical variable sums to one

compute_yloss()[source]

Computes the first part (y-loss) of the loss function.

do_cf_initializations(total_CFs, algorithm, features_to_vary)[source]

Intializes CFs and other related variables.

do_loss_initializations(yloss_type, diversity_loss_type, feature_weights)[source]

Intializes variables related to main loss function

do_optimizer_initializations(optimizer, learning_rate)[source]

Initializes gradient-based TensorFLow optimizers.

dpp_style(submethod)[source]

Computes the DPP of a matrix.

find_counterfactuals(query_instance, desired_class, optimizer, learning_rate, min_iter, max_iter, project_iter, loss_diff_thres, loss_converge_maxiter, verbose, init_near_query_instance, tie_random, stopping_threshold, posthoc_sparsity_param, posthoc_sparsity_algorithm, limit_steps_ls)[source]

Finds counterfactuals by gradient-descent.

initialize_CFs(query_instance, init_near_query_instance=False)[source]

Initialize counterfactuals.

predict_fn(input_instance)[source]

prediction function

predict_fn_for_sparsity(input_instance)[source]

prediction function for sparsity correction

round_off_cfs(assign=False)[source]

function for intermediate projection of CFs.

stop_loop(itr, loss_diff)[source]

Determines the stopping condition for gradient descent.

update_hyperparameters(proximity_weight, diversity_weight, categorical_penalty)[source]

Update hyperparameters of the loss function

dice_ml.explainer_interfaces.dice_xgboost module

class dice_ml.explainer_interfaces.dice_xgboost.DiceXGBoost(data_interface, model_interface)[source]

Bases: ExplainerBase

generate_counterfactuals(query_instance, total_CFs=5)[source]

Generate counterfactuals

dice_ml.explainer_interfaces.explainer_base module

Module containing a template class to generate counterfactual explanations. Subclasses implement interfaces for different ML frameworks such as TensorFlow or PyTorch. All methods are in dice_ml.explainer_interfaces

class dice_ml.explainer_interfaces.explainer_base.ExplainerBase(data_interface, model_interface=None)[source]

Bases: ABC

build_KD_tree(data_df_copy, desired_range, desired_class, predicted_outcome_name)[source]
check_permitted_range(permitted_range)[source]

checks permitted range for continuous features TODO: add comments as to where this is used if this function is necessary, else remove.

check_query_instance_validity(features_to_vary, permitted_range, query_instance, feature_ranges_orig)[source]
decide_cf_validity(model_outputs)[source]
decode_model_output(encoded_labels)[source]
decode_to_original_labels(test_instance_df, final_cfs_df, final_cfs_df_sparse)[source]
static deserialize_explainer(path)[source]

Reload the explainer into the memory by reading the file specified by path.

Performs a binary search between continuous features of a CF and corresponding values in query_instance until the prediction class changes.

Performs a greedy linear search - moves the continuous features in CFs towards original values in query_instance greedily until the prediction class changes, or it reaches the maximum number of steps

do_posthoc_sparsity_enhancement(final_cfs_sparse, query_instance, posthoc_sparsity_param, posthoc_sparsity_algorithm, limit_steps_ls)[source]

Post-hoc method to encourage sparsity in a generated counterfactuals.

Parameters:
  • final_cfs_sparse – Final CFs in original user-fed format, in a pandas dataframe.

  • query_instance – Query instance in original user-fed format, in a pandas dataframe.

  • posthoc_sparsity_param – Parameter for the post-hoc operation on continuous features to enhance sparsity.

  • posthoc_sparsity_algorithm – Perform either linear or binary search. Prefer binary search when a feature range is large (for instance, income varying from 10k to 1000k) and only if the features share a monotonic relationship with predicted outcome in the model.

  • limit_steps_ls – Defines the limit of steps to be done in the linear search, necessary to avoid infinite loops

feature_importance(query_instances, cf_examples_list=None, total_CFs=10, local_importance=True, global_importance=True, desired_class='opposite', desired_range=None, permitted_range=None, features_to_vary='all', stopping_threshold=0.5, posthoc_sparsity_param=0.1, posthoc_sparsity_algorithm='linear', **kwargs)[source]

Estimate feature importance scores for the given inputs.

Parameters:
  • query_instances – A list of inputs for which to compute the feature importances. These can be provided as a dataframe.

  • cf_examples_list – If precomputed, a list of counterfactual examples for every input point. If cf_examples_list is provided, then all the following parameters are ignored.

  • total_CFs – The number of counterfactuals to generate per input (default is 10)

  • other_parameters – These are the same as the generate_counterfactuals method.

Returns:

An object of class CounterfactualExplanations that includes the list of counterfactuals per input, local feature importances per input, and the global feature importance summarized over all inputs.

generate_counterfactuals(query_instances, total_CFs, desired_class='opposite', desired_range=None, permitted_range=None, features_to_vary='all', stopping_threshold=0.5, posthoc_sparsity_param=0.1, posthoc_sparsity_algorithm='linear', verbose=False, **kwargs)[source]

General method for generating counterfactuals.

Parameters:
  • query_instances – Input point(s) for which counterfactuals are to be generated. This can be a dataframe with one or more rows.

  • total_CFs – Total number of counterfactuals required.

  • desired_class – Desired counterfactual class - can take 0 or 1. Default value is “opposite” to the outcome class of query_instance for binary classification.

  • desired_range – For regression problems. Contains the outcome range to generate counterfactuals in. This should be a list of two numbers in ascending order.

  • permitted_range – Dictionary with feature names as keys and permitted range in list as values. Defaults to the range inferred from training data. If None, uses the parameters initialized in data_interface.

  • features_to_vary – Either a string “all” or a list of feature names to vary.

  • stopping_threshold – Minimum threshold for counterfactuals target class probability.

  • proximity_weight – A positive float. Larger this weight, more close the counterfactuals are to the query_instance. Used by [‘genetic’, ‘gradientdescent’], ignored by [‘random’, ‘kdtree’] methods.

  • sparsity_weight – A positive float. Larger this weight, less features are changed from the query_instance. Used by [‘genetic’, ‘kdtree’], ignored by [‘random’, ‘gradientdescent’] methods.

  • diversity_weight – A positive float. Larger this weight, more diverse the counterfactuals are. Used by [‘genetic’, ‘gradientdescent’], ignored by [‘random’, ‘kdtree’] methods.

  • categorical_penalty – A positive float. A weight to ensure that all levels of a categorical variable sums to 1. Used by [‘genetic’, ‘gradientdescent’], ignored by [‘random’, ‘kdtree’] methods.

  • posthoc_sparsity_param – Parameter for the post-hoc operation on continuous features to enhance sparsity.

  • posthoc_sparsity_algorithm – Perform either linear or binary search. Takes “linear” or “binary”. Prefer binary search when a feature range is large (for instance, income varying from 10k to 1000k) and only if the features share a monotonic relationship with predicted outcome in the model.

  • verbose – Whether to output detailed messages.

  • sample_size – Sampling size

  • random_seed – Random seed for reproducibility

  • kwargs – Other parameters accepted by specific explanation method

Returns:

A CounterfactualExplanations object that contains the list of counterfactual examples per query_instance as one of its attributes.

get_model_output_from_scores(model_scores)[source]
global_feature_importance(query_instances, cf_examples_list=None, total_CFs=10, local_importance=True, desired_class='opposite', desired_range=None, permitted_range=None, features_to_vary='all', stopping_threshold=0.5, posthoc_sparsity_param=0.1, posthoc_sparsity_algorithm='linear', **kwargs)[source]

Estimate global feature importance scores for the given inputs.

Parameters:
  • query_instances – A list of inputs for which to compute the feature importances. These can be provided as a dataframe.

  • cf_examples_list – If precomputed, a list of counterfactual examples for every input point. If cf_examples_list is provided, then all the following parameters are ignored.

  • total_CFs – The number of counterfactuals to generate per input (default is 10)

  • local_importance – Binary flag indicating whether local feature importance values should also be returned for each query instance.

  • other_parameters – These are the same as the generate_counterfactuals method.

Returns:

An object of class CounterfactualExplanations that includes the list of counterfactuals per input, local feature importances per input, and the global feature importance summarized over all inputs.

infer_target_cfs_class(desired_class_input, original_pred, num_output_nodes)[source]

Infer the target class for generating CFs. Only called when model_type==”classifier”. TODO: Add support for opposite desired class in multiclass. Downstream methods should decide whether it is allowed or not.

infer_target_cfs_range(desired_range_input)[source]
is_cf_valid(model_score)[source]

Check if a cf belongs to the target class or target range.

local_feature_importance(query_instances, cf_examples_list=None, total_CFs=10, desired_class='opposite', desired_range=None, permitted_range=None, features_to_vary='all', stopping_threshold=0.5, posthoc_sparsity_param=0.1, posthoc_sparsity_algorithm='linear', **kwargs)[source]

Estimate local feature importance scores for the given inputs.

Parameters:
  • query_instances – A list of inputs for which to compute the feature importances. These can be provided as a dataframe.

  • cf_examples_list – If precomputed, a list of counterfactual examples for every input point. If cf_examples_list is provided, then all the following parameters are ignored.

  • total_CFs – The number of counterfactuals to generate per input (default is 10)

  • other_parameters – These are the same as the generate_counterfactuals method.

Returns:

An object of class CounterfactualExplanations that includes the list of counterfactuals per input, local feature importances per input, and the global feature importance summarized over all inputs.

misc_init(stopping_threshold, desired_class, desired_range, test_pred)[source]
predict_fn(input_instance)[source]

prediction function

predict_fn_for_sparsity(input_instance)[source]

prediction function for sparsity correction

round_to_precision()[source]
serialize_explainer(path)[source]

Serialize the explainer to the file specified by path.

setup(features_to_vary, permitted_range, query_instance, feature_weights)[source]
sigmoid(z)[source]

This is used in VAE-based CF explainers.

dice_ml.explainer_interfaces.feasible_base_vae module

class dice_ml.explainer_interfaces.feasible_base_vae.FeasibleBaseVAE(data_interface, model_interface, **kwargs)[source]

Bases: ExplainerBase

compute_loss(model_out, x, target_label)[source]
generate_counterfactuals(query_instance, total_CFs, desired_class='opposite')[source]

General method for generating counterfactuals.

Parameters:
  • query_instances – Input point(s) for which counterfactuals are to be generated. This can be a dataframe with one or more rows.

  • total_CFs – Total number of counterfactuals required.

  • desired_class – Desired counterfactual class - can take 0 or 1. Default value is “opposite” to the outcome class of query_instance for binary classification.

  • desired_range – For regression problems. Contains the outcome range to generate counterfactuals in. This should be a list of two numbers in ascending order.

  • permitted_range – Dictionary with feature names as keys and permitted range in list as values. Defaults to the range inferred from training data. If None, uses the parameters initialized in data_interface.

  • features_to_vary – Either a string “all” or a list of feature names to vary.

  • stopping_threshold – Minimum threshold for counterfactuals target class probability.

  • proximity_weight – A positive float. Larger this weight, more close the counterfactuals are to the query_instance. Used by [‘genetic’, ‘gradientdescent’], ignored by [‘random’, ‘kdtree’] methods.

  • sparsity_weight – A positive float. Larger this weight, less features are changed from the query_instance. Used by [‘genetic’, ‘kdtree’], ignored by [‘random’, ‘gradientdescent’] methods.

  • diversity_weight – A positive float. Larger this weight, more diverse the counterfactuals are. Used by [‘genetic’, ‘gradientdescent’], ignored by [‘random’, ‘kdtree’] methods.

  • categorical_penalty – A positive float. A weight to ensure that all levels of a categorical variable sums to 1. Used by [‘genetic’, ‘gradientdescent’], ignored by [‘random’, ‘kdtree’] methods.

  • posthoc_sparsity_param – Parameter for the post-hoc operation on continuous features to enhance sparsity.

  • posthoc_sparsity_algorithm – Perform either linear or binary search. Takes “linear” or “binary”. Prefer binary search when a feature range is large (for instance, income varying from 10k to 1000k) and only if the features share a monotonic relationship with predicted outcome in the model.

  • verbose – Whether to output detailed messages.

  • sample_size – Sampling size

  • random_seed – Random seed for reproducibility

  • kwargs – Other parameters accepted by specific explanation method

Returns:

A CounterfactualExplanations object that contains the list of counterfactual examples per query_instance as one of its attributes.

train(pre_trained=False)[source]

pre_trained: Bool Variable to check whether pre trained model exists to avoid training again

dice_ml.explainer_interfaces.feasible_model_approx module

class dice_ml.explainer_interfaces.feasible_model_approx.FeasibleModelApprox(data_interface, model_interface, **kwargs)[source]

Bases: FeasibleBaseVAE, ExplainerBase

train(constraint_type, constraint_variables, constraint_direction, constraint_reg, pre_trained=False)[source]
Parameters:
  • pre_trained – Bool Variable to check whether pre trained model exists to avoid training again

  • constraint_type – Binary Variable currently: (1) unary / (0) monotonic

  • constraint_variables – List of List: [[Effect, Cause1, Cause2, …. ]]

  • constraint_direction – -1: Negative, 1: Positive ( By default has to be one for monotonic constraints )

  • constraint_reg – Tunable Hyperparamter

:return None

Module contents