### Install AIF360 Example Notebook Requirements

Source: https://github.com/trusted-ai/aif360/blob/main/README.md

Installs the necessary dependencies to run the example notebooks included with AIF360, specifically for the notebooks extra. This is done after manual installation.

```bash
pip install -e '.[notebooks]'
```

--------------------------------

### Install AIF360 Reductions

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_deterministic_reranking.ipynb

Install the AIF360 library with the Reductions package support.

```bash
pip install 'aif360[Reductions]'
```

--------------------------------

### Install Fairlearn and Dependencies

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_grid_search_reduction_regression_sklearn.ipynb

Installs the aif360 library with Reductions support from Fairlearn. This is a prerequisite for using the grid search functionality for fair machine learning models.

```python
#Install aif360
#Install Reductions from Fairlearn
!pip install aif360[Reductions]
```

--------------------------------

### Manual Installation of AIF360 from Source

Source: https://github.com/trusted-ai/aif360/blob/main/README.md

This section covers cloning the AIF360 repository and installing it in editable mode with all optional dependencies. This method is useful for development or when using the latest unreleased code.

```bash
git clone https://github.com/Trusted-AI/AIF360
pip install --editable '.[all]'
```

--------------------------------

### Initialize SenSeI Environment and Imports

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_sensei_infairness.ipynb

Imports necessary libraries for data manipulation, machine learning, and the SenSeI fairness framework. This setup includes scikit-learn, PyTorch, and AIF360 components.

```python
import pandas as pd
from sklearn.metrics import accuracy_score, balanced_accuracy_score
from sklearn.compose import make_column_transformer
from sklearn.preprocessing import OneHotEncoder, StandardScaler, minmax_scale
from sklearn.model_selection import train_test_split
from skorch import NeuralNetClassifier
import torch
import torch.nn as nn
import torch.nn.functional as F

from inFairness import distances
from inFairness.auditor import SenSeIAuditor

import aif360
from aif360.sklearn.datasets import fetch_adult
from aif360.sklearn.metrics import consistency_score
from aif360.sklearn.inprocessing import SenSeI
```

--------------------------------

### Dataset Loading and Preparation

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/monthly_bee_datasets_metrics.ipynb

Demonstrates how to install AIF360, import necessary libraries, load datasets (e.g., Adult dataset), and inspect their structure.

```APIDOC
## Installation and Imports

### Description
Installs the AIF360 library and imports essential Python libraries for data manipulation, machine learning, and fairness metrics.

### Code
```python
# Install AIF360
!pip install 'aif360'

import pandas as pd
import seaborn as sns

from sklearn.compose import make_column_transformer
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score
from sklearn.model_selection import GridSearchCV, train_test_split
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler

from aif360.sklearn.datasets import fetch_adult, standardize_dataset
from aif360.sklearn.metrics import disparate_impact_ratio, average_odds_error
from aif360.sklearn.metrics import base_rate, ratio
```

## Loading the Adult Dataset

### Description
Loads the Adult dataset from UCI using `fetch_adult`. Datasets are returned as pandas DataFrames for features (X) and labels (y), with the index containing protected attribute information. `sample_weight` may also be provided.

### Method
`aif360.sklearn.datasets.fetch_adult`

### Parameters
- `binary_race` (bool) - Optional - If True, the race column will be binarized.
- `dropna` (bool) - Optional - If True, rows with missing values are dropped. Defaults to True.

### Request Example
```python
X, y, sample_weight = fetch_adult(binary_race=False)
X.head()
```

### Response Example
```
# X.head() output
             age  workclass     education  education-num      marital-status  \
race  sex                                                                      
Black Male  25.0    Private          11th            7.0       Never-married   
White Male  38.0    Private       HS-grad            9.0  Married-civ-spouse   
      Male  28.0  Local-gov    Assoc-acdm           12.0  Married-civ-spouse   
Black Male  44.0    Private  Some-college           10.0  Married-civ-spouse   
White Male  34.0    Private          10th            6.0       Never-married   

                   occupation   relationship   race   sex  capital-gain  \
race  sex                                                                 
Black Male  Machine-op-inspct      Own-child  Black  Male           0.0   
White Male    Farming-fishing        Husband  White  Male           0.0   
      Male    Protective-serv        Husband  White  Male           0.0   
Black Male  Machine-op-inspct        Husband  Black  Male        7688.0   
White Male      Other-service  Not-in-family  White  Male           0.0   

            capital-loss  hours-per-week native-country  
race  sex                                                
Black Male           0.0            40.0  United-States  
White Male           0.0            50.0  United-States  
      Male           0.0            40.0  United-States  
Black Male           0.0            40.0  United-States  
White Male           0.0            30.0  United-States  

# y.head() output
race   sex 
Black  Male    <=50K
White  Male    <=50K
       Male     >50K
Black  Male     >50K
White  Male    <=50K
Name: annual-income, dtype: category
Categories (2, object): ['<=50K' < '>50K']
```

## Handling Missing Values

### Description
Demonstrates how to load the dataset while controlling the handling of missing values using the `dropna` argument.

### Method
`aif360.sklearn.datasets.fetch_adult`

### Parameters
- `dropna` (bool) - If True (default), rows with NA values are dropped. If False, rows with NA values are kept.

### Request Example
```python
X_num, y_num, _ = fetch_adult(dropna=False)
X.shape, X_num.shape
```

### Response Example
```
((45222, 13), (48842, 13))
```

## Dataset Splitting and Encoding

### Description
Shows how to split the dataset into training and testing sets using `train_test_split` and how to one-hot encode categorical features for use in machine learning models.

### Code
```python
from sklearn.model_selection import train_test_split

(X_train, X_test,
 y_train, y_test) = train_test_split(X, y, train_size=0.7, random_state=1234567)

