Add additional parameters to generate_counterfactuals() function (#251)

* Add additional parameters to generate_counterfactuals() function

Signed-off-by: gaugup <gaugup@microsoft.com>

* added the docs for methods

* Fix flake8 error

Signed-off-by: Gaurav Gupta <gaugup@microsoft.com>

Co-authored-by: Amit Sharma <amit_sharma@live.com>

Author: gaugup

dice_ml/explainer_interfaces/explainer_base.py

@@ -50,6 +50,8 @@ def generate_counterfactuals(self, 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,
+                                 proximity_weight=0.2, sparsity_weight=0.2, diversity_weight=5.0,
+                                 categorical_penalty=0.1,
                                  posthoc_sparsity_algorithm="linear", verbose=False, **kwargs):
         """General method for generating counterfactuals.
 
@@ -65,6 +67,15 @@ def generate_counterfactuals(self, query_instances, total_CFs,
                                 If None, uses the parameters initialized in data_interface.
         :param features_to_vary: Either a string "all" or a list of feature names to vary.
         :param stopping_threshold: Minimum threshold for counterfactuals target class probability.
+        :param 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.
+        :param 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.
+        :param diversity_weight: A positive float. Larger this weight, more diverse the counterfactuals are.
+                                 Used by ['genetic', 'gradientdescent'], ignored by ['random', 'kdtree'] methods.
+        :param 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.
         :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,

tests/test_dice_interface/test_explainer_base.py

@@ -365,6 +365,9 @@ def test_desired_class(
         ans = exp.generate_counterfactuals(query_instances=sample_custom_query_2,
                                            features_to_vary='all',
                                            total_CFs=2, desired_class=desired_class,
+                                           proximity_weight=0.2, sparsity_weight=0.2,
+                                           diversity_weight=5.0,
+                                           categorical_penalty=0.1,
                                            permitted_range=None)
         if method != 'kdtree':
             assert all(ans.cf_examples_list[0].final_cfs_df[exp.data_interface.outcome_name].values == [desired_class] * 2)