first version

.travis.yml

@@ -0,0 +1,27 @@
+language: python
+python:
+  - "3.6"
+
+# command to install dependencies
+install:
+  - pip3.6 install .
+    #- pip3.6 install -r requirements.txt
+
+# commands to run tes
+# before_script: redis-cli ping
+
+script:
+  - python3.6 ./tests/contrastive/test_CEM.py
+  - python3.6 ./tests/protodash/test_PDASH.py
+  - python3.6 ./tests/contrastive/test_CEM_MAF.py
+  - python3.6 ./tests/ted/test_TED_Cartesian.py
+  - CUDA_VISIBLE_DEVICES="" python3.6 ./tests/dipvae/test_DIPVAE.py
+  - python3.6 ./tests/rbm/test_Boolean_Rule_CG.py
+  - python3.6 ./tests/rbm/test_Linear_Rule_Regression.py
+  - python3.6 ./tests/rbm/test_Logistic_Rule_Regression.py
+
+after_success:
+#  - codecov
+
+services:
+#  - redis-server

CONTRIBUTING.md

@@ -21,14 +21,23 @@ Below is an (incomplete) list of people (in alphabetical order) who contributed
 via code, tests, or documentation:
 
 * Vijay Arya
+* Rachel Bellamy
+* Pin-Yu Chen
 * Amit Dhurandar
 * Mike Hind
-* Sam Hoffman
+* Samuel C. Hoffman
+* Stephanie Houde
+* Qingzi(Vera) Liao
+* Ronny Luss
 * Sameep Mehta
-* Sami Mourad
 * Saška Mojsilović
-* Animesh Singh
+* Sami Mourad
+* Pablo Pedemonte
+* John T. Richards
+* Prasanna Sattigeri
+* Karthikeyan Shanmugam
 * Moninder Singh
+* Animesh Singh
 * Kush Varshney
 * Dennis Wei
-
+* Yunfeng Zhang

README.md

