Getting Started
Welcome to AI Fairness 360!
AIF360 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. This document will provide an overview of its features and conventions for users of the toolkit.
Definitions of relevant terms may be found in the Glossary page.
Installation
To install the latest stable version from PyPI, run:
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.:
pip install 'aif360[LFR,OptimPreproc]'
or, for complete functionality, run:
pip install 'aif360[all]'
It is recommended to install AIF360 in a virtual environment (e.g., conda).
AIF360 is also available as an R package. To install aif360-r from CRAN:
install.packages("aif360")
For more details, see the AIF360-r README.
scikit-learn API
AIF360 has two interfaces for handling data formats, a legacy interface and a scikit-learn-compatible one. The sklearn API is preferred going forward and all future development will be focused there. Note: there may be slight differences in results between the two versions due to the implementations but both are valid.
AIF360 contains four major classes of features: datasets, estimators, metrics, and detectors.
Datasets
Currently, AIF360 focuses on tabular data which are formatted as pandas
DataFrames
.
>>> from aif360.sklearn.datasets import fetch_compas
>>> fetch_compas().X.head()
sex age age_cat race juv_fel_count juv_misd_count juv_other_count priors_count c_charge_degree c_charge_desc
sex race
Male Other Male 69 Greater than 45 Other 0 0 0 0 F Aggravated Assault w/Firearm
African-American Male 34 25 - 45 African-American 0 0 0 0 F Felony Battery w/Prior Convict
African-American Male 24 Less than 25 African-American 0 0 1 4 F Possession of Cocaine
Other Male 44 25 - 45 Other 0 0 0 0 M Battery
Caucasian Male 41 25 - 45 Caucasian 0 0 0 14 F Possession Burglary Tools
Per-sample protected attributes are stored in the index of the DataFrame. If
multiple protected attributes are present, a single attribute or subset may be
selected for use in a specific algorithm/metric by using the relevant
prot_attr
argument.
In some cases, it is possible to use numpy arrays for features and protected
attributes separately by passing an array to prot_attr
such as in metrics.
However, since support for predict_params
in sklearn is sparse, prot_attr
is an __init__
argument which means handling fit
and predict
separately
is difficult.
Estimators
AIF360 estimators are machine learning models which mitigate unfair bias in some
way. They may also be referred to as algorithms. AIF360 estimators inherit
from scikit-learn Estimators
and are intended to work in conjunction with each
other. Note: while scikit-learn estimators can generally be used in an AIF360
pipeline, the reverse is not always true due to the data limitations explained
above. This is ongoing work to reduce friction between the libraries.
Algorithms are divided into three classes based on how they mitigate bias. For guidance on choosing an algorithm, see the Resources page.
Pre-processing
Pre-processors act on data and produce fair representations which are
subsequently used by another machine learning model. Under scikit-learn
conventions, these work like Transformers
.
>>> from aif360.sklearn.preprocessing import LearnedFairRepresentations
>>> Xt = LearnedFairRepresentations().fit_transform(X, y)
In some cases, AIF360 pre-processors necessarily break scikit-learn conventions,
e.g., Reweighing
and
FairAdapt
. This may cause difficulty when
using them within a Pipeline
. Typically, a MetaEstimator
may be used to
perform pre-processing and estimation in a single step. See relevant examples for
details.
In-processing
In-processors apply mitigation during model training in order to produce a fair
model. Under scikit-learn conventions, these are simply
Classifiers
/Regressors
.
>>> from aif360.sklearn.inprocessing import AdversarialDebiasing
>>> y_pred = AdversarialDebiasing().fit(X_train, y_train).predict(X_test)
Post-processing
Post-processors act on the outputs of a model (and possibly the inputs as well)
and produce new, fairer outputs. These types of models are classified as
MetaEstimators
in scikit-learn.
>>> from sklearn.linear_model import LogisticRegression
>>> from aif360.sklearn.postprocessing import RejectOptionClassifierCV, PostProcessingMeta
>>> y_pred = PostProcessingMeta(
... LogisticRegression(),
... RejectOptionClassifierCV('sex', scoring='disparate_impact')
... ).fit(X_train, y_train).predict(X_test)
Metrics
Fairness may be defined in many different ways according to different situations and stakeholders. It is typically defined as a notion of equality within the population. Fairness metrics measure the deviation from equality (bias) in data or model outputs. These can be divided into two classes of metrics according to the definition of fairness they measure: individual or group fairness.
Group fairness
Group fairness metrics compare statistical measures between different subpopulations of the data divided by protected attributes. Often these are aggregated into a single score, for example, by taking a difference or ratio between the unprivileged and privileged group for binary groups.
These functions are similar to scikit-learn metrics with additional arguments
for prot_attr
(index label of y_true
/y_pred
or explicit array) and
priv_group
(if binary groups are required).
>>> from aif360.sklearn.metrics import disparate_impact_ratio
>>> di = disparate_impact_ratio(y_true, y_pred, prot_attr='race' priv_group='White', pos_label=1)
Individual fairness
Individual fairness is most commonly defined as “similar individuals are treated
similarly” (Dwork, et al. 2011). These
functions therefore, require access to the features, X
, labels, y
, and a
distance function/matrix.
>>> from aif360.sklearn.metrics import consistency_score
>>> cons = consistency_score(X_test, y_pred)
Distributional fairness
A generalized entropy index, or inequality index, measures how unequally the benefits of a model are distributed amongst the population. A value of zero indicates equal benefit is given to every individual. It is similar to individual fairness but because GEI does not take into account individual similarity (i.e., “we’re all equal”) it may be thought of as a separate category, more related to utility measurement. See Mitigating Bias in Machine Learning, Chapter 5 for more details.
>>> from aif360.sklearn.metrics import generalized_entropy_error
>>> ent = generalized_entropy_error(y_true, y_pred)
Detectors
The goal of a bias detector is to identify subgroup(s) which are especially disadvantaged by a model or dataset.
>>> from aif360.sklearn.detectors import bias_scan
>>> subset, score = bias_scan(X, y_true, y_pred)
Future work
Other data modalities
AIF360 is currently best suited for tabular data tasks however any model used by humans could contain bias. In most cases, metrics can still be computed using only labels and protected attribute data but if you are interested in contributing an algorithm which does not fit within the scikit-learn interface style, please submit an issue on GitHub and let’s discuss!