# One-hot encoding would typically follow here using OneHotEncoder
# Example (not fully functional without a full pipeline):
# from sklearn.preprocessing import OneHotEncoder
# from sklearn.compose import make_column_transformer
# preprocessor = make_column_transformer(
#     (OneHotEncoder(handle_unknown='ignore'), categorical_features),
#     remainder='passthrough')
```
```

--------------------------------

### Install AIF360 Library

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_reject_option_classification.ipynb

Installs the AIF360 library, which is required for using the Reject Option Classification method and other fairness-aware machine learning tools.

```python
#Install AIF360
!pip install 'aif360'
```

--------------------------------

### Install Additional Dependencies

Source: https://github.com/trusted-ai/aif360/wiki/ODSC-Immersive-AI-2019-Tutorial

These commands install or upgrade the NumPy library and then install all other required dependencies listed in the 'requirements.txt' file. These are necessary for the AIF360 toolkit to function correctly.

```bash
pip install --upgrade numpy
pip install -r requirements.txt
```

--------------------------------

### Install AIF360 using Pip

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_learning_fair_representations.ipynb

This command installs the AIF360 library and its optional dependencies for LawSchoolGPA. It uses pip, the standard package installer for Python. The output indicates whether the package was already installed or if it needs to be downloaded and installed.

```python
!pip install 'aif360[LawSchoolGPA]'
```

--------------------------------

### Complete Fairness Workflow Example in Python

Source: https://context7.com/trusted-ai/aif360/llms.txt

Presents an end-to-end workflow for fairness-aware machine learning using the AI Fairness 360 library. This example covers data loading and preparation (AdultDataset), splitting data, applying preprocessing (Reweighing) and post-processing (EqOddsPostprocessing) mitigation techniques, and evaluating fairness using BinaryLabelDatasetMetric and ClassificationMetric. It also includes model training with LogisticRegression and data scaling with StandardScaler.

```python
import numpy as np
from aif360.datasets import AdultDataset
from aif360.metrics import BinaryLabelDatasetMetric, ClassificationMetric
from aif360.algorithms.preprocessing import Reweighing
from aif360.algorithms.postprocessing import EqOddsPostprocessing
from sklearn.linear_model import LogisticRegression
from sklearn.preprocessing import StandardScaler

# 1. Load and prepare data
dataset = AdultDataset()
privileged_groups = [{'sex': 1}]
unprivileged_groups = [{'sex': 0}]

dataset_train, dataset_test = dataset.split([0.7], shuffle=True)

```

--------------------------------

### Install AIF360 Library

Source: https://github.com/trusted-ai/aif360/blob/main/docs/source/Getting Started.rst

Commands to install the AIF360 library using pip for Python or CRAN for R. Includes options for installing specific algorithm dependencies.

```bash
pip install aif360
pip install 'aif360[LFR,OptimPreproc]'
pip install 'aif360[all]'
```

```r
install.packages("aif360")
```

--------------------------------

### Install AIF360 with LIME Support

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_lime.ipynb

Installs the AIF360 toolkit along with the necessary dependencies for LIME integration. This command ensures that all required packages are available for generating model explanations.

```python
# Install AIF360
!pip install 'aif360[lime]'
```

--------------------------------

### Install AIF360 Library

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_mdss_bias_scan.ipynb

Installs the AI Fairness 360 (AIF360) library, a Python toolkit for detecting and mitigating unwanted bias in machine learning models. This is a prerequisite for running the subsequent analysis.

```python
# Install AIF360
!pip install 'aif360'
```

--------------------------------

### Install AIF360 R Package

Source: https://github.com/trusted-ai/aif360/blob/main/aif360/aif360-r/README.md

Commands to install the AIF360 package from CRAN or GitHub and initialize the underlying Python environment.

```R
install.packages("aif360")
devtools::install_github("Trusted-AI/AIF360/aif360/aif360-r")
library(aif360)
install_aif360()
```

--------------------------------

### Install Xcode Command Line Tools on macOS

Source: https://github.com/trusted-ai/aif360/blob/main/README.md

Command to install the Xcode Command Line Tools on macOS, which may be a prerequisite for installing libraries like CVXPY that have C extensions.

```bash
xcode-select --install
```

--------------------------------

### Install CVXPY Dependency for AIF360

Source: https://github.com/trusted-ai/aif360/blob/main/README.md

Installs the CVXPY library, which is required for the OptimPreproc algorithm in AIF360. This snippet may require prior installation of Xcode Command Line Tools on macOS or Microsoft C++ Build Tools on Windows.

```bash
pip install 'aif360[OptimPreproc]'
```

--------------------------------

### Install AIF360 Package

Source: https://github.com/trusted-ai/aif360/blob/main/README.md

Installation commands for the AIF360 library in R and Python environments. These commands ensure the necessary dependencies are fetched from the respective package repositories.

```R
install.packages("aif360")
```

```bash
pip install aif360
```

--------------------------------

### Install AIF360 using pip

Source: https://github.com/trusted-ai/aif360/blob/main/README.md

Installs the latest stable version of the AIF360 package from PyPI. Additional dependencies for specific algorithms or full functionality can be included using extras.

```bash
pip install aif360
```

```bash
pip install 'aif360[LFR,OptimPreproc]'
```

```bash
pip install 'aif360[all]'
```

--------------------------------

### Initialize and Configure AdultDataset for Bias Mitigation

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_disparate_impact_remover.ipynb

Imports necessary libraries and initializes the AdultDataset with specific protected attributes and features to keep. This setup prepares the data for the disparate impact removal process.

```python
from aif360.datasets import AdultDataset
protected = 'sex'
ad = AdultDataset(protected_attribute_names=[protected],
    privileged_classes=[['Male']], categorical_features=[],
    features_to_keep=['age', 'education-num', 'capital-gain', 'capital-loss', 'hours-per-week'])
```

