docstr: Generates diverse counterfactual explanations
  
  :param query_instance: Test point of interest. A dictionary of feature names and values or a single row dataframe.
  :param total_CFs: Total number of counterfactuals required.
  :param desired_class: Desired counterfactual class - can take 0 or 1. Default value is "opposite" to the
                        outcome class of query_instance for binary classification.
  :param proximity_weight: A positive float. Larger this weight, more close the counterfactuals are to the
                           query_instance.
  :param diversity_weight: A positive float. Larger this weight, more diverse the counterfactuals are.
  :param categorical_penalty: A positive float. A weight to ensure that all levels of a categorical variable sums to 1.
  
  :param algorithm: Counterfactual generation algorithm. Either "DiverseCF" or "RandomInitCF".
  :param features_to_vary: Either a string "all" or a list of feature names to vary.
  :param permitted_range: Dictionary with continuous feature names as keys and permitted min-max range in list as values.
                         Defaults to the range inferred from training data. If None, uses the parameters initialized in
                         data_interface.
  :param yloss_type: Metric for y-loss of the optimization function. Takes "l2_loss" or "log_loss" or "hinge_loss".
  :param diversity_loss_type: Metric for diversity loss of the optimization function.
                              Takes "avg_dist" or "dpp_style:inverse_dist".
  :param 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.
  :param optimizer: Tensorflow optimization algorithm. Currently tested only with "tensorflow:adam".
  
  :param learning_rate: Learning rate for optimizer.
  :param min_iter: Min iterations to run gradient descent for.
  :param max_iter: Max iterations to run gradient descent for.
  :param project_iter: Project the gradients at an interval of these many iterations.
  :param loss_diff_thres: Minimum difference between successive loss values to check convergence.
  :param 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.
  :param verbose: Print intermediate loss value.
  :param init_near_query_instance: Boolean to indicate if counterfactuals are to be initialized near query_instance.
  :param tie_random: Used in rounding off CFs and intermediate projection.
  :param stopping_threshold: Minimum threshold for counterfactuals target class probability.
  :param posthoc_sparsity_param: Parameter for the post-hoc operation on continuous features to enhance sparsity.
  :param 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.
  :param limit_steps_ls: Defines an upper limit for the linear search step in the posthoc_sparsity_enhancement
  
  
  :return: A CounterfactualExamples object to store and visualize the resulting counterfactual explanations
           (see diverse_counterfactuals.py).
