Metadata-Version: 2.1
Name: fair-scoring
Version: 0.2.1
Summary: Fairness metrics for continuous risk scores
Home-page: https://github.com/schufa-innovationlab/fair-scoring
Author: SCHUFA Holding AG
License: Apache 2.0
Project-URL: Documentation, https://fair-scoring.readthedocs.io/en/stable/
Project-URL: Changelog, https://fair-scoring.readthedocs.io/en/stable/changelog.html
Project-URL: Source code, https://github.com/schufa-innovationlab/fair-scoring
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0,>=1.22.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.6.0
Requires-Dist: seaborn>=0.12.0
Provides-Extra: dev
Requires-Dist: sphinx>=6.2.1; extra == "dev"
Requires-Dist: sphinx-book-theme>=1.1.0; extra == "dev"
Requires-Dist: sphinx-autoapi>=3.0.0; extra == "dev"
Requires-Dist: sphinx-design>=0.6.0; extra == "dev"
Requires-Dist: myst-nb>=1.0.0; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pandas>=2.2.1; extra == "dev"

# Fair-Scoring
Fairness metrics for continuous risk scores.

The implemented algorithms are described in the paper [[1]](#References).

#### Project Links
[Documentation](https://fair-scoring.readthedocs.io/en/stable/) | [PyPI](https://pypi.org/project/fair-scoring/) | [Paper](https://proceedings.mlr.press/v235/becker24a.html)

## Quickstart
### Installation

Install with `pip` directly:
```shell
pip install fair-scoring
```

### Example Usage
The following example shows how compute the equal opportunity bias of the compas dataset

```python
import pandas as pd
from fairscoring.metrics import bias_metric_eo

# Load compas data
dataURL = 'https://raw.githubusercontent.com/propublica/compas-analysis/master/compas-scores-two-years.csv'
df = pd.read_csv(dataURL)

# Relevant data
scores = df['decile_score']
target = df['two_year_recid']
attribute = df['race']

# Compute the bias
bias = bias_metric_eo(scores, target, attribute, groups=['African-American', 'Caucasian'], favorable_target=0,
                      prefer_high_scores=False)
```

#### Further examples
Further examples - especially the experiments conducted for the publication -  can be found 
[in the documentation](docs/source/examples).

## Development
### Setup
Clone the repository and install from this source via

```shell
pip install -e .[dev]
```

### Tests
To execute the tests install the package in development mode (see above)
```
pytest
```

Following the pytest framework, tests for each package are located in a subpackages named `test`

### Docs
To build the docs move to the `./docs` subfolder and call
```shell
make clean
make html
```

## References
[1] Becker, A.-K. and Dumitrasc, O. and Broelemann, K.;
Standardized Interpretable Fairness Measures for Continuous Risk Scores;
Proceedings of the 41th International Conference on Machine Learning, 2024; [pdf](https://openreview.net/pdf?id=CvRu2inbGV)
<details><summary>Bibtex</summary>
<p>

```
@inproceedings{Becker2024FairScoring,
    author = {Ann{-}Kristin Becker and Oana Dumitrasc and Klaus Broelemann}
    title  = {Standardized Interpretable Fairness Measures for Continuous Risk Scores},
    booktitle={Proceedings of the 41th International Conference on Machine Learning},
    year = {2024}
}
```

</p>
</details>
