# FLAI : Fairness Learning in Artificial Intelligence
[![Upload Python Package](https://github.com/rugonzs/FLAI/actions/workflows/python-publish.yml/badge.svg)](https://github.com/rugonzs/FLAI/actions/workflows/python-publish.yml)
[![Upload Docs](https://github.com/rugonzs/FLAI/actions/workflows/docs.yml/badge.svg)](https://github.com/rugonzs/FLAI/actions/workflows/docs.yml)
[![PyPI Version](https://img.shields.io/pypi/v/flai-causal)](https://pypi.org/project/flai-causal/)
[![Downloads](https://static.pepy.tech/badge/flai-causal)](https://pepy.tech/project/flai-causal)
[![Downloads](https://static.pepy.tech/badge/flai-causal/month)](https://pepy.tech/project/flai-causal)
[![Downloads](https://static.pepy.tech/badge/flai-causal/week)](https://pepy.tech/project/flai-causal)
Python library developed by Rubén González during his phD. research. His mission? To mitigate bias and discrimination through the application of causal algorithms.
[Demo](https://www.rubengonzalez.ai/demo)
[Documentation](https://rugonzs.github.io/FLAI/)
## Overview
![Overview](https://github.com/rugonzs/FLAI/blob/main/Documents/fair_algorithm.svg)
**FLAI** is a Python library designed with two key functionalities: building a **causal algorithm** and **mitigating biases** within it.
1. **Causal Algorithm Creation:** This library facilitates the development of a reliable causal algorithm, setting the stage for impartial data analysis.
2. **Bias Mitigation:** Fairness is pursued in two significant areas - **In-Training** and **Pre-Training**.
### In-Training Mitigation
The library includes features that allow the user to adjust the causal algorithm in two essential ways:
- **Graph Relationship Modification:** Relationships within the graph can be modified to establish a more balanced structure.
- **Probability Table Modification:** The probability table can be adjusted to prevent propagation or amplification of existing biases.
### Pre-Training Mitigation
With the mitigated causal algorithm, a bias-free dataset can be generated. This dataset can be used for the training of other algorithms, enabling the bias mitigation process to extend to the initial stages of new model development.
## Installation
**FLAI** can be easily installed using pip, Python's package installer. Open your terminal or command prompt and type the following command:
```bash
pip install flai-causal
```
## Features
### Causal Creation
```python
from FLAI import data
from FLAI import causal_graph
import pandas as pd
df = pd.read_pickle('../Data/adult.pickle')
flai_dataset = data.Data(df, transform=True)
flai_graph = causal_graph.CausalGraph(flai_dataset, target = 'label')
flai_graph.plot(directed = True)
```
![Original Graph](https://github.com/rugonzs/FLAI/blob/main/Documents/original_graph.svg)
### Causal Mitigation
#### Relations Mitigation
```python
flai_graph.mitigate_edge_relation(sensible_feature=['sex','age'])
```
![Mitigated Graph.](https://github.com/rugonzs/FLAI/blob/main/Documents/mitigated_graph.svg)
#### Table Probabilities Mitigation
```python
flai_graph.mitigate_calculation_cpd(sensible_feature = ['age','sex'])
```
#### Inference
Assess the impact of sensitive features before mitigation. Sex, Age and Label 0 is the unfavorable value.
```python
flai_graph.inference(variables=['sex','label'], evidence={})
flai_graph.inference(variables=['age','label'], evidence={})
```
| sex | label | p |
|-------|-------|--------|
| 0 | 0 | 0.1047 |
| **0** | **1** | **0.2053** |
| 1 | 0 | 0.1925 |
| **1** | **1** | **0.4975** |
| age | label | p |
|-----|-------|--------|
| 0 | 0 | 0.0641 |
| **0** | **1** | **0.1259** |
| 1 | 0 | 0.2331 |
| **1** | **1** | **0.5769** |
Assess the impact of sensitive features after mitigation. Changes in sex or age not affect the output.
```python
mitigated_graph.inference(variables=['sex','label'], evidence={})
mitigated_graph.inference(variables=['age','label'], evidence={})
```
| sex | label | p |
|-----|-------|--------|
| 0 | 0 | 0.1498 |
| **0** | **1** | **0.3502** |
| 1 | 0 | 0.1498 |
| **1** | **1** | **0.3502** |
| age | label | p |
|-----|-------|--------|
| 0 | 0 | 0.1498 |
| **0** | **1** | **0.3502** |
| 1 | 0 | 0.1498 |
| **1** | **1** | **0.3502** |
### Fair Data
```python
fair_data = flai_graph.generate_dataset(n_samples = 1000, methodtype = 'bayes')
```
![Correlation in original and Fair Data.](https://github.com/rugonzs/FLAI/blob/main/Documents/corr.svg)
#### Train Algorithm With Fair Data.
```python
from xgboost import XGBClassifier
from sklearn.model_selection import train_test_split
mitigated_X = fair_data.data[['age', 'sex', 'credit_history','savings','employment' ]]
mitigated_y = fair_data.data[['label']]
mitigated_X_train, mitigated_X_test, mitigated_y_train, mitigated_y_test = train_test_split(mitigated_X,
mitigated_y, test_size=0.7, random_state=54)
model_mitigated = XGBClassifier()
model_mitigated.fit(mitigated_X_train, mitigated_y_train)
metrics = mitigated_dataset.fairness_metrics(target_column='label', predicted_column = 'Predicted',
columns_fair = {'sex' : {'privileged' : 1, 'unprivileged' : 0},
'age' : {'privileged' : 1, 'unprivileged' : 0}})
```
##### Metrics Performance
| | ACC | TPR | FPR | FNR | PPP |
|-----------------|--------|---------|---------|---------|---------|
| model | 0.7034 | 0.97995 | 0.94494 | 0.02005 | 0.96948 |
| sex_privileged | 0.7024 | 0.97902 | 0.94363 | 0.02098 | 0.96841 |
| sex_unprivileged| 0.7044 | 0.98087 | 0.94626 | 0.01913 | 0.97055 |
| age_privileged | 0.7042 | 0.97881 | 0.94118 | 0.02119 | 0.96758 |
| age_unprivileged| 0.7026 | 0.98109 | 0.94872 | 0.01891 | 0.97139 |
##### Metrics Fairness
| | EOD | DI | SPD | OD |
|-----------------|---------|---------|---------|---------|
| sex_fair_metrics| 0.00185 | 1.00221 | 0.00214 | 0.00448 |
| age_fair_metrics| 0.00228 | 1.00394 | 0.00382 | 0.00981 |
##### Shap Results
```python
import shap
explainer_original = shap.Explainer(model_original)
explainer_mitigated = shap.Explainer(model_mitigated)
shap_values_orignal = explainer_original(original_dataset.data[
['sex', 'race','age','education']])
shap_values_mitigated = explainer_mitigated(original_dataset.data[
['sex', 'race', 'age','education']])
shap.plots.beeswarm(shap_values_orignal)
shap.plots.bar(shap_values_orignal)
shap.plots.beeswarm(shap_values_mitigated)
shap.plots.bar(shap_values_mitigated)
```
![shap values.](https://github.com/rugonzs/FLAI/blob/main/Documents/shap.svg)
## Citation
Raw data
{
"_id": null,
"home_page": "https://github.com/rugonzs/FLAI",
"name": "FLAI-CAUSAL",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Rub\u00e9n Gonz\u00e1lez Sendino",
"author_email": "rubo.g@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/c6/bf/0875e08a84205c4bb77cc9f861ef731899b01d4a125a919f021cdfe0dd2d/FLAI_CAUSAL-1.1.0.tar.gz",
"platform": null,
"description": "\n\n# FLAI : Fairness Learning in Artificial Intelligence\n\n[![Upload Python Package](https://github.com/rugonzs/FLAI/actions/workflows/python-publish.yml/badge.svg)](https://github.com/rugonzs/FLAI/actions/workflows/python-publish.yml)\n\n[![Upload Docs](https://github.com/rugonzs/FLAI/actions/workflows/docs.yml/badge.svg)](https://github.com/rugonzs/FLAI/actions/workflows/docs.yml)\n\n[![PyPI Version](https://img.shields.io/pypi/v/flai-causal)](https://pypi.org/project/flai-causal/)\n\n[![Downloads](https://static.pepy.tech/badge/flai-causal)](https://pepy.tech/project/flai-causal)\n\n[![Downloads](https://static.pepy.tech/badge/flai-causal/month)](https://pepy.tech/project/flai-causal)\n\n[![Downloads](https://static.pepy.tech/badge/flai-causal/week)](https://pepy.tech/project/flai-causal)\n\nPython library developed by Rub\u00e9n Gonz\u00e1lez during his phD. research. His mission? To mitigate bias and discrimination through the application of causal algorithms.\n\n[Demo](https://www.rubengonzalez.ai/demo)\n\n[Documentation](https://rugonzs.github.io/FLAI/)\n\n## Overview\n\n![Overview](https://github.com/rugonzs/FLAI/blob/main/Documents/fair_algorithm.svg)\n\n**FLAI** is a Python library designed with two key functionalities: building a **causal algorithm** and **mitigating biases** within it.\n\n1. **Causal Algorithm Creation:** This library facilitates the development of a reliable causal algorithm, setting the stage for impartial data analysis.\n\n2. **Bias Mitigation:** Fairness is pursued in two significant areas - **In-Training** and **Pre-Training**.\n\n ### In-Training Mitigation\n\n The library includes features that allow the user to adjust the causal algorithm in two essential ways:\n\n - **Graph Relationship Modification:** Relationships within the graph can be modified to establish a more balanced structure.\n - **Probability Table Modification:** The probability table can be adjusted to prevent propagation or amplification of existing biases.\n\n ### Pre-Training Mitigation\n\n With the mitigated causal algorithm, a bias-free dataset can be generated. This dataset can be used for the training of other algorithms, enabling the bias mitigation process to extend to the initial stages of new model development.\n\n\n## Installation\n\n**FLAI** can be easily installed using pip, Python's package installer. Open your terminal or command prompt and type the following command:\n\n```bash\npip install flai-causal\n```\n\n## Features\n\n### Causal Creation\n\n```python\nfrom FLAI import data\nfrom FLAI import causal_graph\nimport pandas as pd\n\ndf = pd.read_pickle('../Data/adult.pickle')\nflai_dataset = data.Data(df, transform=True)\nflai_graph = causal_graph.CausalGraph(flai_dataset, target = 'label')\nflai_graph.plot(directed = True)\n```\n![Original Graph](https://github.com/rugonzs/FLAI/blob/main/Documents/original_graph.svg)\n\n\n### Causal Mitigation\n\n#### Relations Mitigation\n\n```python\n\nflai_graph.mitigate_edge_relation(sensible_feature=['sex','age'])\n```\n![Mitigated Graph.](https://github.com/rugonzs/FLAI/blob/main/Documents/mitigated_graph.svg)\n\n#### Table Probabilities Mitigation\n\n```python\n\nflai_graph.mitigate_calculation_cpd(sensible_feature = ['age','sex'])\n\n```\n\n#### Inference\n\nAssess the impact of sensitive features before mitigation. Sex, Age and Label 0 is the unfavorable value.\n\n```python\nflai_graph.inference(variables=['sex','label'], evidence={})\nflai_graph.inference(variables=['age','label'], evidence={})\n\n```\n\n| sex | label | p |\n|-------|-------|--------|\n| 0 | 0 | 0.1047 |\n| **0** | **1** | **0.2053** |\n| 1 | 0 | 0.1925 |\n| **1** | **1** | **0.4975** |\n\n| age | label | p |\n|-----|-------|--------|\n| 0 | 0 | 0.0641 |\n| **0** | **1** | **0.1259** |\n| 1 | 0 | 0.2331 |\n| **1** | **1** | **0.5769** |\n\nAssess the impact of sensitive features after mitigation. Changes in sex or age not affect the output.\n\n```python\nmitigated_graph.inference(variables=['sex','label'], evidence={})\nmitigated_graph.inference(variables=['age','label'], evidence={})\n\n```\n\n| sex | label | p |\n|-----|-------|--------|\n| 0 | 0 | 0.1498 |\n| **0** | **1** | **0.3502** |\n| 1 | 0 | 0.1498 |\n| **1** | **1** | **0.3502** |\n\n\n| age | label | p |\n|-----|-------|--------|\n| 0 | 0 | 0.1498 |\n| **0** | **1** | **0.3502** |\n| 1 | 0 | 0.1498 |\n| **1** | **1** | **0.3502** |\n\n\n### Fair Data\n\n```python\nfair_data = flai_graph.generate_dataset(n_samples = 1000, methodtype = 'bayes')\n```\n![Correlation in original and Fair Data.](https://github.com/rugonzs/FLAI/blob/main/Documents/corr.svg)\n\n#### Train Algorithm With Fair Data.\n\n```python\nfrom xgboost import XGBClassifier\nfrom sklearn.model_selection import train_test_split\n\nmitigated_X = fair_data.data[['age', 'sex', 'credit_history','savings','employment' ]]\nmitigated_y = fair_data.data[['label']]\nmitigated_X_train, mitigated_X_test, mitigated_y_train, mitigated_y_test = train_test_split(mitigated_X,\n mitigated_y, test_size=0.7, random_state=54)\nmodel_mitigated = XGBClassifier()\nmodel_mitigated.fit(mitigated_X_train, mitigated_y_train)\nmetrics = mitigated_dataset.fairness_metrics(target_column='label', predicted_column = 'Predicted',\n columns_fair = {'sex' : {'privileged' : 1, 'unprivileged' : 0},\n 'age' : {'privileged' : 1, 'unprivileged' : 0}})\n```\n\n##### Metrics Performance\n\n| | ACC | TPR | FPR | FNR | PPP |\n|-----------------|--------|---------|---------|---------|---------|\n| model | 0.7034 | 0.97995 | 0.94494 | 0.02005 | 0.96948 |\n| sex_privileged | 0.7024 | 0.97902 | 0.94363 | 0.02098 | 0.96841 |\n| sex_unprivileged| 0.7044 | 0.98087 | 0.94626 | 0.01913 | 0.97055 |\n| age_privileged | 0.7042 | 0.97881 | 0.94118 | 0.02119 | 0.96758 |\n| age_unprivileged| 0.7026 | 0.98109 | 0.94872 | 0.01891 | 0.97139 |\n\n##### Metrics Fairness\n\n| | EOD | DI | SPD | OD |\n|-----------------|---------|---------|---------|---------|\n| sex_fair_metrics| 0.00185 | 1.00221 | 0.00214 | 0.00448 |\n| age_fair_metrics| 0.00228 | 1.00394 | 0.00382 | 0.00981 |\n\n##### Shap Results\n```python\nimport shap\n\nexplainer_original = shap.Explainer(model_original)\nexplainer_mitigated = shap.Explainer(model_mitigated)\nshap_values_orignal = explainer_original(original_dataset.data[\n ['sex', 'race','age','education']])\nshap_values_mitigated = explainer_mitigated(original_dataset.data[\n ['sex', 'race', 'age','education']])\nshap.plots.beeswarm(shap_values_orignal)\nshap.plots.bar(shap_values_orignal) \n\nshap.plots.beeswarm(shap_values_mitigated)\nshap.plots.bar(shap_values_mitigated)\n\n```\n![shap values.](https://github.com/rugonzs/FLAI/blob/main/Documents/shap.svg)\n\n## Citation\n",
"bugtrack_url": null,
"license": "Apache-2.0 license",
"summary": "Library to creat causal model and mitigate the bias.",
"version": "1.1.0",
"project_urls": {
"Documentation": "https://rugonzs.github.io/FLAI/",
"Homepage": "https://github.com/rugonzs/FLAI",
"Source Code": "https://github.com/rugonzs/FLAI"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1978ecd97a25dc9629a185bd878f24dbf723c2a0d287cd8797088608632e0fb0",
"md5": "2313de5baca7443563524afcbbb4bb35",
"sha256": "4fa063ba5b869d79473a4f6aea441937137e696d57bf886f257d227a9fccced9"
},
"downloads": -1,
"filename": "FLAI_CAUSAL-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2313de5baca7443563524afcbbb4bb35",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12732,
"upload_time": "2023-06-04T10:48:23",
"upload_time_iso_8601": "2023-06-04T10:48:23.588747Z",
"url": "https://files.pythonhosted.org/packages/19/78/ecd97a25dc9629a185bd878f24dbf723c2a0d287cd8797088608632e0fb0/FLAI_CAUSAL-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c6bf0875e08a84205c4bb77cc9f861ef731899b01d4a125a919f021cdfe0dd2d",
"md5": "bc7f8ef8e92288cd3f3ac99d229095bc",
"sha256": "b12e76b46bc76426f1362d522846b6799831dd9832fd3ecc89ba8656b355e9d0"
},
"downloads": -1,
"filename": "FLAI_CAUSAL-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bc7f8ef8e92288cd3f3ac99d229095bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12550,
"upload_time": "2023-06-04T10:48:25",
"upload_time_iso_8601": "2023-06-04T10:48:25.783463Z",
"url": "https://files.pythonhosted.org/packages/c6/bf/0875e08a84205c4bb77cc9f861ef731899b01d4a125a919f021cdfe0dd2d/FLAI_CAUSAL-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-04 10:48:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rugonzs",
"github_project": "FLAI",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flai-causal"
}