--------------------------------

### Install AI Fairness 360 Toolkit

Source: https://github.com/trusted-ai/aif360/wiki/ODSC-Immersive-AI-2019-Tutorial

This command installs the latest stable version of the AI Fairness 360 (AIF360) toolkit using pip. It assumes the conda environment is already activated.

```bash
pip install aif360
```

--------------------------------

### Calculate Fairness Metrics

Source: https://github.com/trusted-ai/aif360/blob/main/docs/source/Getting Started.rst

Examples of calculating group, individual, and distributional fairness metrics to quantify bias in model predictions.

```python
from aif360.sklearn.metrics import disparate_impact_ratio, consistency_score, generalized_entropy_error

# Group fairness
di = disparate_impact_ratio(y_true, y_pred, prot_attr='race', priv_group='White', pos_label=1)

# Individual fairness
cons = consistency_score(X_test, y_pred)

# Distributional fairness
ent = generalized_entropy_error(y_true, y_pred)
```

--------------------------------

### Navigate to Tutorial Files Directory

Source: https://github.com/trusted-ai/aif360/wiki/ODSC-Immersive-AI-2019-Tutorial

These commands demonstrate how to change the current directory to the 'tutorial_files' folder after unzipping the downloaded archive. Paths vary for Windows and Linux/MacOS.

```bash
cd C:\Users\%USERNAME%\Downloads\tutorial_files
```

```bash
cd ~/Downloads/tutorial_files
```

--------------------------------

### Check Anaconda Installation

Source: https://github.com/trusted-ai/aif360/wiki/ODSC-Immersive-AI-2019-Tutorial

This command checks if Anaconda is installed on your system by displaying its help information. It's a prerequisite for the installation process.

```bash
conda help
```

--------------------------------

### Prepare Data and Model for LIME Explanation (Python)

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_medical_expenditure.ipynb

This snippet initializes the training and testing datasets, loads the trained model, and determines the best threshold for balanced accuracy. It sets up the necessary components for generating LIME explanations.

```python
train_dataset = dataset_transf_panel19_train  # data the deployed model (lr from transformed data)
test_dataset = dataset_orig_panel20_deploy  # the data model is being tested on
model = lr_transf_panel19  # lr_transf_panel19 is LR model learned from Panel 19 with Reweighing
thresh_arr = np.linspace(0.01, 0.5, 50)
best_thresh = thresh_arr[lr_transf_best_ind]
```

--------------------------------

### Initialize and Apply DeterministicReranking (Python)

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_deterministic_reranking.ipynb

Imports necessary classes from AIF360 and demonstrates the initialization of the DeterministicReranking algorithm. This algorithm is used to achieve a fairer representation of protected attributes in the ranked list.

```python
from aif360.datasets import RegressionDataset
from aif360.algorithms.postprocessing.deterministic_reranking import DeterministicReranking
```

--------------------------------

### Instantiate and Run FairAdapt

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_fairadapt_sklearn.ipynb

Performs data adaptation to mitigate bias using the FairAdapt algorithm.

```APIDOC
## Instantiate and Run FairAdapt

### Description
Initializes the FairAdapt object and transforms the training and test datasets to remove bias based on a protected attribute.

### Parameters
- **prot_attr** (string) - Required - The protected attribute to mitigate (e.g., 'sex').
- **adj_mat** (DataFrame) - Required - The causal adjacency matrix.

### Request Example
```python
FA = FairAdapt(prot_attr="sex", adj_mat=adj_mat)
Xf_train, yf_train, Xf_test = FA.fit_transform(X_train, y_train, X_test)
```
```

--------------------------------

### Install TensorFlow Dependency for AIF360

Source: https://github.com/trusted-ai/aif360/blob/main/README.md

Installs the TensorFlow library, which is a requirement for using the AdversarialDebiasing algorithm within AIF360. It specifies a minimum version of TensorFlow.

```bash
pip install 'aif360[AdversarialDebiasing]'
```

--------------------------------

### Importing FACTS and dependencies

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_FACTS.ipynb

Initializes the environment by importing necessary scikit-learn modules, AIF360 dataset utilities, and the FACTS auditing framework.

```python
from sklearn.model_selection import train_test_split
from sklearn.linear_model import LogisticRegression
from sklearn.compose import ColumnTransformer
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder

from aif360.sklearn.datasets.openml_datasets import fetch_adult
from aif360.sklearn.detectors.facts.clean import clean_dataset
from aif360.sklearn.detectors.facts import FACTS, FACTS_bias_scan

from IPython.display import display

import warnings
warnings.filterwarnings("ignore")
```

--------------------------------

### Configure ExponentiatedGradientReduction with Fairlearn Moments

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_exponentiated_gradient_reduction_sklearn.ipynb

Demonstrates initializing the ExponentiatedGradientReduction model using a predefined Fairlearn moment object for constraints, such as EqualizedOdds, instead of a string identifier.

```python
import fairlearn.reductions as red
np.random.seed(0)
exp_grad_red2 = ExponentiatedGradientReduction(prot_attr=prot_attr_cols, estimator=estimator, constraints=red.EqualizedOdds(), drop_prot_attr=False)
exp_grad_red2.fit(X_train, y_train)
exp_grad_red2.score(X_test, y_test)
```

--------------------------------

### Initialize LimeTabularExplainer (Python)

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_medical_expenditure.ipynb

Initializes the `LimeTabularExplainer` with LIME-compatible training data and configuration. This explainer is used to generate explanations for model predictions.

```python
explainer = LimeTabularExplainer(
        s_train, class_names=lime_data.s_class_names, 
        feature_names=lime_data.s_feature_names,
        categorical_features=lime_data.s_categorical_features, 
        categorical_names=lime_data.s_categorical_names, 
        kernel_width=3, verbose=False, discretize_continuous=True)
```

