Skip to content

Latest commit

 

History

History
243 lines (175 loc) · 8.89 KB

README.md

File metadata and controls

243 lines (175 loc) · 8.89 KB
Raw

AI Fairness 360 (AIF360 v0.2.2)

Build Status Documentation PyPI version

The AI Fairness 360 toolkit is an extensible open-source library containg techniques developed by the research community to help detect and mitigate bias in machine learning models throughout the AI application lifecycle. The AI Fairness 360 Python package includes

  1. a comprehensive set of metrics for datasets and models to test for biases,
  2. explanations for these metrics, and
  3. algorithms to mitigate bias in datasets and models. It is designed to translate algorithmic research from the lab into the actual practice of domains as wide-ranging as finance, human capital management, healthcare, and education. We invite you to use it and improve it.

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

Supported Configurations:

OS Python version
macOS 3.5, 3.6, 3.7
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 section if you have issues.

(Optional) Create a virtual environment

AIF360 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 AIF360, try this first.

Conda

Conda is recommended for all configurations though Virtualenv is generally interchangeable for our purposes (CVXPY may require conda in some cases). Miniconda is sufficient (see the difference between Anaconda and Miniconda if you are curious) and can be installed from here if you do not already have it.

Then, to create a new Python 3.5 environment, run:

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

The shell should now look like (aif360) $. To deactivate the environment, run:

(aif360)$ conda deactivate

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

To install the latest stable version from PyPI, run:

pip install aif360

Some algorithms require additional dependencies not included in the minimal installation. To use these, we recommend a full installation.

Full 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 -e .

Run the Examples

To run the example notebooks, complete the full installation steps above. Then, 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. With conda, this is simple:

# 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.

Troubleshooting

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

TensorFlow

In some cases, the URL is required for installation:

# WINDOWS
pip install --upgrade https://storage.googleapis.com/tensorflow/windows/cpu/tensorflow-1.14.0-cp36-cp36m-win_amd64.whl

# MACOS
pip install --upgrade https://storage.googleapis.com/tensorflow/mac/cpu/tensorflow-1.14.0-py3-none-any.whl

# LINUX
pip install --upgrade https://storage.googleapis.com/tensorflow/linux/cpu/tensorflow-1.14.0-cp36-cp36m-linux_x86_64.whl

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

CVXPY

On MacOS, you may first have to install the Xcode Command Line Tools if you never have previously:

xcode-select --install

And then, re-run:

pip install -r requirements.txt

On Windows, you may need to download the appropriate Visual Studio C++ compiler for Python. Then, re-run:

pip install -r requirements.txt

See the CVXPY Installation Instructions for an alternate installation procedure using conda.

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

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)