Merge branch 'master' into gaugup/AddValidationsToGenerateCounterfactuals

Author: gaugup

.github/workflows/python-linting.yml

@@ -0,0 +1,41 @@
+# This workflow will lint python code with flake8 and flake8-nb.
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Python linting
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.7
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8==3.9.2 flake8-nb==0.3.0 isort
+    - name: Check sorted python imports using isort
+      run: |
+        isort . -c
+    - name: Lint code with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # The GitHub editor is 127 chars wide.
+        flake8 . --count --max-complexity=30 --max-line-length=127 --statistics
+        # Check for cyclometric complexity for specific files where this metric has been 
+        # reduced to ten and below
+        flake8 dice_ml/data_interfaces/ --count --max-complexity=10 --max-line-length=127
+    - name: Lint notebooks with flake8_nb
+      run: |
+        # stop the build if there are flake8 errors in notebooks
+        flake8_nb docs/source/notebooks/ --statistics --max-line-length=127

.github/workflows/pythonpackage.yml

@@ -1,7 +1,7 @@
 # This workflow will install Python dependencies, run tests and lint with a variety of Python versions
 # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
 
-name: Python package
+name: Python package test
 
 on:
   push:
@@ -24,25 +24,18 @@ jobs:
       uses: actions/setup-python@v1
       with:
         python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
+    - name: Upgrade pip
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements-test.txt
+    - name: Install core dependencies
+      run: |
         pip install -r requirements.txt
-        pip install -r requirements-deeplearning.txt
-    - name: Lint code with flake8
+    - name: Install deep learning dependencies
       run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # The GitHub editor is 127 chars wide.
-        flake8 . --count --max-complexity=30 --max-line-length=127 --statistics
-        # Check for cyclometric complexity for specific files where this metric has been 
-        # reduced to ten and below
-        flake8 dice_ml/data_interfaces/ --count --max-complexity=10 --max-line-length=127
-    - name: Lint notebooks with flake8_nb
+        pip install -r requirements-deeplearning.txt
+    - name: Install test dependencies
       run: |
-        # stop the build if there are flake8 errors in notebooks
-        flake8_nb docs/source/notebooks/ --statistics --max-line-length=127
+        pip install -r requirements-test.txt
     - name: Test with pytest
       run: |
         # pytest

.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
 
 

CODEOWNERS

@@ -0,0 +1,2 @@
+# dice-ml package
+/dice_ml @gaugup @amit-sharma

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

README.rst

@@ -66,6 +66,7 @@ If you face any problems, try installing dependencies manually.
 
 DiCE requires the following packages:
 
+* jsonschema
 * numpy
 * scikit-learn
 * pandas
@@ -119,6 +120,18 @@ Using DiCE, we can now generate examples that would have been classified as clas
   :width: 400
   :alt: List of counterfactual examples
 
+You can save the generated counterfactual examples in the following way:-
+
+.. code:: python
+
+    # Generate counterfactual examples
+    dice_exp = exp.generate_counterfactuals(query_instance, total_CFs=4, desired_class="opposite")
+    # Visualize counterfactual explanation
+    dice_exp.visualize_as_dataframe()
+    # Save generated counterfactual examples to disk
+    dice_exp.cf_examples_list[0].final_cfs_df.to_csv(path_or_buf='counterfactuals.csv', index=False)
+
+
 For more details, check out the `docs/source/notebooks <https://github.com/interpretml/DiCE/tree/master/docs/source/notebooks>`_ folder. Here are some example notebooks:
 
 * `Getting Started <https://github.com/interpretml/DiCE/blob/master/docs/source/notebooks/DiCE_getting_started.ipynb>`_: Generate CF examples for a `sklearn`, `tensorflow` or `pytorch` binary classifier and compute feature importance scores.

dice_ml/__init__.py

@@ -1,6 +1,6 @@
 from .data import Data
-from .model import Model
 from .dice import Dice
+from .model import Model
 
 __all__ = ["Data",
            "Model",

dice_ml/counterfactual_explanations.py

@@ -1,11 +1,12 @@
 import json
-import jsonschema
 import os
 
-from dice_ml.diverse_counterfactuals import CounterfactualExamples
-from dice_ml.utils.exception import UserConfigValidationException
-from dice_ml.diverse_counterfactuals import _DiverseCFV2SchemaConstants
+import jsonschema
+
 from dice_ml.constants import _SchemaVersions
+from dice_ml.diverse_counterfactuals import (CounterfactualExamples,
+                                             _DiverseCFV2SchemaConstants)
+from dice_ml.utils.exception import UserConfigValidationException
 
 
 class _CommonSchemaConstants:
@@ -45,10 +46,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 +119,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/data_interfaces/private_data_interface.py

@@ -1,15 +1,13 @@
 """Module containing meta data information about private data."""
 
-import sys
-import pandas as pd
-import numpy as np
 import collections
 import logging
+import sys
 
-from dice_ml.data_interfaces.base_data_interface import _BaseData
-
+import numpy as np
+import pandas as pd
 
-logging.basicConfig(level=logging.NOTSET)
+from dice_ml.data_interfaces.base_data_interface import _BaseData
 
 
 class PrivateData(_BaseData):

dice_ml/data_interfaces/public_data_interface.py

@@ -1,13 +1,15 @@
 """Module containing all required information about the interface between raw (or transformed)
 public data and DiCE explainers."""
 
-import pandas as pd
-import numpy as np
 import logging
 from collections import defaultdict
 
+import numpy as np
+import pandas as pd
+
 from dice_ml.data_interfaces.base_data_interface import _BaseData
-from dice_ml.utils.exception import SystemException, UserConfigValidationException
+from dice_ml.utils.exception import (SystemException,
+                                     UserConfigValidationException)
 
 
 class PublicData(_BaseData):
@@ -147,6 +149,37 @@ def _validate_and_set_permitted_range(self, params):
                     )
         self.permitted_range, _ = self.get_features_range(input_permitted_range)
 
+    def check_features_to_vary(self, features_to_vary):
+        if features_to_vary is not None and features_to_vary != 'all':
+            not_training_features = set(features_to_vary) - set(self.feature_names)
+            if len(not_training_features) > 0:
+                raise UserConfigValidationException("Got features {0} which are not present in training data".format(
+                    not_training_features))
+
+    def check_permitted_range(self, permitted_range):
+        if permitted_range is not None:
+            permitted_range_features = list(permitted_range)
+            not_training_features = set(permitted_range_features) - set(self.feature_names)
+            if len(not_training_features) > 0:
+                raise UserConfigValidationException("Got features {0} which are not present in training data".format(
+                    not_training_features))
+
+            for feature in permitted_range_features:
+                if feature in self.categorical_feature_names:
+                    train_categories = self.permitted_range[feature]
+                    for test_category in permitted_range[feature]:
+                        if test_category not in train_categories:
+                            raise UserConfigValidationException(
+                                'The category {0} does not occur in the training data for feature {1}.'
+                                ' Allowed categories are {2}'.format(test_category, feature, train_categories))
+
+    def check_mad_validity(self, feature_weights):
+        """checks feature MAD validity and throw warnings.
+           TODO: add comments as to where this is used if this function is necessary, else remove.
+        """
+        if feature_weights == "inverse_mad":
+            self.get_valid_mads(display_warnings=True, return_mads=False)
+
     def get_features_range(self, permitted_range_input=None):
         ranges = {}
         # Getting default ranges based on the dataset