docstr_tok: ["Generates","diverse","counterfactual","explanations",":","param","query_instance",":","Test","point","of","interest",".","A","dictionary","of","feature","names","and","values","or","a","single","row","dataframe",".",":","param","total_CFs",":","Total","number","of","counterfactuals","required",".",":","param","desired_class",":","Desired","counterfactual","class","-","can","take","0","or","1",".","Default","value","is","``","opposite","''","to","the","outcome","class","of","query_instance","for","binary","classification",".",":","param","proximity_weight",":","A","positive","float",".","Larger","this","weight",",","more","close","the","counterfactuals","are","to","the","query_instance",".",":","param","diversity_weight",":","A","positive","float",".","Larger","this","weight",",","more","diverse","the","counterfactuals","are",".",":","param","categorical_penalty",":","A","positive","float",".","A","weight","to","ensure","that","all","levels","of","a","categorical","variable","sums","to","1.",":","param","algorithm",":","Counterfactual","generation","algorithm",".","Either","``","DiverseCF","''","or","``","RandomInitCF","''",".",":","param","features_to_vary",":","Either","a","string","``","all","''","or","a","list","of","feature","names","to","vary",".",":","param","permitted_range",":","Dictionary","with","continuous","feature","names","as","keys","and","permitted","min-max","range","in","list","as","values",".","Defaults","to","the","range","inferred","from","training","data",".","If","None",",","uses","the","parameters","initialized","in","data_interface",".",":","param","yloss_type",":","Metric","for","y-loss","of","the","optimization","function",".","Takes","``","l2_loss","''","or","``","log_loss","''","or","``","hinge_loss","''",".",":","param","diversity_loss_type",":","Metric","for","diversity","loss","of","the","optimization","function",".","Takes","``","avg_dist","''","or","``","dpp_style",":","inverse_dist","''",".",":","param","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",".",":","param","optimizer",":","Tensorflow","optimization","algorithm",".","Currently","tested","only","with","``","tensorflow",":","adam","''",".",":","param","learning_rate",":","Learning","rate","for","optimizer",".",":","param","min_iter",":","Min","iterations","to","run","gradient","descent","for",".",":","param","max_iter",":","Max","iterations","to","run","gradient","descent","for",".",":","param","project_iter",":","Project","the","gradients","at","an","interval","of","these","many","iterations",".",":","param","loss_diff_thres",":","Minimum","difference","between","successive","loss","values","to","check","convergence",".",":","param","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",".",":","param","verbose",":","Print","intermediate","loss","value",".",":","param","init_near_query_instance",":","Boolean","to","indicate","if","counterfactuals","are","to","be","initialized","near","query_instance",".",":","param","tie_random",":","Used","in","rounding","off","CFs","and","intermediate","projection",".",":","param","stopping_threshold",":","Minimum","threshold","for","counterfactuals","target","class","probability",".",":","param","posthoc_sparsity_param",":","Parameter","for","the","post-hoc","operation","on","continuous","features","to","enhance","sparsity",".",":","param","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",".",":","param","limit_steps_ls",":","Defines","an","upper","limit","for","the","linear","search","step","in","the","posthoc_sparsity_enhancement",":","return",":","A","CounterfactualExamples","object","to","store","and","visualize","the","resulting","counterfactual","explanations","(","see","diverse_counterfactuals.py",")","."]
code: def generate_counterfactuals(
      self,
      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",
      permitted_range=None,
      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-5,
      loss_converge_maxiter=1,
      verbose=False,
      init_near_query_instance=True,
      tie_random=False,
      stopping_threshold=0.5,
      posthoc_sparsity_param=0.1,
      posthoc_sparsity_algorithm="linear",
      limit_steps_ls=10000,
  ):
      """Generates diverse counterfactual explanations
  
      :param query_instance: Test point of interest. A dictionary of feature names and values or a single row dataframe.
      :param total_CFs: Total number of counterfactuals required.
      :param desired_class: Desired counterfactual class - can take 0 or 1. Default value is "opposite" to the
                            outcome class of query_instance for binary classification.
      :param proximity_weight: A positive float. Larger this weight, more close the counterfactuals are to the
                               query_instance.
      :param diversity_weight: A positive float. Larger this weight, more diverse the counterfactuals are.
      :param categorical_penalty: A positive float. A weight to ensure that all levels of a categorical variable sums to 1.
  
      :param algorithm: Counterfactual generation algorithm. Either "DiverseCF" or "RandomInitCF".
      :param features_to_vary: Either a string "all" or a list of feature names to vary.
      :param permitted_range: Dictionary with continuous feature names as keys and permitted min-max range in list as values.
                             Defaults to the range inferred from training data. If None, uses the parameters initialized in
                             data_interface.
      :param yloss_type: Metric for y-loss of the optimization function. Takes "l2_loss" or "log_loss" or "hinge_loss".
      :param diversity_loss_type: Metric for diversity loss of the optimization function.
                                  Takes "avg_dist" or "dpp_style:inverse_dist".
      :param 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.
      :param optimizer: Tensorflow optimization algorithm. Currently tested only with "tensorflow:adam".
  
      :param learning_rate: Learning rate for optimizer.
      :param min_iter: Min iterations to run gradient descent for.
      :param max_iter: Max iterations to run gradient descent for.
      :param project_iter: Project the gradients at an interval of these many iterations.
      :param loss_diff_thres: Minimum difference between successive loss values to check convergence.
      :param 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.
      :param verbose: Print intermediate loss value.
      :param init_near_query_instance: Boolean to indicate if counterfactuals are to be initialized near query_instance.
      :param tie_random: Used in rounding off CFs and intermediate projection.
      :param stopping_threshold: Minimum threshold for counterfactuals target class probability.
      :param posthoc_sparsity_param: Parameter for the post-hoc operation on continuous features to enhance sparsity.
      :param 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.
      :param limit_steps_ls: Defines an upper limit for the linear search step in the posthoc_sparsity_enhancement
  
  
      :return: A CounterfactualExamples object to store and visualize the resulting counterfactual explanations
               (see diverse_counterfactuals.py).
  
      """
  
      # check feature MAD validity and throw warnings
      if feature_weights == "inverse_mad":
          self.data_interface.get_valid_mads(
              display_warnings=True, return_mads=False
          )
  
      # check permitted range for continuous features
      if permitted_range is not None:
          self.data_interface.permitted_range = permitted_range
          self.minx, self.maxx = self.data_interface.get_minx_maxx(
              normalized=True
          )
          self.cont_minx = []
          self.cont_maxx = []
          for feature in self.data_interface.continuous_feature_names:
              self.cont_minx.append(
                  self.data_interface.permitted_range[feature][0]
              )
              self.cont_maxx.append(
                  self.data_interface.permitted_range[feature][1]
              )
  
      if [
          total_CFs,
          algorithm,
          features_to_vary,
          yloss_type,
          diversity_loss_type,
          feature_weights,
          optimizer,
      ] != (
          self.cf_init_weights
          + self.loss_weights
          + self.optimizer_weights
      ):
          self.do_cf_initializations(
              total_CFs, algorithm, features_to_vary
          )
          self.do_loss_initializations(
              yloss_type, diversity_loss_type, feature_weights
          )
          self.do_optimizer_initializations(optimizer)
  
      """
          Future Support: We have three main components in our tensorflow graph:
          (1) initialization of tf.variables
          (2) defining ops for loss function initializations, and
          (3) defining ops for optimizer initializations.
  
          Need to define methods to delete some nodes from a tensorflow graphs or update
          variables/ops in a tensorflow graph dynamically, so that only those components
          corresponding to the variables that are updated change.
          """
      # check if hyperparameters are to be updated
      if not collections.Counter(
          [proximity_weight, diversity_weight, categorical_penalty]
      ) == collections.Counter(self.hyperparameters):
          self.update_hyperparameters(
              proximity_weight, diversity_weight, categorical_penalty
          )
  
      (
          final_cfs_df,
          test_instance_df,
          final_cfs_df_sparse,
      ) = self.find_counterfactuals(
          query_instance,
          limit_steps_ls,
          desired_class,
          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,
      )
  
      counterfactual_explanations = exp.CounterfactualExamples(
          data_interface=self.data_interface,
          final_cfs_df=final_cfs_df,
          test_instance_df=test_instance_df,
          final_cfs_df_sparse=final_cfs_df_sparse,
          posthoc_sparsity_param=posthoc_sparsity_param,
          desired_class=desired_class,
      )
  
      return CounterfactualExplanations(
          cf_examples_list=[counterfactual_explanations]
      )
  
imports: import collections
  import copy
  import random
  import timeit
  import numpy
  import tensorflow
  from dice_ml import diverse_counterfactuals
  from dice_ml.counterfactual_explanations import CounterfactualExplanations
  from dice_ml.explainer_interfaces.explainer_base import ExplainerBase
label_desc: Use image node_id 2 for calling the DiceTensorFlow1 obj's underlying member method code with example usage: obj.generate_counterfactuals(query_instance, total_CFs, desired_class, proximity_weight, diversity_weight, categorical_penalty, algorithm, features_to_vary, permitted_range, yloss_type, diversity_loss_type, feature_weights, 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) and returns: CounterfactualExplanations