@@ -1,4 +1,115 @@
-[![Build Status](https://travis-ci.com/IBM/AIX360.svg?branch=master)](https://travis-ci.com/IBM/AIX360) [![Documentation Status](https://readthedocs.org/projects/aix360/badge/?version=latest)](https://aix360.readthedocs.io/en/latest/?badge=latest)
+[![Build Status](https://travis.ibm.com/aix360/AIX360.svg?token=be4QPGQzRqgZ3sJhrG1n&branch=master)](https://travis.ibm.com/aix360/AIX360)
 
-# AIX360
-This project is about building AI eXplainability toolkit for explaining machine learning models and their predictions. We plan to support local/global post-hoc explanations for classifiers that use text/image/structured data.
+The AI Explainbability 360 toolkit is an open-source library that supports interpretability and explainability of data and machine learning models. The AI Explainability 360 Python package includes a comprehensive set of algorithms that cover different dimensions of explanations along with proxy explainability metrics. 
+
+The [AI Explainability 360 interactive experience](http://aix360.mybluemix.net/data) provides a gentle introduction to the concepts and capabilities by walking through an example use case for different consumer personas. The [tutorials and example notebooks](./examples) offer a deeper, data scientist-oriented introduction. The complete API is also available. 
+
+There is no single approach to explainability that works best. There are many ways to explain: data vs. model, directly interpretable vs. post hoc explanation, local vs. global, etc. It may therefore be confusing to figure out which algorithms are most appropriate for a given use case. To help, we have created some [guidance material](http://aix360.mybluemix.net/resources#guidance) and a [chart](./aix360/algorithms/README.md) that can be consulted. 
+
+We have developed the package with extensibility in mind. This library is still in development. We encourage the contribution of your explainability algorithms and metrics. To get started as a contributor, please join the [AI Explainability 360 Community](https://aix360.slack.com) by requesting an invitation [here](https://join.slack.com/t/aix360/shared_invite/enQtNzEyOTAwOTk1NzY2LTM1ZTMwM2M4OWQzNjhmNGRiZjg3MmJiYTAzNDU1MTRiYTIyMjFhZTI4ZDUwM2M1MGYyODkwNzQ2OWQzMThlN2Q). Please review the instructions to contribute code [here](CONTRIBUTING.md).
+
+## Supported explainability algorithms
+
+### Data explanation
+
+- ProtoDash ([Gurumoorthy et al., 2017](https://arxiv.org/abs/1707.01212))
+- Disentangled Inferred Prior VAE ([Kumar et al., 2018](https://openreview.net/forum?id=H1kG7GZAW))
+
+### Local post-hoc explanation
+
+- ProtoDash ([Gurumoorthy et al., 2017](https://arxiv.org/abs/1707.01212))
+- Contrastive Explanations Method ([Dhurandhar et al., 2018](https://papers.nips.cc/paper/7340-explanations-based-on-the-missing-towards-contrastive-explanations-with-pertinent-negatives))
+- Contrastive Explanations Method with Monotonic Attribute Functions ([Luss et al., 2019](https://arxiv.org/abs/1905.12698))
+
+### Local direct explanation
+
+- Teaching AI to Explain its Decisions ([Hind et al., 2019](https://doi.org/10.1145/3306618.3314273)) 
+
+### Global direct explanation
+
+- Boolean Decision Rules via Column Generation (Light Edition) ([Dash et al., 2018](https://papers.nips.cc/paper/7716-boolean-decision-rules-via-column-generation))
+- Generalized Linear Rule Models ([Wei et al., 2019](http://proceedings.mlr.press/v97/wei19a.html))
+
+### Global post-hoc explanation 
+
+- ProfWeight ([Dhurandhar et al., 2018](https://papers.nips.cc/paper/8231-improving-simple-models-with-confidence-profiles))
+
+
+## Supported explainability metrics
+- Faithfuless ([Alvarez-Melis and Jaakkola, 2018](https://papers.nips.cc/paper/8003-towards-robust-interpretability-with-self-explaining-neural-networks))
+- Monotonicity ([Luss et al., 2019](https://arxiv.org/abs/1905.12698))
+
+## Setup
+
+Supported Configurations:
+
+| OS      | Python version |
+| ------- | -------------- |
+| macOS   | 3.6  |
+| Ubuntu  | 3.6  |
+| Windows | 3.6  |
+
+
+### (Optional) Create a virtual environment
+
+AIX360 requires specific versions of many Python packages which may conflict
+with other projects on your system. A virtual environment manager is strongly
+recommended to ensure dependencies may be installed safely. If you have trouble
+installing AIX360, try this first.
+
+#### Conda
+
+Conda is recommended for all configurations though Virtualenv is generally
+interchangeable for our purposes. Miniconda is sufficient (see [the difference between Anaconda and
+Miniconda](https://conda.io/docs/user-guide/install/download.html#anaconda-or-miniconda)
+if you are curious) and can be installed from
+[here](https://conda.io/miniconda.html) if you do not already have it.
+
+Then, to create a new Python 3.6 environment, run:
+
+```bash
+conda create --name aix360 python=3.6
+conda activate aix360
+```
+
+The shell should now look like `(aix360) $`. To deactivate the environment, run:
+
+```bash
+(aix360)$ conda deactivate
+```
+
+The prompt will return back to `$ ` or `(base)$`.
+
+Note: Older versions of conda may use `source activate aix360` and `source
+deactivate` (`activate aix360` and `deactivate` on Windows).
+
+
+### Installation
+
+Clone the latest version of this repository:
+
+```bash
+(aix360)$ git clone https://github.com/IBM/AIX360
+```
+
+If you'd like to run the examples and tutorial notebooks, download the datasets now and place them in
+their respective folders as described in
+[aix360/data/README.md](aix360/data/README.md).
+
+Then, navigate to the root directory of the project which contains `setup.py` file and run:
+
+```bash
+(aix360)$ pip install -e .
+```
+
+## Using AIX360
+
+The `examples` directory contains a diverse collection of jupyter notebooks
+that use AI Explainability 360 in various ways. Both examples and tutorial notebooks illustrate
+working code using AIX360. Tutorials provide additional discussion that walks
+the user through the various steps of the notebook. See the details about
+[tutorials and demos here](examples/README.md)
+
+## Citing AIX360
+
+* Coming soon. 

aix360/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from .version import version as __version__
+except ImportError:
+    pass

aix360/algorithms/README.md

@@ -0,0 +1,3 @@
+# Guidance on use of AI Explainability 360 algorithms
+
+![Guidance](methods-choice.gif)

aix360/algorithms/__init__.py

@@ -0,0 +1 @@
+

aix360/algorithms/contrastive/CEM.py

@@ -0,0 +1,101 @@
+from __future__ import print_function
+
+from aix360.algorithms.lwbe import LocalWBExplainer
+
+from .CEM_aen import AEADEN
+
+import random
+import numpy as np
+
+
+class CEMExplainer(LocalWBExplainer):
+    """
+    CEMExplainer can be used to compute contrastive explanations for image and tabular data.
+    This is achieved by finding what is minimally sufficient (PP - Pertinent Positive) and
+    what should be necessarily absent (PN - Pertinent Negative) to maintain the original classification.
+    We use elastic norm regularization to ensure minimality for both parts of the explanation
+    i.e. PPs and PNs. An autoencoder can optionally be used to make the explanations more realistic. [#]_
+
+    References:
+        .. [#] `Amit Dhurandhar, Pin-Yu Chen, Ronny Luss, Chun-Chen Tu,
+           Paishun Ting, Karthikeyan Shanmugam, Payel Das, "Explanations based on
+           the Missing: Towards Contrastive Explanations with Pertinent Negatives,"
+           Advances in Neural Information Processing Systems (NeurIPS), 2018.
+           <https://arxiv.org/abs/1802.07623>`_
+    """
+    def __init__(self, model):
+
+        """
+        Constructor method, initializes the explainer
+
+        Args:
+            model: KerasClassifier model whose predictions needs to be explained
+        """
+        super(CEMExplainer, self).__init__()
+        self._wbmodel = model
+
+
+    def set_params(self, *argv, **kwargs):
+        """
+        Set parameters for the explainer.
+        """
+        pass
+
+
+    def explain_instance(self, input_X,
+                         arg_mode, AE_model, arg_kappa, arg_b,
+                         arg_max_iter, arg_init_const, arg_beta, arg_gamma):
+
+        """
+        Explains an input instance input_X and returns contrastive explanations
+
+        Args:
+            input_X (numpy.ndarray): input instance to be explained
+            arg_mode (str): 'PP' or 'PN'
+            AE_model: Auto-encoder model
+            arg_kappa (double): Confidence gap between desired class and other classes
+            arg_b (double): Number of different weightings of loss function to try
+            arg_max_iter (int): For each weighting of loss function number of iterations to search
+            arg_init_const (double): Initial weighting of loss function
+            arg_beta (double): Weighting of L1 loss
+            arg_gamma (double): Weighting of auto-encoder
+
+        Returns:
+            tuple:
+                * **adv_X** (`numpy ndarray`) -- Perturbed input instance for PP/PN
+                * **delta_X** (`numpy ndarray`) -- Difference between input and Perturbed instance
+                * **INFO** (`str`) -- Other information about PP/PN
+        """
+
+        random.seed(121)
+        np.random.seed(1211)
+
+        (_, orig_class, orig_prob_str) = self._wbmodel.predict_long(input_X)
+        target_label = orig_class
+
+        target = np.array([np.eye(self._wbmodel._nb_classes)[target_label]])
+
+        # Hard coding batch_size=1
+        batch_size = 1
+
+        # Example: for MNIST (1, 28, 28, 1), for tabular (1, no of columns)
+        shape = input_X.shape
+
+        attack = AEADEN(self._wbmodel, shape,
+                        mode=arg_mode, AE=AE_model, batch_size=batch_size,
+                        kappa=arg_kappa, init_learning_rate=1e-2,
+                        binary_search_steps=arg_b, max_iterations=arg_max_iter,
+                        initial_const=arg_init_const, beta=arg_beta, gamma=arg_gamma)
+
+        adv_X = attack.attack(input_X, target)
+
+        adv_prob, adv_class, adv_prob_str = self._wbmodel.predict_long(adv_X)
+
+        delta_X = input_X - adv_X
+
+        _, delta_class, delta_prob_str = self._wbmodel.predict_long(delta_X)
+
+        INFO = "[INFO]kappa:{}, Orig class:{}, Perturbed class:{}, Delta class: {}, Orig prob:{}, Perturbed prob:{}, Delta prob:{}".format(
+            arg_kappa, orig_class, adv_class, delta_class, orig_prob_str, adv_prob_str, delta_prob_str)
+
+        return (adv_X, delta_X, INFO)