A comprehensive set of fairness metrics for datasets and machine learning models, explanations for these metrics, and algorithms to mitigate bias in datasets and models.
Clone or download
hoffmansc fixes to instructions and requirements (#30)
* removes requirements3.txt
* also clarifies StandardDataset documentation
* adds data folders to .gitignore
* small fix to test_disparate_impact_remover
Latest commit 31df2ad Oct 12, 2018

README.md

AI Fairness 360 (AIF360 v0.1.1)

Build Status

The AI Fairness 360 toolkit is an open-source library to help detect and remove bias in machine learning models. The AI Fairness 360 Python package includes a comprehensive set of metrics for datasets and models to test for biases, explanations for these metrics, and algorithms to mitigate bias in datasets and models.

The AI Fairness 360 interactive experience provides a gentle introduction to the concepts and capabilities. The tutorials and other notebooks offer a deeper, data scientist-oriented introduction. The complete API is also available.

Being a comprehensive set of capabilities, it may be confusing to figure out which metrics and algorithms are most appropriate for a given use case. To help, we have created some guidance material 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 metrics, explainers, and debiasing algorithms.

Get in touch with us on Slack (invitation here)!

Supported bias mitigation algorithms

Supported fairness metrics

  • Comprehensive set of group fairness metrics derived from selection rates and error rates
  • Comprehensive set of sample distortion metrics
  • Generalized Entropy Index (Speicher et al., 2018)

Setup

Installation is easiest on a Unix-like system running Python 3.6 or Windows running Python 3.5. See the Troubleshooting section if you have issues with other configurations.

(Optional) Create a virtual environment

Virtualenv

AIF360 requires specific versions of many Python packages which may conflict with other projects on your system. Virtualenv creates an isolated virtual Python environment where these dependencies may be installed safely. If you have trouble installing AIF360, try this first.

mkdir ~/virtualenvs && cd ~/virtualenvs  # this can be wherever you like storing virtualenvs
virtualenv -p python3 aif360             # or substitute your preferred version of Python
source aif360/bin/activate

For Windows, this is a little different:

md C:\virtualenvs             # this can be wherever you like storing virtualenvs
cd C:\virtualenvs
virtualenv -p python3 aif360  # or substitute your preferred version of Python
aif360/Scripts/activate

The shell should now look like (aif360) $.

Also, upgrade pip to be safe:

(aif360)$ pip install --upgrade pip

To deactivate the environment, run

(aif360)$ deactivate

The prompt will return to $.

See the Virtualenv User Guide for more details.

Conda

Some users may prefer to use conda to manage environments. It can be installed with the Anaconda distribution by following these instructions. Then, to create a new Python 3.6 environment, run:

conda create --name aif360 python=3.6
conda activate aif360

and to deactivate, run

(aif360)$ conda deactivate

For simplicity, the following instructions will assume virtualenv but the same steps should work regardless of which you choose.

Install with minimal dependencies

Installation with pip

pip install aif360

This package supports Python 2.7, 3.5, and 3.6. However, for Python 2, the BlackBoxAuditing package must be installed manually.

Manual installation

Clone the latest version of this repository:

git clone https://github.com/IBM/AIF360

If you'd like to run the examples, download the datasets now and place them in their respective folders as described in aif360/data/README.md.

Then, navigate to the root directory of the project and run:

pip install .

Run the Examples

To run the example notebooks, install the additional requirements as follows:

pip install -r requirements.txt

Then, follow the Getting Started instructions from PyTorch to download and install the latest version for your machine.

Finally, if you did not already, download the datasets as described in aif360/data/README.md but place them in the appropriate sub-folder in ~/virtualenvs/aif360/lib/pythonX.X/site-packages/aif360/data/raw where pythonX.X is the version of python you are using.

Troubleshooting

If you encounter any errors during the installation process, look for your issue here and try the solutions.

Windows

TensorFlow

Note: TensorFlow 1.1.0 only supports Python 3.5 officially on Windows. You can get it from python.org.

Then, try:

pip install --upgrade https://storage.googleapis.com/tensorflow/windows/cpu/tensorflow-1.1.0-cp35-cp35m-win_amd64.whl

TensorFlow is only required for use with the aif360.algorithms.inprocessing.AdversarialDebiasing class.

CVXPY

You may need to download the appropriate Visual Studio C++ compiler for Python and rerun

pip install cvxpy==0.4.11

CVXPY is only required for use with the aif360.algorithms.preprocessing.OptimPreproc class.

Python 2

Some additional installation is required to use aif360.algorithms.preprocessing.DisparateImpactRemover with Python 2.7. In a directory of your choosing, run:

git clone https://github.com/algofairness/BlackBoxAuditing

In the root directory of BlackBoxAuditing, run:

echo -n $PWD/BlackBoxAuditing/weka.jar > python2_source/BlackBoxAuditing/model_factories/weka.path
echo "include python2_source/BlackBoxAuditing/model_factories/weka.path" >> MANIFEST.in
pip install --no-deps .

This will produce a minimal installation which satisfies our requirements.

Using AIF360

The examples directory contains a diverse collection of jupyter notebooks that use AI Fairness 360 in various ways. Both tutorials and demos illustrate working code using AIF360. Tutorials provide additional discussion that walks the user through the various steps of the notebook. See the details about tutorials and demos here

Citing AIF360

A technical description of AI Fairness 360 is available in this paper. Below is the bibtex entry for this paper.

@misc{aif360-oct-2018,
    title = "{AI Fairness} 360:  An Extensible Toolkit for Detecting, Understanding, and Mitigating Unwanted Algorithmic Bias",
    author = {Rachel K. E. Bellamy and Kuntal Dey and Michael Hind and
	Samuel C. Hoffman and Stephanie Houde and Kalapriya Kannan and
	Pranay Lohia and Jacquelyn Martino and Sameep Mehta and
	Aleksandra Mojsilovic and Seema Nagar and Karthikeyan Natesan Ramamurthy and
	John Richards and Diptikalyan Saha and Prasanna Sattigeri and
	Moninder Singh and Kush R. Varshney and Yunfeng Zhang},
    month = oct,	
    year = {2018},
    url = {https://arxiv.org/abs/1810.01943}
}

AIF360 Videos

  • Introductory video to AI Fairness 360 by Kush Varshney, September 20, 2018 (32 mins)