Version bump -> 0.3.0rc0 (#148)

* fixed multilabel bug in standarize_dataset

* fix docs build issue

* update copyright

* cleaned up requirements

* added differential fairness to README

* notebook -> jupyter

* make version rc

LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) IBM Corporation 2018
+Copyright (C) IBM Corporation 2018-2020
 
                                  Apache License
                            Version 2.0, January 2004

README.md

@@ -1,4 +1,4 @@
-# AI Fairness 360 (AIF360 v0.2.2)
+# AI Fairness 360 (AIF360)
 
 [![Build Status](https://travis-ci.org/IBM/AIF360.svg?branch=master)](https://travis-ci.org/IBM/AIF360)
 [![Documentation](https://readthedocs.org/projects/aif360/badge/?version=latest)](http://aif360.readthedocs.io/en/latest/?badge=latest)
@@ -51,6 +51,7 @@ Get in touch with us on [Slack](https://aif360.slack.com) (invitation
 * Comprehensive set of group fairness metrics derived from selection rates and error rates including rich subgroup fairness
 * Comprehensive set of sample distortion metrics
 * Generalized Entropy Index ([Speicher et al., 2018](https://doi.org/10.1145/3219819.3220046))
+* Differential Fairness and Bias Amplification ([Foulds et al., 2018](https://arxiv.org/pdf/1807.08362))
 
 
 ## Setup
@@ -63,11 +64,6 @@ Supported Configurations:
 | Ubuntu  | 3.5, 3.6, 3.7  |
 | Windows | 3.5, 3.6, 3.7  |
 
-NOTE: Python 2.7 support has been **deprecated** in this version. This message
-will be removed in the next release.
-
-See the [Troubleshooting](#troubleshooting) section if you have issues.
-
 ### (Optional) Create a virtual environment
 
 AIF360 requires specific versions of many Python packages which may conflict
@@ -78,16 +74,15 @@ installing AIF360, try this first.
 #### Conda
 
 Conda is recommended for all configurations though Virtualenv is generally
-interchangeable for our purposes ([CVXPY](#cvxpy) may require conda in some
-cases). Miniconda is sufficient (see [the difference between Anaconda and
+interchangeable for our purposes. [Miniconda](https://conda.io/miniconda.html)
+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.
+if you are curious) if you do not already have conda installed.
 
-Then, to create a new Python 3.5 environment, run:
+Then, to create a new Python 3.6 environment, run:
 
 ```bash
-conda create --name aif360 python=3.5
+conda create --name aif360 python=3.6
 conda activate aif360
 ```
 
@@ -102,18 +97,34 @@ The prompt will return to `$ `.
 Note: Older versions of conda may use `source activate aif360` and `source
 deactivate` (`activate aif360` and `deactivate` on Windows).
 
-### Install with minimal dependencies
+### Install with `pip`
 
 To install the latest stable version from PyPI, run:
 
 ```bash
 pip install aif360
 ```
 
-Some algorithms require additional dependencies not included in the minimal
-installation. To use these, we recommend a full installation.
+Note: Some algorithms require additional dependencies (although the metrics will
+all work out-of-the-box). To install with certain algorithm dependencies
+included, run, e.g.:
+
+```bash
+pip install 'aif360[LFR,OptimPreproc]'
+```
+
+or, for complete functionality, run:
+
+```bash
+pip install 'aif360[all]'
+```
+
+The options for available extras are: `OptimPreproc, LFR, AdversarialDebiasing,
+DisparateImpactRemover, LIME, ART, notebooks, tests, docs, all`
+
+If you encounter any errors, try the [Troubleshooting](#troubleshooting) steps.
 
-### Full installation
+### Manual installation
 
 Clone the latest version of this repository:
 
@@ -128,31 +139,19 @@ their respective folders as described in
 Then, navigate to the root directory of the project and run:
 
 ```bash
-pip install -e .
+pip install --editable '.[all]'
 ```
 
 #### Run the Examples
 
-To run the example notebooks, complete the full installation steps above. Then,
-install the additional requirements as follows:
+To run the example notebooks, complete the manual installation steps above.
+Then, if you did not use the `[all]` option, install the additional requirements
+as follows:
 
 ```bash
-pip install -r requirements.txt
+pip install -e '.[notebooks]'
 ```
 
-Then, follow the [Getting Started](https://pytorch.org) instructions from
-PyTorch to download and install the latest version for your machine. With conda,
-this is simple:
-
-```bash
-# LINUX/WINDOWS
-conda install pytorch-cpu torchvision-cpu -c pytorch
-# MACOS
-conda install pytorch torchvision -c pytorch
-```
-
-For CUDA support or alternative installation, see the instructions.
-
 Finally, if you did not already, download the datasets as described in
 [aif360/data/README.md](aif360/data/README.md).
 
@@ -163,17 +162,15 @@ issue here and try the solutions.
 
 #### TensorFlow
 
-In some cases, the URL is required for installation:
+See the [Install TensorFlow with pip](https://www.tensorflow.org/install/pip?lang=python3#older-versions-of-tensorflow)
+page for detailed instructions.
 
-```bat
-# WINDOWS
-pip install --upgrade https://storage.googleapis.com/tensorflow/windows/cpu/tensorflow-1.14.0-cp36-cp36m-win_amd64.whl
+Note: we require `'tensorflow >= 1.13.1, < 2'`.
 
-# MACOS
-pip install --upgrade https://storage.googleapis.com/tensorflow/mac/cpu/tensorflow-1.14.0-py3-none-any.whl
+Once tensorflow is installed, try re-running:
 
-# LINUX
-pip install --upgrade https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-1.14.0-cp36-cp36m-linux_x86_64.whl
+```bash
+pip install 'aif360[AdversarialDebiasing]'
 ```
 
 TensorFlow is only required for use with the
@@ -188,24 +185,17 @@ never have previously:
 xcode-select --install
 ```
 
-And then, re-run:
+On Windows, you may need to download the [Microsoft C++ Build Tools for Visual
+Studio 2019](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=16).
+See the [CVXPY Install](https://www.cvxpy.org/install/index.html#mac-os-x-windows-and-linux)
+page for up-to-date instructions.
 
-```sh
-pip install -r requirements.txt
-```
-
-On Windows, you may need to download the appropriate [Visual Studio C++
-compiler for Python](https://wiki.python.org/moin/WindowsCompilers#Microsoft_Visual_C.2B-.2B-_14.0_standalone:_Build_Tools_for_Visual_Studio_2017_.28x86.2C_x64.2C_ARM.2C_ARM64.29). Then,
-re-run:
+Then, try reinstalling via:
 
-```bat
-pip install -r requirements.txt
+```bash
+pip install 'aif360[OptimPreproc]'
 ```
 
-See the [CVXPY Installation
-Instructions](https://www.cvxpy.org/install/index.html#windows)
-for an alternate installation procedure using conda.
-
 CVXPY is only required for use with the
 `aif360.algorithms.preprocessing.OptimPreproc` class.
 

aif360/sklearn/datasets/utils.py

@@ -2,6 +2,7 @@
 import warnings
 
 import numpy as np
+import pandas as pd
 from pandas.core.dtypes.common import is_list_like
 
 
@@ -104,7 +105,7 @@ def standardize_dataset(df, prot_attr, target, sample_weight=None, usecols=[],
     target = check_already_dropped(target, nonnumeric, 'target')
     if len(target) == 0:
         raise ValueError("At least one target must be present.")
-    y = df.pop(target if len(target) > 1 else target[0])  # maybe return Series
+    y = pd.concat([df.pop(t) for t in target], axis=1).squeeze()  # maybe Series
 
     # Column-wise drops
     orig_cols = df.columns

docs/source/conf.py

@@ -57,10 +57,10 @@
 # generate autosummary even if no references
 autosummary_generate = True
 
-autodoc_default_options = {
-    'members': True,
-    # 'inherited-members': True
-}
+autodoc_default_flags = [
+    'members',
+    # 'inherited-members'
+]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -73,7 +73,7 @@
 
 # General information about the project.
 project = u'aif360'
-copyright = u'2018 - 2019, IBM Corporation'
+copyright = u'2018 - 2020, IBM Corporation'
 author = u'aif360 developers'
 
 # The version info for the project you're documenting, acts as replacement for

requirements.txt

@@ -1,21 +1,14 @@
-nbformat
-nbconvert
-jupyter_client
-ipykernel
-ipython
-ipywidgets
-tqdm
-numpy>=1.16
-matplotlib
-pandas>=0.24
-pytest>=3.5.0
-scipy>=1.2.0
-scikit-learn
-cvxpy>=1.0
-scs==2.1.0
-numba==0.42.0
-tensorflow>=1.13.1,<2
-networkx==1.11
-BlackBoxAuditing
+# algorithms
+numba>=0.42.0
 lime
 adversarial-robustness-toolbox>=1.0.0
+BlackBoxAuditing
+tensorflow>=1.13.1,<2
+cvxpy>=1.0
+
+# notebooks
+jupyter
+tqdm
+
+# tests
+pytest>=3.5.0

setup.py

@@ -1,4 +1,5 @@
 from setuptools import setup, find_packages
+from functools import reduce
 
 long_description = """The AI Fairness 360 toolkit is an open-source library to help detect and mitigate bias in machine
 learning models. The AI Fairness 360 Python package includes a comprehensive set of metrics for datasets and models to
@@ -7,11 +8,24 @@
 We have developed the package with extensibility in mind. This library is still in development. We encourage the
 contribution of your datasets, metrics, explainers, and debiasing algorithms."""
 
-version = '0.2.2'
+version = '0.3.0rc0'
 
 with open("aif360/version.py", 'w') as f:
     f.write('# generated by setup.py\nversion = "{}"\n'.format(version))
 
+extras = {
+    'OptimPreproc': ['cvxpy>=1.0'],
+    'LFR': ['numba>=0.42.0'],
+    'AdversarialDebiasing': ['tensorflow>=1.13.1,<2'],
+    'DisparateImpactRemover': ['BlackBoxAuditing'],
+    'LIME': ['lime'],
+    'ART': ['adversarial-robustness-toolbox>=1.0.0'],
+    'notebooks': ['jupyter', 'tqdm']
+}
+extras['tests'] = reduce(lambda l1, l2: l1+l2, extras.values(), ['pytest>=3.5'])
+extras['docs'] = ['sphinx', 'sphinx_rtd_theme']
+extras['all'] = list(reduce(lambda s, l: s.union(l), extras.values(), set()))
+
 setup(name='aif360',
       version=version,
       description='IBM AI Fairness 360',
@@ -22,14 +36,15 @@
       long_description_content_type='text/markdown',
       license='Apache License 2.0',
       packages=[pkg for pkg in find_packages() if pkg.startswith('aif360')],
-      # python_requires='>=3.5, <3.7',
+      python_requires='>=3.5',
       install_requires=[
           'numpy>=1.16',
-          'scipy',
+          'scipy>=1.2.0',
           'pandas>=0.24.0',
-          'scikit-learn',
-          'matplotlib'
+          'scikit-learn>=0.21',
+          'matplotlib',
       ],
+      extras_require=extras,
       package_data={'aif360': ['data/*', 'data/*/*', 'data/*/*/*']},
       include_package_data=True,
       zip_safe=False)

tests/sklearn/test_datasets.py

@@ -28,6 +28,14 @@ def test_standardize_dataset_basic():
     assert X.index.equals(y.index)
     assert X.shape == (3, 3)
 
+def test_multilabel_basic():
+    """Tests returning a multilabel target on a toy example."""
+    multilabel = basic(target=['X2', 'y'])
+    assert isinstance(multilabel.y, pd.DataFrame)
+    assert isinstance(multilabel.X, pd.DataFrame)
+    assert multilabel.y.shape == (3, 2)
+    assert multilabel.X.shape == (3, 2)
+
 def test_sample_weight_basic():
     """Tests returning sample_weight on a toy example."""
     with_weights = basic(sample_weight='X2')