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.

Trusted-AI, updated 🕥 2023-03-18 21:18:24

AI Fairness 360 (AIF360)

Continuous Integration Documentation PyPI version CRAN_Status_Badge

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

The AI Fairness 360 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 including rich subgroup fairness
  • Comprehensive set of sample distortion metrics
  • Generalized Entropy Index (Speicher et al., 2018)
  • Differential Fairness and Bias Amplification (Foulds et al., 2018)
  • Bias Scan with Multi-Dimensional Subset Scan (Zhang, Neill, 2017)

Setup

R

r install.packages("aif360")

For more details regarding the R setup, please refer to instructions here.

Python

Supported Python Configurations:

| OS | Python version | | ------- | -------------- | | macOS | 3.7 – 3.10 | | Ubuntu | 3.7 – 3.10 | | Windows | 3.7 – 3.10 |

(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. Miniconda is sufficient (see the difference between Anaconda and Miniconda if you are curious) if you do not already have conda installed.

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

bash conda create --name aif360 python=3.7 conda activate aif360

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

bash (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 pip

To install the latest stable version from PyPI, run:

bash pip install aif360

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, Reductions, notebooks, tests, docs, all

If you encounter any errors, try the Troubleshooting steps.

Manual installation

Clone the latest version of this repository:

bash git clone https://github.com/Trusted-AI/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:

bash pip install --editable '.[all]'

Run the Examples

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 -e '.[notebooks]'

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

See the Install TensorFlow with pip page for detailed instructions.

Note: we require 'tensorflow >= 1.13.1'.

Once tensorflow is installed, try re-running:

bash pip install 'aif360[AdversarialDebiasing]'

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:

sh xcode-select --install

On Windows, you may need to download the Microsoft C++ Build Tools for Visual Studio 2019. See the CVXPY Install page for up-to-date instructions.

Then, try reinstalling via:

bash pip install 'aif360[OptimPreproc]'

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)

Contributing

The development fork for Rich Subgroup Fairness (inprocessing/gerryfair_classifier.py) is here. Contributions are welcome and a list of potential contributions from the authors can be found here.

Issues

added demv preprocessing algorithm

opened on 2023-02-13 14:28:24 by giordanoDaloisio

We included an implementation of the Debiaser for Multiple Variables algorithm from the paper

Debiaser for Multiple Variables to enhance fairness in classification tasks G d’Aloisio, A D’Angelo, A Di Marco, G Stilo Information Processing & Management 60 (2), 103226

We included the implementation of the algorithm and a notebook showing an example usage

Signed-off-by: Giordano d'Aloisio [email protected]

Equal opportunity fairness notion added

opened on 2023-02-08 21:10:38 by minasmz

Equal opportunity is added according to the definition in "Mitigating Unwanted Biases with Adversarial Learning".

Also, we are able to save and restore trained model in this implementation

Signed-off-by: Mina Samizadeh mina.smz2016@gmail.com

equal_opportunity fairness notion is added

opened on 2023-02-08 20:30:40 by minasmz

"equal_opportunity" fairness notion is added as described in the "Mitigating Unwanted Biases with Adversarial Learning" paper. In this case, the adversary is only trained on positive (label=1) data points.

Also, you are able to save and restore the trained model in this new code.

Signed-off-by: Mina Samizadeh mina.smz2016@gmail.com

Between group metrics for Equal_opportunity_difference and average_odds_difference

opened on 2023-02-01 23:08:50 by justinbroce

I see that for Generalized entropy index (GOI),there is a metric that calculates GOI between combinations of all groups for protected attributes. As seen in: between_all_groups_generalized_entropy_index()

I'm working on a binary classification research project that uses a dataset that has 4 different races as protected attributes. We want to calculate fairness metrics for all protected attributes in some way. I was wondering what people think about calculating Equal_opportunity_difference and odds difference on the combination of groups. Would anyone be interested in between_all_group functions for equality of odds, and equality of opportunities.

Thanks

Post processing bias mitigation methods with Multi class classification scenario

opened on 2023-01-30 07:25:23 by pradeepdev-1995

How to use the Post processing bias mitigation methods such as Reject Option Classification ,Calibrated Equalized Odds post processing,Equalized Odds post processing with multi-class classification dataset? In the documentation, it says that the fit method requires BinaryLabelDataset datasets as arguments.

Args: dataset_true (BinaryLabelDataset): Dataset containing true `labels`. dataset_pred (BinaryLabelDataset): Dataset containing predicted `scores`. So how can I pass a MulticlassLabelDataset object to these methods?

PrejudiceRemover and MetaFairClassifier inprocess bias mitigation algorithms with Multiclass classification

opened on 2023-01-30 06:19:02 by pradeepdev-1995

How to use PrejudiceRemover and MetaFairClassifier in-process bias mitigation algorithm with a multiclass classification dataset? Is it possible or does it only accepts BinaryLabelDataset?

Releases

v0.5.0 2022-09-03 03:17:54

AIF360 v0.5.0 Release Notes

Highlights

  • New algorithms:
  • FairAdapt
  • New metrics:
  • MDSS
  • class_imbalance, kl_divergence, conditional_demographic_disparity
  • intersection and one_vs_rest meta-metrics
  • sklearn-compatible ports:
  • differential fairness metrics
  • MEPS, COMPAS violent
  • RejectOptionClassification, LearnedFairRepresentations

New Features/Improvements

  • Multidimensional subset scanning (MDSS) for bias in classifiers by @Viktour19 in https://github.com/Trusted-AI/AIF360/pull/238
  • Update component.yaml to kfp v2 sdk by @yhwang in https://github.com/Trusted-AI/AIF360/pull/259
  • Fairadapt inclusion in AIF360 by @dplecko in https://github.com/Trusted-AI/AIF360/pull/257
  • Added a tutorial for advertising data by @barvek in https://github.com/Trusted-AI/AIF360/pull/310
  • More sklearn-compatible algorithms by @hoffmansc in https://github.com/Trusted-AI/AIF360/pull/318
  • Dataset Improvements by @hoffmansc in https://github.com/Trusted-AI/AIF360/pull/278
  • array of sample-wise protected attributes may now be passed in prot_attr instead of an index label
  • Method of the month (July) by @hoffmansc in https://github.com/Trusted-AI/AIF360/pull/324
  • sklearn-compat additions by @mnagired in https://github.com/Trusted-AI/AIF360/pull/322
  • add predict_proba to RejectOptionClassifier
  • More sklearn-compatible metrics by @hoffmansc in https://github.com/Trusted-AI/AIF360/pull/290
  • smoothed_edf, df_bias_amplification
  • class_imbalance, kl_divergence, conditional_demographic_disparity
  • intersection, one_vs_rest

Backwards-Incompatible Changes

  • Add detectors api by @Adebayo-Oshingbesan in https://github.com/Trusted-AI/AIF360/pull/305
  • version of bias_scan in aif360.metrics to be deprecated next release

Fixes

  • Fixed computation of coefficient of variation in classification_metrics by @plankington in https://github.com/Trusted-AI/AIF360/pull/288
  • Fix exponential gradient reduction without protected attribute (#267) by @jdnklau in https://github.com/Trusted-AI/AIF360/pull/268
  • Remove caches due to excessive memory use by @Adebayo-Oshingbesan in https://github.com/Trusted-AI/AIF360/pull/317
  • fix rpy2 crash bug by @hoffmansc in https://github.com/Trusted-AI/AIF360/pull/313
  • Fix pipelining bug in fairlearn algorithms by @hoffmansc in https://github.com/Trusted-AI/AIF360/pull/323
  • Optional tempeh, conditional imports by @DanielRyszkaIBM in https://github.com/Trusted-AI/AIF360/pull/338
  • Restricting AdversarialDebiasing's trainable variables to current scope by @mfeffer in https://github.com/Trusted-AI/AIF360/pull/255
  • Increasing max_iter to 1000 for LogisticRegression used in PrejudiceRemover by @mfeffer in https://github.com/Trusted-AI/AIF360/pull/254

New Contributors

  • @Viktour19 made their first contribution in https://github.com/Trusted-AI/AIF360/pull/238
  • @jdnklau made their first contribution in https://github.com/Trusted-AI/AIF360/pull/268
  • @yhwang made their first contribution in https://github.com/Trusted-AI/AIF360/pull/259
  • @dplecko made their first contribution in https://github.com/Trusted-AI/AIF360/pull/257
  • @plankington made their first contribution in https://github.com/Trusted-AI/AIF360/pull/288
  • @Adebayo-Oshingbesan made their first contribution in https://github.com/Trusted-AI/AIF360/pull/305
  • @barvek made their first contribution in https://github.com/Trusted-AI/AIF360/pull/310
  • @milevavantuyl made their first contribution in https://github.com/Trusted-AI/AIF360/pull/309
  • @josue-rodriguez made their first contribution in https://github.com/Trusted-AI/AIF360/pull/315
  • @DanielRyszkaIBM made their first contribution in https://github.com/Trusted-AI/AIF360/pull/338
  • @mnagired made their first contribution in https://github.com/Trusted-AI/AIF360/pull/322
  • @mfeffer made their first contribution in https://github.com/Trusted-AI/AIF360/pull/255

Full Changelog: https://github.com/Trusted-AI/AIF360/compare/v0.4.0...v0.5.0

v0.4.0 2021-03-04 17:33:12

AIF360 v0.4.0 Release Notes

This is a major release containing a number of new features, improvements, and bugfixes.

Highlights

  • TensorFlow 2, Python 3.8 now supported
  • New algorithms:
  • Exponentiated Gradient Reduction
  • Grid Search Reduction
  • New dataset:
  • Law school GPA

New Features/Improvements

  • Python 3.8 and TensorFlow 2 (via compat.v1) support added (#230)
  • Algorithms from fairlearn added (#215):
  • Exponentiated Gradient Reduction and Grid Search Reduction
  • Support for regression datasets
  • Law school GPA dataset added
  • MetaFairClassifier code cleaned and sped up (#196)
  • removed numba dependency (#187)
  • maxiter and maxfun arguments in LFR fit() (#184)

Backwards-Incompatible Changes

  • Removed support for Python 3.5

Fixes

  • Fix bug where scores in a single-row dataset was getting squeezed (#193)
  • Typo in consistency_score documentation (#195)
  • Lime notebook license issue (#191)

New Contributors

@baba-mpe, @SSaishruthi, @leenamurgai, @synapticarbors, @sohiniu, @yangky11

v0.3.0 2020-06-02 22:24:37

AIF360 v0.3.0 Release Notes

This is a major release containing a number of new features, improvements, and bugfixes.

Highlights

New Features/Improvements

  • Optional dependencies may now be installed using the setuptools "extras" option: e.g., pip install 'aif360[LFR,AdversarialDebiasing]' or pip install 'aif360[all]'
  • Added support for integrations with MLOps (Kubeflow and NiFi) and examples
  • Added scores output to AdversarialDebiasing.predict() (#139)
  • Added a subset() method to StructuredDataset (#140)
  • Added new MulticlassLabelDataset to support basic multiclass problems (#165)

  • scikit-learn compatibility (#134)

  • EXPERIMENTAL: incomplete, contributions welcome
  • 4 datasets (Adult, German, Bank, Compas) in DataFrame format with protected attributes in the index
    • Automatically downloads from openml.org
  • 6 group fairness metrics as functions (statistical_parity_difference, disparate_impact_ratio, equal_opportunity_difference, average_odds_difference, average_odds_error, between_group_generalized_entropy_error)
  • 2 individual fairness metrics as functions (generalized_entropy_index and its variants, consistency_score)
  • 5 additional metrics as functions (specificity_score, base_rate, selection_rate, generalized_fpr, generalized_fnr)
  • make_scorer function to wrap metrics for use in sklearn cross-validation functions (#174, #178)
  • 3 algorithms (Reweighing, AdversarialDebiasing, CalibratedEqualizedOdds)

Fixes

  • Fixed deprecation warning/NotImplementedError in StandardDataset (#115)
  • Fixed age threshold in GermanDataset (#129 and #137)
  • Corrected privileged/unprivileged attribute values for COMPAS dataset in some demos (#138)
  • Fixed base rate computation in EqOddsPostprocessing (#170)
  • Improved warning messages when missing optional packages (#170)
  • Multiple documentation fixes (#114, #124, #153, #155, #157, #158, #159, #170)

New Contributors

@autoih, @romeokienzler, @jimbudarz, @stephanNorsten, @sethneel, @imolloy, @guillemarsan, @gdequeiroz, @chajath, @bhavyaghai, @Tomcli, @swapna-somineni, @chkoar, @motapaolla

v0.3.0rc0 2020-04-03 16:16:22

AIF360 v0.3.0rc0 Release Notes

This is a major release containing a number of new features, improvements, and bugfixes.

Highlights

New Features/Improvements

  • Optional dependencies may now be installed using the setuptools "extras" option: e.g., pip install 'aif360[LFR,AdversarialDebiasing]' or pip install 'aif360[all]'
  • Added support for integrations with MLOps (Kubeflow and NiFi) and examples
  • Added scores output to AdversarialDebiasing.predict() (#139)
  • Added a subset() method to StructuredDataset (#140)

  • scikit-learn compatibility (#134)

  • EXPERIMENTAL: incomplete, contributions welcome
  • 4 datasets (Adult, German, Bank, Compas) in DataFrame format with protected attributes in the index
    • Automatically downloads from openml.org
  • 6 group fairness metrics as functions (statistical_parity_difference, disparate_impact_ratio, equal_opportunity_difference, average_odds_difference, average_odds_error, between_group_generalized_entropy_error)
  • 2 individual fairness metrics as functions (generalized_entropy_index and its variants, consistency_score)
  • 5 additional metrics as functions (specificity_score, base_rate, selection_rate, generalized_fpr, generalized_fnr)
  • 3 algorithms (Reweighing, AdversarialDebiasing, CalibratedEqualizedOdds)

Fixes

  • Fixed deprecation warning/NotImplementedError in StandardDataset (#115)
  • Fixed age threshold in GermanDataset (#129 and #137)
  • Corrected privileged/unprivileged attribute values for COMPAS dataset in some demos (#138)
  • Multiple documentation fixes (#114, #124, #153, #155, #157, #158, #159)

New Contributors

@autoih, @romeokienzler, @jimbudarz, @stephanNorsten, @sethneel, @imolloy, @guillemarsan, @gdequeiroz, @chajath, @bhavyaghai, @Tomcli

v0.2.3 2020-03-09 19:56:31

AIF360 v0.2.3 Release Notes

Fixes

  • Fixed fit_predict arguments in RejectOptionClassification (#111)
  • Removed Orange3 from requirements (#113)

v0.2.2 2019-09-16 16:52:17

AIF360 v0.2.2 Release Notes

Fixes

  • Removed Gender Classification tutorial (see #101 for details and discussion)
  • Bug fix in Optimized Preprocessing to check for optimality correctly
Trusted-AI

This GitHub org hosts LF AI Foundation projects in the category of Trusted and Responsible AI.

GitHub Repository Homepage

ai fairness-ai fairness fairness-testing fairness-awareness-model bias-detection bias bias-correction bias-reduction bias-finder artificial-intelligence discrimination ibm-research-ai ibm-research machine-learning deep-learning codait trusted-ai r python