Note FairGBM has been accepted at ICLR 2023. Link to paper here.
FairGBM is an easy-to-use and lightweight fairness-aware ML algorithm with state-of-the-art performance on tabular datasets.
FairGBM builds upon the popular LightGBM algorithm and adds customizable constraints for group-wise fairness (e.g., equal opportunity, predictive equality, equalized odds) and other global goals (e.g., specific Recall or FPR prediction targets).
Table of contents:
FairGBM can be installed from PyPI:
pip install fairgbm
Or directly from GitHub:
git clone --recurse-submodules https://github.com/feedzai/fairgbm.git
pip install fairgbm/python-package/
Note Compatibility is only maintained with Linux OS.
If you don't have access to a Linux machine we advise using the free Google Colab service (example Colab notebook here).
We also provide a docker image that can be useful for non-linux platforms, run:
docker run -p 8888:8888 ndrcrz/fairgbm-minicondafor a jupyter notebook environment withfairgbminstalled.
Note Follow this link for more details on the Python package installation instructions.
We provide a Docker image with python and miniconda installed, ready to run the example fairgbm jupyter notebooks.
You can get a jupyter notebook with fairgbm up and running on your local machine with:
docker run -p 8888:8888 ndrcrz/fairgbm-miniconda
Although it is recommended to use the python package directly on your local x86-64 (non-arm) linux machine, using this docker image is an option for users on other platforms (docker image was tested on an M1 Mac).
The Dockerfile is available here.
Recommended Python notebook example here (Google Colab link here).
You can get FairGBM up and running in just a few lines of Python code:
from fairgbm import FairGBMClassifier
# Instantiate
fairgbm_clf = FairGBMClassifier(
constraint_type="FNR", # constraint on equal group-wise TPR (equal opportunity)
n_estimators=200, # core parameters from vanilla LightGBM
random_state=42, # ...
)
# Train using features (X), labels (Y), and sensitive attributes (S)
fairgbm_clf.fit(X, Y, constraint_group=S)
# NOTE: labels (Y) and sensitive attributes (S) must be in numeric format
# Predict
Y_test_pred = fairgbm_clf.predict_proba(X_test)[:, -1] # Compute continuous class probabilities (recommended)
# Y_test_pred = fairgbm_clf.predict(X_test) # Or compute discrete class predictionsFor Python examples see the notebooks folder.
A more in-depth explanation and other usage examples (with python package or compiled binary) can be found in the examples folder.
Note FairGBM is a research project, so its default hyperparameters (key-word arguments) will expectedly not be as robust as the default hyperparameters in
sklearnorlightgbmclassifiers. We earnestly recommend running hyperparameter-tuning to tune themultiplier_learning_ratehyperparameter as well as the remaining GBM hyperparameters (example here).
The following parameters can be used as key-word arguments for the FairGBMClassifier Python class.
| Name | Description | Default |
|---|---|---|
constraint_type |
The type of fairness (group-wise equality) constraint to use (if any). | FPR,FNR |
global_constraint_type |
The type of global equality constraint to use (if any). | None |
multiplier_learning_rate |
The learning rate for the gradient ascent step (w.r.t. Lagrange multipliers). | 0.1 |
constraint_fpr_tolerance |
The slack when fulfilling group-wise FPR constraints. | 0.01 |
constraint_fnr_tolerance |
The slack when fulfilling group-wise FNR constraints. | 0.01 |
global_target_fpr |
Target rate for the global FPR (inequality) constraint. | None |
global_target_fnr |
Target rate for the global FNR (inequality) constraint. | None |
constraint_stepwise_proxy |
Differentiable proxy for the step-wise function in group-wise constraints. | cross_entropy |
objective_stepwise_proxy |
Differentiable proxy for the step-wise function in global constraints. | cross_entropy |
stepwise_proxy_margin |
Intercept value for the proxy function: value at f(logodds=0.0) |
1.0 |
score_threshold |
Score threshold used when assessing group-wise FPR or FNR in training. | 0.5 |
global_score_threshold |
Score threshold used when assessing global FPR or FNR in training. | 0.5 |
init_multipliers |
The initial value of the Lagrange multipliers. | 0 for each constraint |
| ... | Any core LGBMClassifier parameter can be used with FairGBM as well. |
Please consult this list for a detailed
view of all vanilla LightGBM parameters (e.g., n_estimators, n_jobs, ...).
Note The
objectiveis the only core LightGBM parameter that cannot be changed when using FairGBM, as you must use the constrained loss functionobjective="constrained_cross_entropy". Using a standard non-constrained objective will fallback to using standard LightGBM.
In addition to the usual fit arguments, features X and labels Y, FairGBM takes in the sensitive attributes S
column for training.
Regarding the sensitive attributes column S:
- It should be in numeric format, and have each different protected group take a different integer value, starting at
0. - It is not restricted to binary sensitive attributes: you can use two or more different groups encoded in the same column;
- It is only required for training and not for computing predictions;
Here is an example pre-processing for the sensitive attributes on the UCI Adult dataset:
# Given X, Y, S
X, Y, S = load_dataset()
# The sensitive attributes S must be in numeric format
S = np.array([1 if val == "Female" else 0 for val in S])
# The labels Y must be binary and in numeric format: {0, 1}
Y = np.array([1 if val == ">50K" else 0 for val in Y])
# And the features X may be numeric or categorical, but make sure categorical columns are in the correct format
X: Union[pd.DataFrame, np.ndarray] # any array-like can be used
# Train FairGBM
fairgbm_clf.fit(X, Y, constraint_group=S)FairGBM enables you to train a GBM model to minimize a loss function (e.g., cross-entropy) subject to fairness constraints (e.g., equal opportunity).
Namely, you can target equality of performance metrics (FPR, FNR, or both) across instances from two or more different protected groups (see fairness constraints section). Optionally, you can simultaneously add global constraints on specific metrics (see global constraints section).
You can use FairGBM to equalize the following metrics across two or more protected groups:
- Equalize FNR (equivalent to equalizing TPR or Recall)
- also known as equal opportunity (Hardt et al., 2016)
- Equalize FPR (equivalent to equalizing TNR or Specificity)
- also known as predictive equality (Corbett-Davies et al., 2017)
- Equalize both FNR and FPR simultaneously
- also known as equalized odds (Hardt et al., 2016)
Example for equality of opportunity in college admissions: your likelihood of getting admitted to a certain college (predicted positive) given that you're a qualified candidate (label positive) should be the same regardless of your race (sensitive attribute).
You can also target specific FNR or FPR goals.
For example, in cases where high accuracy is trivially achieved (e.g., problems with high class imbalance),
you may want to maximize TPR with a constraint on FPR (e.g., "maximize TPR with at most 5% FPR").
You can set a constraint on global FPR โค 0.05 by using global_target_fpr=0.05 and
global_constraint_type="FPR".
You can simultaneously set constraints on group-wise metrics (fairness constraints) and constraints on global metrics.
FairGBM is a framework that enables constrained optimization of Gradient Boosting Machines (GBMs). This way, we can train a GBM model to minimize some loss function (usually the binary cross-entropy) subject to a set of constraints that should be met in the training dataset (e.g., equality of opportunity).
FairGBM applies the method of Lagrange multipliers, and uses iterative and interleaved steps of gradient descent (on the function space, by adding new trees to the GBM model) and gradient ascent (on the space of Lagrange multipliers, ฮ).
The main obstacle with enforcing fairness constraints in training is that these constraints are often non-differentiable. To side-step this issue, we use a differentiable proxy of the step-wise function. The following plot shows an example of hinge-based and cross-entropy-based proxies for the false positive value of a label negative instance.
For a more in-depth explanation of FairGBM please consult the paper.
For commercial uses of FairGBM please contact [email protected].
@inproceedings{cruz2023fairgbm,
author = {Cruz, Andr{\'{e}} F. and Bel{\'{e}}m, Catarina and Jesus, S{\'{e}}rgio and Bravo, Jo{\~{a}}o and Saleiro, Pedro and Bizarro, Pedro},
title={Fair{GBM}: Gradient Boosting with Fairness Constraints},
booktitle={The Eleventh International Conference on Learning Representations},
year={2023},
url={https://openreview.net/forum?id=x-mXzBgCX3a}
}
The paper is publicly available at this arXiv link.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent