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)

Bases: ExplainerBase

do_sparsity_check(cfs, query_instance, sparsity_weight)

duplicates(cfs, final_indices, i)

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)

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

predict_fn(input_instance)

returns predictions

predict_fn_scores(input_instance)

Returns prediction scores.

vary_valid(KD_query_instance, total_CFs, features_to_vary, permitted_range, query_instance, sparsity_weight)

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)

Bases: ExplainerBase

compute_loss(cfs, desired_range, desired_class)

Computes the overall loss

compute_proximity_loss(x_hat_unnormalized, query_instance_normalized)

Compute weighted distance between two vectors.

compute_sparsity_loss(cfs)

Compute weighted distance between two vectors.

compute_yloss(cfs, desired_range, desired_class)

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

do_KD_init(features_to_vary, query_instance, cfs, desired_class, desired_range)

do_cf_initializations(total_CFs, initialization, algorithm, features_to_vary, desired_range, desired_class, query_instance, query_instance_df_dummies, verbose)

Intializes CFs and other related variables.

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

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)

do_random_init(num_inits, features_to_vary, query_instance, desired_class, desired_range)

find_counterfactuals(query_instance, desired_range, desired_class, features_to_vary, maxiterations, thresh, verbose)

Finds counterfactuals by generating cfs through the genetic algorithm

get_valid_feature_range(normalized=False)

label_decode(labelled_input)

Transforms label encoded data back to categorical values

label_decode_cfs(cfs_arr)

label_encode(input_instance)

mate(k1, k2, features_to_vary, query_instance)

Performs mating and produces new offsprings

predict_fn(input_instance)

Returns actual prediction.

predict_fn_scores(input_instance)

Returns prediction scores.

update_hyperparameters(proximity_weight, sparsity_weight, diversity_weight, categorical_penalty)

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)

Bases: ExplainerBase

compute_dist(x_hat, x1)

Compute weighted distance between two vectors.

compute_diversity_loss()

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

compute_loss()

Computes the overall loss

compute_proximity_loss()

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

compute_regularization_loss()

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

compute_yloss()

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

do_cf_initializations(total_CFs, algorithm, features_to_vary)

Intializes CFs and other related variables.

do_loss_initializations(yloss_type, diversity_loss_type, feature_weights)

Intializes variables related to main loss function

do_optimizer_initializations(optimizer, learning_rate)

Initializes gradient-based PyTorch optimizers.

dpp_style(submethod)

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)

Finds counterfactuals by gradient-descent.

get_model_output(input_instance, transform_data=False, out_tensor=True)

get output probability of ML model

initialize_CFs(query_instance, init_near_query_instance=False)

Initialize counterfactuals.

predict_fn(input_instance)

prediction function

predict_fn_for_sparsity(input_instance)

prediction function for sparsity correction

round_off_cfs(assign=False)

function for intermediate projection of CFs.

stop_loop(itr, loss_diff)

Determines the stopping condition for gradient descent.

update_hyperparameters(proximity_weight, diversity_weight, categorical_penalty)

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)

Bases: ExplainerBase

get_continuous_samples(low, high, precision, size=1000, seed=None)

get_samples(fixed_features_values, feature_range, sampling_random_seed, sampling_size)

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)

Bases: ExplainerBase

compute_dist(x_hat, x1)

Compute weighted distance between two vectors.

compute_diversity_loss(method)

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

compute_proximity_loss()

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

compute_regularization_loss()

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

compute_yloss(method)

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

do_cf_initializations(total_CFs, algorithm, features_to_vary)

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')

Defines the optimization loss

do_optimizer_initializations(optimizer)

Initializes gradient-based TF optimizers.

dpp_style(submethod)

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')

Finds counterfactuals by gradient-descent.

initialize_CFs(query_instance, init_near_query_instance=False)

Initialize counterfactuals.

predict_fn(input_instance)

prediction function

predict_fn_for_sparsity(input_instance)

prediction function for sparsity correction

round_off_cfs(assign=False)

function for intermediate projection of CFs.

scipy_optimizers(method='Nelder-Mead')

stop_loop(itr, loss_diff)

Determines the stopping condition for gradient descent.

tensorflow_optimizers(method='adam')

Initializes tensorflow optimizers.

update_hyperparameters(proximity_weight=0.5, diversity_weight=0.5, categorical_penalty=0.1)

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)

Bases: ExplainerBase

compute_dist(x_hat, x1)

Compute weighted distance between two vectors.

compute_diversity_loss()

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

compute_loss()

Computes the overall loss

compute_proximity_loss()

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

compute_regularization_loss()

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

compute_yloss()

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

do_cf_initializations(total_CFs, algorithm, features_to_vary)

Intializes CFs and other related variables.

do_loss_initializations(yloss_type, diversity_loss_type, feature_weights)

Intializes variables related to main loss function

do_optimizer_initializations(optimizer, learning_rate)

Initializes gradient-based TensorFLow optimizers.

dpp_style(submethod)

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)

Finds counterfactuals by gradient-descent.

initialize_CFs(query_instance, init_near_query_instance=False)

Initialize counterfactuals.

predict_fn(input_instance)

prediction function

predict_fn_for_sparsity(input_instance)

prediction function for sparsity correction

round_off_cfs(assign=False)

function for intermediate projection of CFs.

stop_loop(itr, loss_diff)

Determines the stopping condition for gradient descent.

update_hyperparameters(proximity_weight, diversity_weight, categorical_penalty)

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)

Bases: ExplainerBase

generate_counterfactuals(query_instance, total_CFs=5)

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)

Bases: ABC

build_KD_tree(data_df_copy, desired_range, desired_class, predicted_outcome_name)

check_permitted_range(permitted_range)

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)

decide_cf_validity(model_outputs)

decode_model_output(encoded_labels)

decode_to_original_labels(test_instance_df, final_cfs_df, final_cfs_df_sparse)

static deserialize_explainer(path)

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

do_binary_search(diff, decimal_prec, query_instance, cf_ix, feature, final_cfs_sparse, current_pred)

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

do_linear_search(diff, decimal_prec, query_instance, cf_ix, feature, final_cfs_sparse, current_pred_orig, limit_steps_ls)

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)

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)

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)

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)

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)

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)

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)

is_cf_valid(model_score)

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)

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)

predict_fn(input_instance)

prediction function

predict_fn_for_sparsity(input_instance)

prediction function for sparsity correction

round_to_precision()

serialize_explainer(path)

Serialize the explainer to the file specified by path.

setup(features_to_vary, permitted_range, query_instance, feature_weights)

sigmoid(z)

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)

Bases: ExplainerBase

compute_loss(model_out, x, target_label)

generate_counterfactuals(query_instance, total_CFs, desired_class='opposite')

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)

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)

Bases: FeasibleBaseVAE, ExplainerBase

train(constraint_type, constraint_variables, constraint_direction, constraint_reg, pre_trained=False)

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