--------------------------------

### Initialize AIF360 Environment and Dependencies

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_medical_expenditure.ipynb

This snippet imports the required AIF360 modules, scikit-learn classifiers, and LIME explainers. It also sets the random seed to ensure reproducibility for the model training process.

```python
import sys
sys.path.insert(0, '../')

%matplotlib inline
import matplotlib.pyplot as plt
import numpy as np
from IPython.display import Markdown, display

from aif360.datasets import MEPSDataset19, MEPSDataset20, MEPSDataset21
from aif360.metrics import BinaryLabelDatasetMetric, ClassificationMetric
from aif360.explainers import MetricTextExplainer
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression
from sklearn.pipeline import make_pipeline
from aif360.algorithms.preprocessing import Reweighing
from aif360.algorithms.inprocessing import PrejudiceRemover
from aif360.datasets.lime_encoder import LimeEncoder
import lime
from lime.lime_tabular import LimeTabularExplainer

np.random.seed(1)
```

--------------------------------

### Import AIF360 and Scikit-Learn Dependencies

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_optim_data_preproc.ipynb

Initializes the environment by importing necessary AIF360 modules for bias mitigation, dataset handling, and Scikit-Learn for model training.

```python
import sys
sys.path.append("../")
import numpy as np
from aif360.datasets import BinaryLabelDataset, AdultDataset, GermanDataset, CompasDataset
from aif360.metrics import BinaryLabelDatasetMetric, ClassificationMetric
from aif360.algorithms.preprocessing.optim_preproc import OptimPreproc
from sklearn.linear_model import LogisticRegression
from sklearn.preprocessing import StandardScaler
```

--------------------------------

### Initialize AIF360 Environment and Dependencies

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_calibrated_eqodds_postprocessing.ipynb

Imports necessary libraries including AIF360 datasets, metrics, and scikit-learn components required for bias mitigation workflows.

```python
%matplotlib inline
import sys
import numpy as np
import pandas as pd
sys.path.append("../")
from aif360.datasets import AdultDataset, GermanDataset, CompasDataset
from aif360.metrics import BinaryLabelDatasetMetric, ClassificationMetric
from sklearn.linear_model import LogisticRegression
```

--------------------------------

### Initialize Metric Explainers

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_json_explainers.ipynb

Creates instances of MetricTextExplainer and MetricJSONExplainer using the pre-calculated BinaryLabelDatasetMetric object.

```python
text_expl = MetricTextExplainer(bldm)
json_expl = MetricJSONExplainer(bldm)
```

--------------------------------

### GET /metrics/bias/mean_difference

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_optim_preproc_adult.ipynb

Calculates the mean difference in favorable outcomes between privileged and unprivileged groups to detect bias in a dataset.

```APIDOC
## GET /metrics/bias/mean_difference

### Description
Computes the difference in mean outcomes between unprivileged and privileged groups. A negative value indicates bias against the unprivileged group.

### Method
GET

### Endpoint
/metrics/bias/mean_difference

### Parameters
#### Query Parameters
- **dataset** (object) - Required - The BinaryLabelDataset containing the features and labels.
- **privileged_groups** (list) - Required - List of dictionaries defining the privileged group (e.g., [{'race': 1}]).
- **unprivileged_groups** (list) - Required - List of dictionaries defining the unprivileged group (e.g., [{'race': 0}]).

### Request Example
{
  "dataset": "dataset_orig_train",
  "privileged_groups": [{"race": 1}],
  "unprivileged_groups": [{"race": 0}]
}

### Response
#### Success Response (200)
- **mean_difference** (float) - The calculated difference in mean outcomes between groups.

#### Response Example
{
  "mean_difference": -0.104553
}
```

--------------------------------

### Configure Dataset and Optimization Parameters

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_optim_data_preproc.ipynb

Sets up the dataset selection, defines privileged/unprivileged groups, and configures the optimization options required for the OptimPreproc algorithm. It also performs the initial split of data into training, validation, and testing sets.

```python
dataset_used = "adult"
protected_attribute_used = 1
if dataset_used == "adult":
    privileged_groups = [{'sex': 1}]
    unprivileged_groups = [{'sex': 0}]
    dataset_orig = load_preproc_data_adult(['sex'])
    optim_options = {
        "distortion_fun": get_distortion_adult,
        "epsilon": 0.05,
        "clist": [0.99, 1.99, 2.99],
        "dlist": [.1, 0.05, 0]
    }
np.random.seed(1)
dataset_orig_train, dataset_orig_vt = dataset_orig.split([0.7], shuffle=True)
dataset_orig_valid, dataset_orig_test = dataset_orig_vt.split([0.5], shuffle=True)
```

--------------------------------

### Metric Explanation API

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_json_explainers.ipynb

This section details how to use MetricTextExplainer and MetricJSONExplainer to get human-readable and structured JSON explanations of fairness metrics.

```APIDOC
## Metric Explanation API

### Description
This API allows for the explanation of fairness metrics computed on a dataset. It provides both text-based and JSON-based outputs for clarity and programmatic use.

### Method
N/A (This is a library usage example, not a direct API endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Load dataset and compute metrics
gd = GermanDataset()
priv = [{'sex': 1}]
unpriv = [{'sex': 0}]
bldm = BinaryLabelDatasetMetric(gd, unprivileged_groups=unpriv, privileged_groups=priv)

# Initialize explainers
text_expl = MetricTextExplainer(bldm)
json_expl = MetricJSONExplainer(bldm)

# Get text explanation for number of positives
print(text_expl.num_positives())

# Get JSON explanation for mean difference
print(format_json(json_expl.mean_difference()))
```

### Response
#### Success Response (Text Output)
- **Output**: String containing a human-readable explanation of the metric.

