Metadata-Version: 2.4
Name: fairical
Version: 2.0.3
Summary: Fairical is a Python library to assess adjustable demographically fair Machine Learning (ML) systems
Project-URL: documentation, https://fairical.readthedocs.io/en/v2.0.3/
Project-URL: homepage, https://pypi.org/project/fairical
Project-URL: repository, https://gitlab.idiap.ch/medai/software/fairical
Project-URL: changelog, https://gitlab.idiap.ch/medai/software/fairical/-/releases
Author-email: Gokhan Ozbulak <gokhan.ozbulak@idiap.ch>
License-Expression: GPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click
Requires-Dist: compact-json
Requires-Dist: fairlearn
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pydantic>=2
Requires-Dist: pymoo
Requires-Dist: scikit-learn
Requires-Dist: tabulate
Provides-Extra: doc
Requires-Dist: auto-intersphinx; extra == 'doc'
Requires-Dist: furo; extra == 'doc'
Requires-Dist: sphinx; extra == 'doc'
Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
Requires-Dist: sphinx-click; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-design; extra == 'doc'
Requires-Dist: sphinx-inline-tabs; extra == 'doc'
Requires-Dist: sphinxcontrib-bibtex; extra == 'doc'
Requires-Dist: sphobjinv; extra == 'doc'
Provides-Extra: qa
Requires-Dist: prek; extra == 'qa'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: Copyright © 2025 Idiap Research Institute <contact@idiap.ch>
SPDX-License-Identifier: GPL-3.0-or-later
-->

[![latest-docs](https://img.shields.io/badge/docs-v2.0.3-orange.svg)](https://fairical.readthedocs.io/en/v2.0.3/)
[![build](https://gitlab.idiap.ch/medai/software/fairical/badges/v2.0.3/pipeline.svg)](https://gitlab.idiap.ch/medai/software/fairical/commits/v2.0.3)
[![coverage](https://gitlab.idiap.ch/medai/software/fairical/badges/v2.0.3/coverage.svg)](https://www.idiap.ch/software/medai/docs/medai/software/fairical/v2.0.3/coverage/index.html)
[![repository](https://img.shields.io/badge/gitlab-project-0000c0.svg)](https://gitlab.idiap.ch/medai/software/fairical)

# Fairical

Fairical is a Python library for rigorously evaluating and comparing demographically
fair machine-learning systems through the lens of multi-objective optimization. Rather
than treating fairness as a single constraint, Fairical recognizes that real-world
deployments must balance multiple, often conflicting fairness metrics (e.g., demographic
parity, equalized odds across race, gender, age) alongside traditional utility measures
like accuracy. It implements a model-agnostic evaluation framework that approximates
Pareto fronts of utility-fairness trade-offs, then distills each system's performance
into a compact measurement table and radar chart. By calculating convergence (how close
models get to optimal trade-offs), diversity (uniform distribution and spread of
solutions), capacity (number of non-dominated points), and a unified
convergence-diversity score via hypervolume, Fairical delivers both quantitative rigor
and qualitative clarity.

For installation and usage instructions, check-out our documentation.

If you use this library in published material, we kindly ask you to cite this work:

```bibtex
@article{ozbulak_multi-objective_2025,
	title={A Multi-Objective Evaluation Framework for Analyzing Utility-Fairness Trade-Offs in Machine Learning Systems},
	author={Özbulak, Gökhan and Jimenez-del-Toro, Oscar and Fatoretto, Maíra and Berton, Lilian and Anjos, André},
	journal={Machine Learning for Biomedical Imaging},
	volume={3},
	number={Special issue on FAIMI},
	pages={938--957},
	doi={10.59275/j.melba.2025-ab9a},
	year={2025}
}
```
