equipy 0.0.11a0.dev0
Equipy is a tool for fast, online fairness calibration
Keywords: fairness, wasserstein

.. -*- mode: rst -*-

|Build yes|

.. |Build yes| image:: https://img.shields.io/badge/build-passing-<COLOR>.svg
   :target: https://github.com/equilibration/equipy/actions/workflows/build-package.yml


**EquiPy** is a Python package implementing sequential fairness on the predicted outputs of Machine Learning models, when dealing with multiple sensitive attributes. This post-processing method progressively achieve fairness accross a set of sensitive features by leveraging multi-marginal Wasserstein barycenters, which extends the standard notion of Strong Demographic Parity to the case with multiple sensitive characteristics. This approach seamlessly extends
to approximate fairness, enveloping a framework accommodating the trade-off between performance and unfairness.

The project was started in 2023 by François Hu, Philipp Ratz, Suzie Grondin, Agathe Fernandes Machado and Arthur Charpentier, following the release of this paper "A Sequentially Fair Mechanism for Multiple Sensitive Attributes" (https://arxiv.org/pdf/2309.06627.pdf), written by François Hu, Philipp Ratz and Arthur Charpentier.

For additional details, you can visit the dedicated **EquiPy** website https://equilibration.github.io/equipy/.

Installation
------------

Dependencies
~~~~~~~~~~~~

EquiPy requires:

- Numpy (>= 1.17.3)
- Scipy (>= 1.5.0)
- Scikit-learn (== 1.3.0)
- Matplotlib (== 3.7.2)
- Pandas (== 2.0.3)
- Statsmodels (== 0.14.0)
- Seaborn (== 0.12.2)
- POT (==0.9.1)

User installation
~~~~~~~~~~~~~~~~~


To install EquiPy, use ``pip``::

    pip install equipy

Project Tree Structure
----------------------

The following is the tree structure of the project:

.. code-block:: plaintext

    equipy/
        ├── equipy/
        |   ├── __init__.py
        |   ├── fairness/
        |   │   ├── __init__.py
        |   |   ├── _base.py
        |   |   ├── _wasserstein.py
        |   ├── graphs/
        |   │   ├── __init__.py
        |   │   ├── _arrow_plot.py
        |   │   ├── _density_plot.py
        |   │   ├── _waterfall_plot.py
        |   ├── metrics/
        |   │   ├── __init__.py
        |   │   ├── _fairness_metrics.py
        |   │   ├── _performance_metrics.py
        |   ├── utils/
        |   │   ├── __init__.py
        |   │   ├── checkers.py
        |   │   ├── permutations/
        |   │   |   ├── __init__.py
        |   │   |   ├── _compute_permutations.py
        |   │   |   ├── metrics/
        |   │   |   |   ├── __init__.py
        |   │   |   |   ├── _fairness_permutations.py
        |   │   |   |   ├── _performance_permutations.py
        ├── .gitignore
        ├── LICENSE
        ├── README.rst
        ├── requirements.txt
        ├── setup.py
        └── tests.py


Visualization
-------------

This package contains the module **graphs** which allows visualization of the resulting sequential fairness applied to a response variable.

|pic1| |pic2|

(Risk, Unfairness) phase diagrams that show the sequential fairness approach for (left pane) two sensitive features;
(right pane) three sensitive features.

.. |pic1| image:: https://raw.githubusercontent.com/equilibration/equipy/feature-corrections/examples/images/arrow_plot_2_sa.png
   :width: 45%

.. |pic2| image:: https://raw.githubusercontent.com/equilibration/equipy/feature-corrections/examples/images/arrow_plot_3_sa.png
   :width: 45%

|pic3| |pic4|

A sequential unfairness evaluation, for (left pane) exact fairness in $A_{3}$ ; (right pane) approximate fairness in $A_{3}$ with $\\epsilon = (\\epsilon_{1}, \\epsilon_{2}, \\epsilon_{3}) = (0.2, 0.5, 0.75)$. Hashed color corresponds to exact fairness.

.. |pic3| image:: https://raw.githubusercontent.com/equilibration/equipy/feature-corrections/examples/images/waterfall_plot_exact.png
   :width: 45%

.. |pic4| image:: https://raw.githubusercontent.com/equilibration/equipy/feature-corrections/examples/images/waterfall_plot_approx.png
   :width: 45%

Help and Support
----------------

Communication
~~~~~~~~~~~~~

If you have any inquiries, feel free to contact us:

- François Hu : hu.faugon@gmail.com
- Suzie Grondin : suzie.grondin@gmail.com
- Philipp Ratz : ratz.philipp@courrier.uqam.ca
- Agathe Fernandes Machado : fernandes_machado.agathe@courrier.uqam.ca
- Arthur Charpentier : arthur.charpentier@gmail.com