#### Success Response (JSON Output)
- **metric** (string) - The name of the fairness metric.
- **message** (string) - A descriptive message about the metric.
- **numPositives** (float) - Number of positive instances (for num_positives).
- **numPositivesUnprivileged** (float) - Number of positive instances for the unprivileged group.
- **numInstancesUnprivileged** (float) - Total number of instances in the unprivileged group.
- **numPositivesPrivileged** (float) - Number of positive instances for the privileged group.
- **numInstancesPrivileged** (float) - Total number of instances in the privileged group.
- **description** (string) - Detailed description of the metric.
- **ideal** (string) - The ideal value or condition for the metric.

#### Response Example (Text)
```
Number of positive-outcome instances: 700.0
```

#### Response Example (JSON)
```json
{
  "metric": "mean_difference", 
  "message": "Mean difference (mean label value on privileged instances - mean label value on unprivileged instances): -0.0748013090229", 
  "numPositivesUnprivileged": 201.0, 
  "numInstancesUnprivileged": 310.0, 
  "numPositivesPrivileged": 499.0, 
  "numInstancesPrivileged": 690.0, 
  "description": "Computed as the difference of the rate of favorable outcomes received by the unprivileged group to the privileged group.", 
  "ideal": "The ideal value of this metric is 0.0"
}
```
```

--------------------------------

### Explain Number of Positives (Text)

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_json_explainers.ipynb

Uses the MetricTextExplainer to get a human-readable string describing the number of positive outcome instances in the dataset.

```python
print(text_expl.num_positives())
```

--------------------------------

### Execute Explanation Generation and Display (Python)

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_medical_expenditure.ipynb

This snippet executes the explanation generation process by printing the best threshold and calling `show_explanation` for specific instances (index 0 and 2) from the test dataset.

```python
print("Threshold corresponding to Best balanced accuracy: {:6.4f}".format(best_thresh))
show_explanation(0)
show_explanation(2)
```

--------------------------------

### Generate and Display LIME Explanations (Python)

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_medical_expenditure.ipynb

This function `show_explanation` generates LIME explanations for a given instance using the explainer and prediction function. It then prints the actual label and displays the explanation as a plot.

```python
def show_explanation(ind):
    exp = explainer.explain_instance(s_test[ind], s_predict_fn, num_features=10)
    print("Actual label: " + str(test_dataset.labels[ind]))
    exp.as_pyplot_figure()
    plt.show()
```

--------------------------------

### Initialize AIF360 Environment

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_isf.ipynb

Configures the Python path and imports necessary libraries for intersectional fairness analysis and visualization.

```python
import os
import sys
sys.path.append(os.path.abspath("../"))
%matplotlib inline
from pylab import rcParams
from aif360.algorithms.intersectional_fairness import IntersectionalFairness
from aif360.algorithms.isf_helpers.isf_utils.common import output_subgroup_metrics, convert_labels, create_multi_group_label
from aif360.algorithms.isf_helpers.isf_analysis.intersectional_bias import plot_intersectionalbias_compare
import numpy as np
import pandas as pd
```

--------------------------------

### Calculate Wasserstein Distance for Permuted Distributions (Python)

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_ot_metric.ipynb

This example demonstrates calculating the Wasserstein distance between two distributions that can be transformed into each other solely through permutations. The distributions are visualized using Matplotlib, and the distance is computed using `aif360.sklearn.metrics.ot_distance`.

```python
import numpy as np

# Initial distribution
a = np.array([0., 0.1, 0.1, 0.1, 0.08, 0., 0.1, 0.1, 0.08, 0.08, 0., 0.1, 0.08, 0.08, 0.08, 0.])
# Required distribution
b = np.array([0., 0.08, 0.08, 0.08, 0.1, 0., 0.08, 0.08, 0.1, 0.1, 0., 0.08, 0.1, 0.1, 0.1, 0.])
```

```python
import matplotlib.pyplot as plt

# Drawing both of them
figure, axis = plt.subplots(1, 2)
figure.set_figheight(4)
figure.set_figwidth(12)
figure.tight_layout(w_pad = 5)

def draw(y, id):
    x = np.array(range(0, np.size(y)))
    axis[id].bar(x, y, color="lightgreen", ec='black')
    axis[id].scatter(x, y, color="orange")

axis[0].title.set_text("Initial distribution")
axis[1].title.set_text("Required distribution")
draw(a, 0)
draw(b, 1)

plt.show()
```

```python
import pandas as pd
from aif360.sklearn.metrics import ot_distance

_a = pd.Series(a)
_b = pd.Series(b)
c = ot_distance(_a, _b, mode='continuous')

print(c)
```

--------------------------------

### Example Output: No Unfair Recourses Found

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_FACTS.ipynb

This snippet represents the output from the AIF360 library when no recourses exhibiting unfairness are found based on the given parameters and metrics. It indicates that the bias scan did not detect any significant bias.

```text
Output:\nWith the given parameters, no recourses showing unfairness have been found!\n
```

--------------------------------

### Initialize Predicted and Original Datasets

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_bias_advertising.ipynb

Demonstrates how to instantiate both predicted and ground-truth StandardDataset objects using the conversion function. It ensures labels and scores are correctly aligned for bias evaluation.

```python
ad_standard_dataset_pred = convert_to_standard_dataset(ad_conversion_dataset, 
                                            target_label_name = 'predicted_conversion',
                                            scores_name='predicted_probability')
