dice_ml.dice_interfaces package — DiCE 0.2 documentation

# dice_ml.dice_interfaces package

## Submodules

## dice_ml.dice_interfaces.dice_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.dice_interfaces

class `dice_ml.dice_interfaces.dice_base.` `DiceBase`(data_interface)

  Bases: `object`

  `generate_counterfactuals`()

## dice_ml.dice_interfaces.dice_pytorch module

## dice_ml.dice_interfaces.dice_tensorflow1 module

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

class `dice_ml.dice_interfaces.dice_tensorflow1.` `DiceTensorFlow1`(data_interface, model_interface)

  Bases: `dice_ml.dice_interfaces.dice_base.DiceBase`

  `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, 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)

    Finds counterfactuals by graident-descent.

  `generate_counterfactuals`(query_instance, total_CFs, desired_class='opposite', proximity_weight=0.5, diversity_weight=1.0, categorical_penalty=0.1, algorithm='DiverseCF', features_to_vary='all', yloss_type='hinge_loss', diversity_loss_type='dpp_style:inverse_dist', feature_weights='inverse_mad', optimizer='tensorflow:adam', 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=True, tie_random=False, stopping_threshold=0.5, posthoc_sparsity_param=0.1)

    Generates diverse counterfactual explanations

    Parameters

      - query_instance – A dictionary of feature names and values. Test point of interest.

      - 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.

      - proximity_weight – A positive float. Larger this weight, more close the counterfactuals are to the query_instance.

      - diversity_weight – A positive float. Larger this weight, more diverse the counterfactuals are.

      - categorical_penalty – A positive float. A weight to ensure that all levels of a categorical variable sums to 1.

      - algorithm – Counterfactual generation algorithm. Either “DiverseCF” or “RandomInitCF”.

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

      - yloss_type – Metric for y-loss of the optimization function. Takes “l2_loss” or “log_loss” or “hinge_loss”.

      - diversity_loss_type – Metric for diversity loss of the optimization function. Takes “avg_dist” or “dpp_style:inverse_dist”.

      - feature_weights – Either “inverse_mad” or a dictionary with feature names as keys and corresponding weights as values. Default option is “inverse_mad” where the weight for a continuous feature is the inverse of the Median Absolute Devidation (MAD) of the feature’s values in the training set; the weight for a categorical feature is equal to 1 by default.

      - optimizer – Tensorflow optimization algorithm. Currently tested only with “tensorflow:adam”.

      - learning_rate – Learning rate for optimizer.

      - min_iter – Min iterations to run gradient descent for.

      - max_iter – Max iterations to run gradient descent for.

      - project_iter – Project the gradients at an interval of these many iterations.

      - loss_diff_thres – Minimum difference between successive loss values to check convergence.

      - loss_converge_maxiter – Maximum number of iterations for loss_diff_thres to hold to declare convergence. Defaults to 1, but we assigned a more conservative value of 2 in the paper.

      - verbose – Print intermediate loss value.

      - init_near_query_instance – Boolean to indicate if counterfactuals are to be initialized near query_instance.

      - tie_random – Used in rounding off CFs and intermediate projection.

      - stopping_threshold – Minimum threshold for counterfactuals target class probability.

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

    Returns

      A CounterfactualExamples object to store and visualize the resulting counterfactual explanations (see diverse_counterfactuals.py).

  `initialize_CFs`(query_instance, init_near_query_instance=False)

    Initialize counterfactuals.

  `predict_fn`(input_instance)

    prediction function

  `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.dice_interfaces.dice_tensorflow2 module

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

class `dice_ml.dice_interfaces.dice_tensorflow2.` `DiceTensorFlow2`(data_interface, model_interface)

  Bases: `dice_ml.dice_interfaces.dice_base.DiceBase`

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

    Finds counterfactuals by graident-descent.

  `generate_counterfactuals`(query_instance, total_CFs, desired_class='opposite', proximity_weight=0.5, diversity_weight=1.0, categorical_penalty=0.1, algorithm='DiverseCF', features_to_vary='all', yloss_type='hinge_loss', diversity_loss_type='dpp_style:inverse_dist', feature_weights='inverse_mad', optimizer='tensorflow:adam', 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=True, tie_random=False, stopping_threshold=0.5, posthoc_sparsity_param=0.1)

    Generates diverse counterfactual explanations

    Parameters

      - query_instance – A dictionary of feature names and values. Test point of interest.

      - 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.

      - proximity_weight – A positive float. Larger this weight, more close the counterfactuals are to the query_instance.

      - diversity_weight – A positive float. Larger this weight, more diverse the counterfactuals are.

      - categorical_penalty – A positive float. A weight to ensure that all levels of a categorical variable sums to 1.

      - algorithm – Counterfactual generation algorithm. Either “DiverseCF” or “RandomInitCF”.

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

      - yloss_type – Metric for y-loss of the optimization function. Takes “l2_loss” or “log_loss” or “hinge_loss”.

      - diversity_loss_type – Metric for diversity loss of the optimization function. Takes “avg_dist” or “dpp_style:inverse_dist”.

      - feature_weights – Either “inverse_mad” or a dictionary with feature names as keys and corresponding weights as values. Default option is “inverse_mad” where the weight for a continuous feature is the inverse of the Median Absolute Devidation (MAD) of the feature’s values in the training set; the weight for a categorical feature is equal to 1 by default.

      - optimizer – Tensorflow optimization algorithm. Currently tested only with “tensorflow:adam”.

      - learning_rate – Learning rate for optimizer.

      - min_iter – Min iterations to run gradient descent for.

      - max_iter – Max iterations to run gradient descent for.

      - project_iter – Project the gradients at an interval of these many iterations.

      - loss_diff_thres – Minimum difference between successive loss values to check convergence.

      - loss_converge_maxiter – Maximum number of iterations for loss_diff_thres to hold to declare convergence. Defaults to 1, but we assigned a more conservative value of 2 in the paper.

      - verbose – Print intermediate loss value.

      - init_near_query_instance – Boolean to indicate if counterfactuals are to be initialized near query_instance.

      - tie_random – Used in rounding off CFs and intermediate projection.

      - stopping_threshold – Minimum threshold for counterfactuals target class probability.

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

    Returns

      A CounterfactualExamples object to store and visualize the resulting counterfactual explanations (see diverse_counterfactuals.py).

  `initialize_CFs`(query_instance, init_near_query_instance=False)

    Initialize counterfactuals.

  `predict_fn`(input_instance)

    prediction function

  `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

## Module contents