Version Bump: Update to v0.7 (#210)

* version update and initial make html

* updated sphinx docstring bugs and markdown formatting for model agnostic notebook

* updated html docs

.gitignore

@@ -113,5 +113,6 @@ docs/notebooks/DiCE_getting_started.ipynb
 docs/notebooks/DiCE_getting_started_feasible.ipynb
 docs/notebooks/DiCE_with_advanced_options.ipynb
 docs/notebooks/DiCE_with_private_data.ipynb
+docs/notebooks/*.ipynb
 
 

MANIFEST.in

@@ -1,5 +1,6 @@
 include requirements.txt
 include requirements-deeplearning.txt
+include requirements-test.txt
 include LICENSE
 recursive-include docs *
 recursive-include tests *.py

dice_ml/counterfactual_explanations.py

@@ -45,10 +45,10 @@ class CounterfactualExplanations:
 
     :param cf_examples_list: A list of CounterfactualExamples instances
     :param local_importance: List of estimated local importance scores. The
-    size of the list is the number of input instances, each containing feature
-    importance scores for that input.
+        size of the list is the number of input instances, each containing
+        feature importance scores for that input.
     :param summary_importance: Estimated global feature importance scores
-    based on the input set of CounterfactualExamples instances
+        based on the input set of CounterfactualExamples instances
 
     """
     def __init__(self, cf_examples_list,
@@ -118,6 +118,7 @@ def _check_cf_exp_output_against_json_schema(
 
         :param cf_dict: Serialized version of the counterfactual explanations.
         :type cf_dict: Dict
+
         """
         schema_file_name = 'counterfactual_explanations_v{0}.json'.format(version)
         schema_path = os.path.join(os.path.dirname(__file__),

dice_ml/explainer_interfaces/dice_pytorch.py

@@ -55,7 +55,7 @@ def generate_counterfactuals(self, query_instance, total_CFs, desired_class="opp
                                  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"):
-        """Generates diverse counterfactual explanations
+        """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.
@@ -67,7 +67,7 @@ def generate_counterfactuals(self, query_instance, total_CFs, desired_class="opp
         :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.
+        :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".
@@ -94,6 +94,7 @@ def generate_counterfactuals(self, query_instance, total_CFs, desired_class="opp
                                            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.
+
         :return: A CounterfactualExamples object to store and visualize the resulting
                  counterfactual explanations (see diverse_counterfactuals.py).
         """
@@ -417,7 +418,7 @@ def find_counterfactuals(self, query_instance, desired_class, optimizer, learnin
                              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):
-        """Finds counterfactuals by graident-descent."""
+        """Finds counterfactuals by gradient-descent."""
 
         # Prepares user defined query_instance for DiCE.
         # query_instance = self.data_interface.prepare_query_instance(query_instance=query_instance, encoding='one-hot')

dice_ml/explainer_interfaces/dice_tensorflow1.py

@@ -21,6 +21,7 @@ def __init__(self, data_interface, model_interface):
 
         :param data_interface: an interface class to access data related params.
         :param model_interface: an interface class to access trained ML model.
+
         """
         # initiating data related parameters
         super().__init__(data_interface)
@@ -83,7 +84,7 @@ def generate_counterfactuals(self, query_instance, total_CFs, desired_class="opp
 
         :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.
+        :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".
@@ -112,8 +113,10 @@ def generate_counterfactuals(self, query_instance, total_CFs, desired_class="opp
                                            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.
+
         :return: A CounterfactualExamples object to store and visualize the resulting counterfactual explanations
                  (see diverse_counterfactuals.py).
+
         """
 
         # check feature MAD validity and throw warnings

dice_ml/explainer_interfaces/dice_tensorflow2.py

@@ -19,6 +19,7 @@ def __init__(self, data_interface, model_interface):
         """Init method
         :param data_interface: an interface class to access data related params.
         :param model_interface: an interface class to access trained ML model.
+
         """
         # initiating data related parameters
         super().__init__(data_interface)
@@ -69,7 +70,7 @@ def generate_counterfactuals(self, query_instance, total_CFs, desired_class="opp
                                     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.
+        :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".
@@ -100,6 +101,7 @@ def generate_counterfactuals(self, query_instance, total_CFs, desired_class="opp
 
         :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":

dice_ml/explainer_interfaces/explainer_base.py

@@ -531,8 +531,8 @@ def misc_init(self, stopping_threshold, desired_class, desired_range, test_pred)
     def infer_target_cfs_class(self, 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.
+            TODO: Add support for opposite desired class in multiclass.
+            Downstream methods should decide whether it is allowed or not.
         """
         if desired_class_input == "opposite":
             if num_output_nodes == 2:

dice_ml/model_interfaces/base_model.py

@@ -26,6 +26,7 @@ def __init__(self, model=None, model_path='', backend='', func=None, kw_args=Non
         :param func: function transformation required for ML model. If func is None, then func will be the identity function.
         :param kw_args: Dictionary of additional keyword arguments to pass to func. DiCE's data_interface is appended to the
                         dictionary of kw_args, by default.
+
         """
         self.model = model
         self.model_path = model_path

docs/_modules/dice_ml/constants.html

@@ -0,0 +1,248 @@
+
+
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" >
+<head>
+  <meta charset="utf-8">
+
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+  <title>dice_ml.constants &mdash; DiCE 0.7 documentation</title>
+
+
+
+  <link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
+  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
+
+
+
+
+
+
+
+  <!--[if lt IE 9]>
+    <script src="../../_static/js/html5shiv.min.js"></script>
+  <![endif]-->
+
+
+      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
+        <script src="../../_static/jquery.js"></script>
+        <script src="../../_static/underscore.js"></script>
+        <script src="../../_static/doctools.js"></script>
+        <script src="../../_static/language_data.js"></script>
+        <script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
+        <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
+        <script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"inlineMath": [["$", "$"], ["\\(", "\\)"]], "processEscapes": true, "ignoreClass": "document", "processClass": "math|output_area"}})</script>
+
+    <script type="text/javascript" src="../../_static/js/theme.js"></script>
+
+
+    <link rel="index" title="Index" href="../../genindex.html" />
+    <link rel="search" title="Search" href="../../search.html" /> 
+</head>
+
+<body class="wy-body-for-nav">
+
+
+  <div class="wy-grid-for-nav">
+
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+
+
+
+            <a href="../../index.html" class="icon icon-home" alt="Documentation Home"> DiCE
+
+
+
+          </a>
+
+
+
+
+
+
+
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+
+
+        </div>
+
+
+        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
+
+
+
+
+
+
+              <p class="caption"><span class="caption-text">Getting Started:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../readme.html">Diverse Counterfactual Explanations (DiCE) for ML</a></li>
+</ul>
+<p class="caption"><span class="caption-text">Notebooks:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_getting_started.html">Quick introduction to generating counterfactual explanations using DiCE</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_feature_importances.html">Estimating local and global feature importance scores using DiCE</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_multiclass_classification_and_regression.html">Generating counterfactuals for multi-class classification and regression models</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_multiclass_classification_and_regression.html#Regression">Regression</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_model_agnostic_CFs.html">Generating counterfactual explanations with any ML model</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_with_private_data.html">Generating Counterfactual Explanations without access to training data</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_with_advanced_options.html">Advanced options to customize Counterfactual Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_getting_started_feasible.html">Generate feasible counterfactual explanations using a VAE</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../notebooks/DiCE_getting_started_feasible.html#Adding-feasibility-constraints">Adding feasibility constraints</a></li>
+</ul>
+<p class="caption"><span class="caption-text">Package:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../dice_ml.html">dice_ml package</a></li>
+</ul>
+
+
+
+        </div>
+
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+
+
+      <nav class="wy-nav-top" aria-label="top navigation">
+
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../../index.html">DiCE</a>
+
+      </nav>
+
+
+      <div class="wy-nav-content">
+
+        <div class="rst-content">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<div role="navigation" aria-label="breadcrumbs navigation">
+
+  <ul class="wy-breadcrumbs">
+
+      <li><a href="../../index.html" class="icon icon-home"></a> &raquo;</li>
+
+          <li><a href="../index.html">Module code</a> &raquo;</li>
+
+      <li>dice_ml.constants</li>
+
+
+      <li class="wy-breadcrumbs-aside">
+
+      </li>
+
+  </ul>
+
+
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+
+  <h1>Source code for dice_ml.constants</h1><div class="highlight"><pre>
+<span></span><span class="sd">&quot;&quot;&quot;Constants for dice-ml package.&quot;&quot;&quot;</span>
+
+
+<div class="viewcode-block" id="BackEndTypes"><a class="viewcode-back" href="../../dice_ml.html#dice_ml.constants.BackEndTypes">[docs]</a><span class="k">class</span> <span class="nc">BackEndTypes</span><span class="p">:</span>
+    <span class="n">Sklearn</span> <span class="o">=</span> <span class="s1">&#39;sklearn&#39;</span>
+    <span class="n">Tensorflow1</span> <span class="o">=</span> <span class="s1">&#39;TF1&#39;</span>
+    <span class="n">Tensorflow2</span> <span class="o">=</span> <span class="s1">&#39;TF2&#39;</span>
+    <span class="n">Pytorch</span> <span class="o">=</span> <span class="s1">&#39;PYT&#39;</span>
+
+    <span class="n">ALL</span> <span class="o">=</span> <span class="p">[</span><span class="n">Sklearn</span><span class="p">,</span> <span class="n">Tensorflow1</span><span class="p">,</span> <span class="n">Tensorflow2</span><span class="p">,</span> <span class="n">Pytorch</span><span class="p">]</span></div>
+
+
+<div class="viewcode-block" id="SamplingStrategy"><a class="viewcode-back" href="../../dice_ml.html#dice_ml.constants.SamplingStrategy">[docs]</a><span class="k">class</span> <span class="nc">SamplingStrategy</span><span class="p">:</span>
+    <span class="n">Random</span> <span class="o">=</span> <span class="s1">&#39;random&#39;</span>
+    <span class="n">Genetic</span> <span class="o">=</span> <span class="s1">&#39;genetic&#39;</span>
+    <span class="n">KdTree</span> <span class="o">=</span> <span class="s1">&#39;kdtree&#39;</span></div>
+
+
+<div class="viewcode-block" id="ModelTypes"><a class="viewcode-back" href="../../dice_ml.html#dice_ml.constants.ModelTypes">[docs]</a><span class="k">class</span> <span class="nc">ModelTypes</span><span class="p">:</span>
+    <span class="n">Classifier</span> <span class="o">=</span> <span class="s1">&#39;classifier&#39;</span>
+    <span class="n">Regressor</span> <span class="o">=</span> <span class="s1">&#39;regressor&#39;</span>
+
+    <span class="n">ALL</span> <span class="o">=</span> <span class="p">[</span><span class="n">Classifier</span><span class="p">,</span> <span class="n">Regressor</span><span class="p">]</span></div>
+
+
+<span class="k">class</span> <span class="nc">_SchemaVersions</span><span class="p">:</span>
+    <span class="n">V1</span> <span class="o">=</span> <span class="s1">&#39;1.0&#39;</span>
+    <span class="n">V2</span> <span class="o">=</span> <span class="s1">&#39;2.0&#39;</span>
+    <span class="n">CURRENT_VERSION</span> <span class="o">=</span> <span class="n">V2</span>
+
+    <span class="n">ALL_VERSIONS</span> <span class="o">=</span> <span class="p">[</span><span class="n">V1</span><span class="p">,</span> <span class="n">V2</span><span class="p">]</span>
+</pre></div>
+
+           </div>
+
+          </div>
+          <footer>
+
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>
+
+        &copy; Copyright 2020, Ramaravind, Amit, Chenhao
+
+    </p>
+  </div>
+
+
+
+    Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a
+
+    <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a>
+
+    provided by <a href="https://readthedocs.org">Read the Docs</a>. 
+
+</footer>
+
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+
+
+  <script type="text/javascript">
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script>
+
+
+
+
+
+
+</body>
+</html>