ad_standard_dataset_orig = ad_standard_dataset_pred.copy()
ad_standard_dataset_orig.labels = ad_conversion_dataset["true_conversion"].values.reshape(-1, 1)
ad_standard_dataset_orig.scores = ad_conversion_dataset["true_conversion"].values.reshape(-1, 1)
```

--------------------------------

### Load and Prepare AdultDataset

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_isf.ipynb

Loads the AdultDataset, converts labels for compatibility, and splits the data into training and testing sets.

```python
from aif360.datasets import AdultDataset
dataset = AdultDataset()
convert_labels(dataset)
ds_train, ds_test = dataset.split([0.7])
```

--------------------------------

### Initialize Adversarial Debiasing Model (Python)

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_adversarial_debiasing.ipynb

Initializes the AdversarialDebiasing model with specified privileged and unprivileged groups, a scope name, debias set to True, and a TensorFlow session. This setup is crucial for training a model that aims to reduce bias.

```python
debiased_model = AdversarialDebiasing(privileged_groups = privileged_groups,
                          unprivileged_groups = unprivileged_groups,
                          scope_name='debiased_classifier',
                          debias=True,
                          sess=sess)
```

--------------------------------

### Data Preprocessing and Bias Scan Example

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_mdss_classifier_metric.ipynb

This code snippet demonstrates how to load a dataset (e.g., COMPAS), preprocess it by converting one-hot encoded features back to categorical ones, and then apply the bias scan algorithm to find biased subgroups.

```python
import itertools

import numpy as np
import pandas as pd

from aif360.metrics import BinaryLabelDatasetMetric, MDSSClassificationMetric
from aif360.detectors import bias_scan

from aif360.algorithms.preprocessing.optim_preproc_helpers.data_preproc_functions import load_preproc_data_compas

# Load the dataset
dataset_orig = load_preproc_data_compas()

# Define specific subgroups for potential scoring (optional)
female_group = [{'sex': 1}]
male_group = [{'sex': 0}]

# Preprocess dataset: Convert one-hot encoded features back to categorical
dataset_orig_df = pd.DataFrame(dataset_orig.features, columns=dataset_orig.feature_names)

age_cat = np.argmax(dataset_orig_df[['age_cat=Less than 25', 'age_cat=25 to 45',
                                     'age_cat=Greater than 45']].values, axis=1).reshape(-1, 1)
priors_count = np.argmax(dataset_orig_df[['priors_count=0', 'priors_count=1 to 3',
                                          'priors_count=More than 3']].values, axis=1).reshape(-1, 1)
c_charge_degree = np.argmax(dataset_orig_df[['c_charge_degree=M', 'c_charge_degree=F']].values, axis=1).reshape(-1, 1)

# Combine processed features with original categorical features (sex, race) and labels
features = np.concatenate((dataset_orig_df[['sex', 'race']].values, age_cat, priors_count,
                           c_charge_degree, dataset_orig.labels), axis=1)
feature_names = ['sex', 'race', 'age_cat', 'priors_count', 'c_charge_degree']

# Create a pandas DataFrame for easier inspection
df = pd.DataFrame(features, columns=feature_names + ['two_year_recid'])

# Display the first few rows of the preprocessed DataFrame
print(df.head())

# Example of how to use the bias_scan function (assuming 'dataset_orig' is properly prepared)
# Note: The actual bias_scan function call would depend on the specific implementation details
# and might require creating a BinaryLabelDataset object from the preprocessed data.
# For demonstration, let's assume a function call like this:
# result = bias_scan(dataset_orig, 'two_year_recid', 'sex', bias_direction='higher')
# print(result)

```

--------------------------------

### Configure and Run Deterministic Reranking

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_deterministic_reranking.ipynb

Initialize the DeterministicReranking algorithm with defined groups and execute fit_predict to generate a fair ranking based on target proportions.

```python
dr = DeterministicReranking(unprivileged_groups=[{'color': 0}], privileged_groups=[{'color': 1}])
fair_ranking = dr.fit_predict(dataset=balls_ds, rec_size=6, target_prop=[0.5, 0.5], rerank_type='Constrained')
fair_ranking.convert_to_dataframe()[0]
```

--------------------------------

### GerryFairClassifier Instantiation and Training

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_gerryfair.ipynb

Demonstrates how to instantiate a GerryFairClassifier, train it with respect to rich subgroup fairness, and predict labels. It highlights the role of parameters like C, gamma, and max_iters, and explains the print_flag for monitoring training progress.

```APIDOC
## GerryFairClassifier Instantiation and Training

### Description
This section demonstrates the instantiation and training of the `GerryFairClassifier` algorithm. It shows how to set parameters related to fairness, classification cost, and training iterations. The `fit` method is called with `early_termination=True` to allow the algorithm to stop training based on convergence criteria.

### Method
`fit`

### Endpoint
N/A (This is a library function, not a REST endpoint)

### Parameters
#### Instantiation Parameters
- **C** (int) - Required - The regularization parameter for the underlying classifier (e.g., linear regression).
- **printflag** (bool) - Optional - If True, prints error, fairness violation, and violated group size at each iteration.
- **gamma** (float) - Required - The target $\gamma$-disparity for fairness.
- **fairness_def** (str) - Required - The definition of fairness to use (e.g., 'FP' for false positive rate).
- **max_iters** (int) - Required - The maximum number of iterations for the optimization process.
- **heatmapflag** (bool) - Optional - If True, enables heatmap visualization (not used in this example).

#### Fit Method Parameters
- **dataset** (object) - Required - The dataset to train on.
- **early_termination** (bool) - Optional - If True, allows the algorithm to terminate early based on convergence.

### Request Example
```python
# Load dataset
data_set = load_preproc_data_adult(sub_samp=1000, balance=True)

# Parameters
C = 100
print_flag = True
gamma = .005
max_iterations = 500

# Instantiate the classifier
fair_model = GerryFairClassifier(C=C, printflag=print_flag, gamma=gamma, fairness_def='FP',
             max_iters=max_iterations, heatmapflag=False)

# Fit the model
fair_model.fit(data_set, early_termination=True)
```

### Response
#### Success Response (fit method)
- **fair_model** (object) - The trained GerryFairClassifier model instance.

