Metadata-Version: 2.1
Name: equal-odds
Version: 0.0.7
Summary: _PACKAGE UNDER CONSTRUCTION_
Home-page: https://github.com/AndreFCruz/equal-odds
Author: AndreFCruz
License: MIT
Keywords: ml,optimization,fairness
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: cvxpy
Requires-Dist: matplotlib
Requires-Dist: seaborn
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: folktables ; extra == 'dev'
Requires-Dist: tqdm ; extra == 'dev'
Provides-Extra: test
Requires-Dist: ipdb ; extra == 'test'
Requires-Dist: tqdm ; extra == 'test'
Requires-Dist: notebook ; extra == 'test'
Requires-Dist: folktables ; extra == 'test'
Requires-Dist: hyperparameter-tuning ; extra == 'test'
Requires-Dist: fairlearn ; extra == 'test'
Requires-Dist: lightgbm ; extra == 'test'
Requires-Dist: fairgbm ; extra == 'test'

# equal-odds

![PyPI publishing status](https://github.com/AndreFCruz/equal-odds/actions/workflows/python-publish.yml/badge.svg)
![PyPI version](https://badgen.net/pypi/v/equal-odds)
![OSI license](https://badgen.net/pypi/license/equal-odds)
![Python compatibility](https://badgen.net/pypi/python/equal-odds)
<!-- ![PyPI version](https://img.shields.io/pypi/v/equal-odds) -->
<!-- ![OSI license](https://img.shields.io/pypi/l/equal-odds) -->
<!-- ![Compatible python versions](https://img.shields.io/pypi/pyversions/equal-odds) -->

Fast postprocessing of any score-based predictor to meet fairness criteria.

The `equal-odds` package can achieve strict or relaxed fairness constraint fulfillment, 
which can be useful to compare ML models at equal fairness levels.


## Installing

Install package from [PyPI](https://pypi.org/project/equal-odds/):
```
pip install equal-odds
```

Or, for development, you can clone the repo and install from local sources:
```
git clone https://github.com/AndreFCruz/equal-odds.git
pip install ./equal-odds
```


## Getting started

```py
# Given any trained model that outputs real-valued scores
fair_clf = RelaxedEqualOdds(
    predictor=lambda X: model.predict_proba(X)[:, -1],   # for sklearn API
    # predictor=model,  # use this for a callable model
    tolerance=0.05,     # fairness constraint tolerance
)

# Fit the fairness adjustment on some data
# This will find the optimal _fair classifier_
fair_clf.fit(X=X, y=y, group=group)

# Now you can use `fair_clf` as any other classifier
# You have to provide group information to compute fair predictions
y_pred_test = fair_clf(X=X_test, group=group_test)
```


## How it works

Given a callable score-based predictor (i.e., `y_pred = predictor(X)`), and some `(X, Y, S)` data to fit, `RelaxedEqualOdds` will:
1. Compute group-specific ROC curves and their convex hulls;
2. Compute the `r`-relaxed optimal solution for the chosen fairness criterion (using [cvxpy](https://www.cvxpy.org));
3. Find the set of group-specific binary classifiers that match the optimal solution found.
    - each group-specific classifier is made up of (possibly randomized) group-specific thresholds over the given predictor;
    - if a group's ROC point is in the interior of its ROC curve, partial randomization of its predictions may be necessary.


## Implementation road-map

We welcome community contributions for [cvxpy](https://www.cvxpy.org) implementations of other fairness constraints.

Currently implemented fairness constraints:
- [x] equality of odds [(Hardt et al., 2016)](https://proceedings.neurips.cc/paper/2016/file/9d2682367c3935defcb1f9e247a97c0d-Paper.pdf);
  - i.e., equal group-specific TPR and FPR;
<!--
- [ ] equal opportunity;
  - i.e., equal group-specific TPR;
- [ ] demographic parity;
  - i.e., equal group-specific predicted prevalence;
-->
