aequitas-fairlib 2.8.2
A library for detecting and mitigating bias in machine learning models, with a focus on interoperability with scikit-learn, Pandas, and PyTorch.
License: Apache 2.0
Requires Python: <4.0.0,>=3.10.0

<p align="center"><img src="assets/logo.svg"></p>
<p align="center">
    <img src="https://img.shields.io/badge/fairness-8A2BE2">
    <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3670A0?style=flate&logo=python&logoColor=ffdd54"></a>   
    <a href="https://pytorch.org/"><img src="https://img.shields.io/badge/PyTorch-EE4C2C?style=flate&logo=pytorch&logoColor=white"></a>
    <a href="https://pandas.pydata.org/"><img src="https://img.shields.io/badge/-Pandas-150458?&logo=pandas"></a>
    <a href="https://jupyter.org/"><img src="https://img.shields.io/badge/Jupyter%20Notebook-F37626?style=flate&logo=jupyter&logoColor=white"></a>
    <a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits"></a>
</p>


# FairLib - Python Library for Fairness Metrics and Processing

This library provides a set of tools for measuring and improving fairness in machine learning models, covering a variety of fairness metrics, pre-processing, in-processing, and post-processing techniques.

[Complete Workflow Example Notebook](examples/demo_core_lib.ipynb)

## Library functionality
The library will provide some fairness metrics to perform various analyses. Plus a number of pre-processing, in-processing and post-processing algorithms.

### Fairness Metrics
- Statistical Parity Difference - [Example Notebook](examples/demo_statistical_parity_difference.ipynb)
- Disparate Impact - [Example Notebook](examples/demo_disparate_impact.ipynb)
- Equal Opportunity Difference - [Example Notebook](examples/demo_equality_of_opportunity.ipynb)

### Pre-Processing Techniques
- Disparate Impact Remover - [Example Notebook](examples/demo_disparate_impact_remover.ipynb)
- LFR (Learning Fair Representations) - [Example Notebook](examples/demo_lfr.ipynb)
- Reweighing - [Example Notebook](examples/demo_reweighing.ipynb)

### In-Processing Techniques
- FaUCI - [Example Notebook](examples/demo_fauci_TO_DELETE.ipynb)
- Adversarial Debiasing - [Example Notebook](examples/demo_adversarial_debiasing.ipynb)
- Prejudice Remover - [Example Notebook](examples/demo_prejudice_remover.ipynb)

## Project Structure

Overview of the project structure:

```bash
<root directory>
├── fairlib/               # Main package for the project
│   ├── __init__.py        # Package marker
│   ├── metrics/           # Fairness metrics implementations
│   ├── preprocessing/     # Pre-processing techniques for fairness
│   └── inprocessing/      # In-processing debiasing algorithms
├── tests/                 # Unit tests for the library
│   ├── metrics/           # Unit tests for fairness metrics
│   ├── preprocessing/     # Unit tests for pre-processing methods
│   └── inprocessing/      # Unit tests for in-processing techniques
├── examples/             # Jupyter notebooks with examples
├── .github/               # GitHub workflows for CI/CD
│   └── workflows/
│       ├── test.yml       # Run tests on multiple Python versions
│       └── deploy.yml     # Deploy to PyPI if tests succeed
├── pyproject.toml         # Project configuration file managed by Poetry
├── LICENSE                # License file (Apache 2.0 by default)
├── README.md              # Project documentation (this file)
├── renovate.json          # Configuration of Renovate bot, for automatic dependency updates
├── requirements.txt       # Only declares a dependency on Poetry. DO NOT EDIT THIS FILE
└── release.config.js      # Script to release on PyPi, and GitHub via semantic-release
```

### Restore dev dependencies

1. Install Poetry if you don't have it yet
```bash
pip install -r requirements.txt
```

2. Install the project's dependencies
```bash
poetry install
```

### Run unit tests
```bash
poetry run poe test
```

> Tests are automatically run in CI, on all pushes on all branches.
> There, tests are executed on multiple OS (Win, Mac, Ubuntu) and on multiple Python versions.