#### Response Example
(The `fit` method typically returns `self` or `None` and modifies the model instance in place. The primary output is the trained model object.)
```json
{
  "message": "Model trained successfully."
}
```
```

--------------------------------

### POST /AdversarialDebiasing/fit

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_adversarial_debiasing.ipynb

Initializes the AdversarialDebiasing model and trains it on the provided training dataset.

```APIDOC
## POST /AdversarialDebiasing/fit

### Description
Initializes an adversarial debiasing model and executes the training process on a specified dataset to reduce bias.

### Method
POST

### Endpoint
/AdversarialDebiasing/fit

### Parameters
#### Request Body
- **privileged_groups** (list) - Required - List of dictionaries containing privileged group attributes.
- **unprivileged_groups** (list) - Required - List of dictionaries containing unprivileged group attributes.
- **scope_name** (string) - Optional - The scope name for the TensorFlow graph.
- **debias** (boolean) - Required - Set to True to enable adversarial debiasing.
- **sess** (object) - Required - The active TensorFlow session.
- **dataset_orig_train** (object) - Required - The training dataset object to fit the model.

### Request Example
{
  "privileged_groups": [{"sex": 1}],
  "unprivileged_groups": [{"sex": 0}],
  "scope_name": "debiased_classifier",
  "debias": true,
  "dataset_orig_train": "<dataset_object>"
}

### Response
#### Success Response (200)
- **status** (string) - Training completion status.
- **logs** (string) - Training epoch and iteration loss logs.

#### Response Example
{
  "status": "success",
  "logs": "epoch 26; iter: 200; batch classifier loss: 0.449761; batch adversarial loss: 0.571238"
}
```

--------------------------------

### Run FairAdapt Data Adaptation

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_fairadapt_sklearn.ipynb

Instantiates the FairAdapt class using a specified protected attribute and adjacency matrix, then performs data transformation on training and test sets.

```python
FA = FairAdapt(prot_attr="sex", adj_mat=adj_mat)
Xf_train, yf_train, Xf_test = FA.fit_transform(X_train, y_train, X_test)
```

--------------------------------

### Configure and Train SenSeI Model

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_sensei_infairness.ipynb

Sets up the SenSeI model architecture with specified hyperparameters and trains it on the provided dataset. The class integrates with skorch for a standard training workflow.

```python
rho = 2.5
eps = 0.1
auditor_nsteps = 100
auditor_lr = 1e-3

network_fair = SenSeI(
    Model,
    module__input_size=input_size,
    module__output_size=output_size,
    distance_x=distance_x,
    distance_y=distance_y,
    rho=rho,
    eps=eps,
    auditor_nsteps=auditor_nsteps,
    auditor_lr=auditor_lr,
    max_epochs=EPOCHS,
    criterion=criterion,
    optimizer=optimizer,
    lr=lr,
    device=device,
    iterator_train__shuffle=True,
)

network_fair.fit(X_train, y_train)
```

--------------------------------

### Configure Fairness Metric Parameters

Source: https://github.com/trusted-ai/aif360/blob/main/examples/tutorial_bias_advertising.ipynb

Sets up the configuration for bias mitigation, including the selection of a fairness metric and defining acceptable bounds for that metric.

```python
metric_name = "Statistical parity difference"
metric_ub = 0.05
metric_lb = -0.05
np.random.seed(1)
allowed_metrics = ["Statistical parity difference", "Average odds difference", "Equal opportunity difference"]
if metric_name not in allowed_metrics:
    raise ValueError("Metric name should be one of allowed metrics")
```

--------------------------------

### Initialize Grid Search Reduction for Fair Regression

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_grid_search_reduction_regression_sklearn.ipynb

Initializes the GridSearchReduction estimator from Fairlearn for fair regression. It configures the search with a specified base estimator, fairness constraints (BoundedGroupLoss), loss function ('Absolute'), and range for target values, along with grid search parameters.

```python
estimator = TransformedTargetRegressor(LinearRegression(), transformer=scaler)
```

```python
np.random.seed(0) #need for reproducibility
grid_search_red = GridSearchReduction(prot_attr="race",
                                      estimator=estimator,
                                      constraints="BoundedGroupLoss",
                                      loss="Absolute",
                                      min_val=y_train.min(),
                                      max_val=y_train.max(),
                                      grid_size=10,
                                      drop_prot_attr=True)
grid_search_red.fit(X_train, y_train)
gs_pred = grid_search_red.predict(X_test)
```

--------------------------------

### Initialize and Import AIF360 LFR Environment

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_lfr.ipynb

Sets up the necessary environment by importing AIF360 modules, scikit-learn utilities, and helper functions required for the LFR algorithm workflow.

```python
import sys
sys.path.append("../")
from aif360.datasets import BinaryLabelDataset, AdultDataset
from aif360.metrics import BinaryLabelDatasetMetric, ClassificationMetric
from aif360.algorithms.preprocessing.lfr import LFR
from sklearn.linear_model import LogisticRegression
from sklearn.preprocessing import StandardScaler
from common_utils import compute_metrics
```

--------------------------------

### Download Adult Dataset

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_lime.ipynb

This snippet demonstrates how to download the adult dataset from a specified URL. It checks for the existence of required files and initiates a download if any are missing. Dependencies include the 'os' module.

```python
import os

data_source_directory = "https://archive.ics.uci.edu/ml/machine-learning-databases/adult/"
destn = os.path.join(LIB_PATH, "aif360", "data", "raw", "adult")
files = ["adult.data", "adult.test", "adult.names"]

check_data_or_download(destn, files, data_source_directory)
```

--------------------------------

### Initialize and Fit Reject Option Classification

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_reject_option_classification.ipynb

Initializes the RejectOptionClassification class with specified thresholds and margins, then fits the model to the validation dataset to find optimal parameters.

```python
ROC = RejectOptionClassification(unprivileged_groups=unprivileged_groups, 
                                 privileged_groups=privileged_groups, 
                                 low_class_thresh=0.01, high_class_thresh=0.99,
                                  num_class_thresh=100, num_ROC_margin=50,
                                  metric_name=metric_name,
                                  metric_ub=metric_ub, metric_lb=metric_lb)
ROC = ROC.fit(dataset_orig_valid, dataset_orig_valid_pred)
print("Optimal classification threshold (with fairness constraints) = %.4f" % ROC.classification_threshold)
print("Optimal ROC margin = %.4f" % ROC.ROC_margin)
```

--------------------------------

### Load and Prepare Adult Dataset

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_exponentiated_gradient_reduction_sklearn.ipynb

Loads the Adult dataset using aif360's fetch_adult function. It then preprocesses the 'race' feature, maps protected attributes and target classes to integers, and splits the data into training and testing sets. This preparation ensures compatibility with scikit-learn models.

```python
X, y, sample_weight = fetch_adult()
X.race = X.race.cat.set_categories(['Non-white', 'White'], ordered=True).fillna('Non-white')
X.index = pd.MultiIndex.from_arrays(X.index.codes, names=X.index.names)
y.index = pd.MultiIndex.from_arrays(y.index.codes, names=y.index.names)
y = pd.Series(y.factorize(sort=True)[0], index=y.index)
(X_train, X_test,
y_train, y_test) = train_test_split(X, y, train_size=0.7, random_state=1234567)
```

--------------------------------

### Load and Prepare Adult Dataset

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_new_features.ipynb

Fetches the Adult dataset and performs necessary preprocessing steps including mapping protected attributes to integers and encoding target classes. This prepares the data for integration with scikit-learn pipelines.

```python
from aif360.sklearn.datasets import fetch_adult
import pandas as pd

X, y, sample_weight = fetch_adult()
X.index = pd.MultiIndex.from_arrays(X.index.codes, names=X.index.names)
y.index = pd.MultiIndex.from_arrays(y.index.codes, names=y.index.names)
y = pd.Series(y.factorize(sort=True)[0], index=y.index)
```

--------------------------------

### Data Preparation and Model Training

Source: https://github.com/trusted-ai/aif360/blob/main/examples/sklearn/demo_new_features.ipynb

Demonstrates loading data, training a logistic regression model, and making predictions.

```APIDOC
## Data Preparation and Model Training

### Description
This section shows how to load data, train a logistic regression model, and generate predictions on test data.

### Method
N/A (Illustrative Code)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
y_pred = LogisticRegression(solver='liblinear').fit(X_train, y_train).predict(X_test)
accuracy_score(y_test, y_pred)
```

### Response
#### Success Response (200)
Returns the accuracy score of the model.

#### Response Example
```
0.8455074813886637
```
```

--------------------------------

### Load Data and Initialize GerryFairClassifier in Python

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_gerryfair.ipynb

This snippet loads the adult dataset and initializes the GerryFairClassifier. It sets parameters such as cost (C), print flag, gamma for disparity, fairness definition (FP), and maximum iterations. The classifier is then trained using the loaded dataset with early termination enabled.

```python
%matplotlib inline
import warnings
warnings.filterwarnings("ignore")
import sys
sys.path.append("../")
from aif360.algorithms.inprocessing import GerryFairClassifier
from aif360.algorithms.inprocessing.gerryfair.clean import array_to_tuple
from aif360.algorithms.inprocessing.gerryfair.auditor import Auditor
from aif360.algorithms.preprocessing.optim_preproc_helpers.data_preproc_functions import load_preproc_data_adult
from sklearn import svm
from sklearn import tree
from sklearn.kernel_ridge import KernelRidge
from sklearn import linear_model
from aif360.metrics import BinaryLabelDatasetMetric
from IPython.display import Image
import pickle
import matplotlib.pyplot as plt

# load data set
data_set = load_preproc_data_adult(sub_samp=1000, balance=True)
max_iterations = 500

C = 100
print_flag = True
gamma = .005


fair_model = GerryFairClassifier(C=C, printflag=print_flag, gamma=gamma, fairness_def='FP',
             max_iters=max_iterations, heatmapflag=False)

# fit method
fair_model.fit(data_set, early_termination=True)
```

--------------------------------

### Create and Activate Conda Virtual Environment

Source: https://github.com/trusted-ai/aif360/blob/main/README.md

This snippet demonstrates how to create a new Conda virtual environment for Python 3.11 and activate it. This is recommended for managing AIF360 dependencies.

```bash
conda create --name aif360 python=3.11
conda activate aif360
```

--------------------------------

### Load AI Fairness 360 Packages and Dataset

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_json_explainers.ipynb

Imports necessary libraries from AI Fairness 360 and Python's standard library, then loads the German dataset.

```python
# Load all necessary packages
import sys
sys.path.append("../")
from collections import OrderedDict
import json
from pprint import pprint
from aif360.datasets import GermanDataset
from aif360.metrics import BinaryLabelDatasetMetric
from aif360.explainers import MetricTextExplainer, MetricJSONExplainer
from IPython.display import JSON, display_json

gd = GermanDataset()
```

--------------------------------

### Configure Dataset and Fairness Parameters

Source: https://github.com/trusted-ai/aif360/blob/main/examples/demo_calibrated_eqodds_postprocessing.ipynb

Selects the target dataset and defines privileged/unprivileged groups based on protected attributes. Sets the cost constraint parameter for the post-processing algorithm.

```python
dataset_used = "adult"
protected_attribute_used = 1
if dataset_used == "adult":
    dataset_orig = AdultDataset()
    privileged_groups = [{'sex': 1}]
    unprivileged_groups = [{'sex': 0}]
cost_constraint = "fnr"
randseed = 12345679
```