binary_credit_card.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Binary Classification with the UCI Credit-card Default Dataset\n",
    "_**Mitigating disparities in accuracy as measured by equalized-odds difference**_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Contents\n",
    "\n",
    "1. [What is Covered](#What-is-Covered)\n",
    "1. [Introduction](#Introduction)\n",
    "1. [The UCI Credit-card Default Dataset](#The-UCI-Credit-card-Default-Dataset)\n",
    "1. [Using a Fairness Unaware Model](#Using-a-Fairness-Unaware-Model)\n",
    "1. [Mitigating Equalized Odds Difference with Postprocessing](#Mitigating-Equalized-Odds-Difference-with-Postprocessing)\n",
    "1. [Mitigating Equalized Odds Difference with GridSearch](#Mitigating-Equalized-Odds-Difference-with-GridSearch)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What is Covered\n",
    "\n",
    "* **Domain:**\n",
    "  * Finance (loan decisions). The data is semisynthetic to create a simple example of disparity in accuracy.\n",
    "\n",
    "* **ML task:**\n",
    "  * Binary classification.\n",
    "\n",
    "* **Fairness tasks:**\n",
    "  * Assessment of unfairness using Fairlearn metrics and Fairlearn dashboard.\n",
    "  * Mitigation of unfairness using Fairlearn mitigation algorithms.\n",
    "\n",
    "* **Performance metrics:**\n",
    "  * Area under ROC curve.\n",
    "  * Balanced accuracy.\n",
    "\n",
    "* **Fairness metrics:**\n",
    "  * Equalized-odds difference.\n",
    "\n",
    "* **Mitigation algorithms:**\n",
    "  * `fairlearn.reductions.GridSearch`\n",
    "  * `fairlearn.postprocessing.ThresholdOptimizer`\n",
    "\n",
    "## Introduction\n",
    "\n",
    "In this example, we emulate the problem of accuracy disparities arising in loan decisions. Specifically, we consider scenarios where algorithmic tools are trained on historic data and their predictions about loan applicants are used for making decisions about applicants. See [here](https://www.nytimes.com/2019/11/10/business/Apple-credit-card-investigation.html) for an example involving sex-based discrimination for credit limit decisions.  \n",
    "\n",
    "We use the [UCI dataset](https://archive.ics.uci.edu/ml/datasets/default+of+credit+card+clients) on credit-card defaults in 2005 in Taiwan. For the sake of this exercise, we modify the original UCI dataset: we introduce a synthetic feature that has a strong predictive power for female clients, but is uninformative for male applicants. We fit a variety of models for predicting the default of a client. We show that a fairness-unaware training algorithm can lead to a predictor that achieves a much better accuracy for women than for men, and that it is insufficient to simply remove the sensitive feature (in this case sex) from training. We then use Fairlearn to mitigate this disparity in accuracy with either `ThresholdOptimizer` or `GridSearch`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# General imports\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "\n",
    "# Data processing\n",
    "from sklearn.model_selection import train_test_split\n",
    "\n",
    "# Models\n",
    "import lightgbm as lgb\n",
    "from sklearn.calibration import CalibratedClassifierCV\n",
    "\n",
    "# Fairlearn algorithms and utils\n",
    "from fairlearn.postprocessing import ThresholdOptimizer\n",
    "from fairlearn.reductions import GridSearch, EqualizedOdds\n",
    "from fairlearn.widget import FairlearnDashboard\n",
    "\n",
    "# Metrics\n",
    "from fairlearn.metrics import (\n",
    "    selection_rate, demographic_parity_difference, demographic_parity_ratio,\n",
    "    balanced_accuracy_score_group_summary, roc_auc_score_group_summary,\n",
    "    equalized_odds_difference, difference_from_summary)\n",
    "from sklearn.metrics import balanced_accuracy_score, roc_auc_score"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The UCI Credit-card Default Dataset\n",
    "\n",
    "The UCI dataset contains data on 30,000 clients and their credit card transactions at a bank in Taiwan. In addition to static client features, the dataset contains the history of credit card bill payments between April and September 2005, as well as the balance limit of the client's credit card. The target is whether the client will default on a card payment in the following month, October 2005. One can imagine that a model trained on this data can be used in practice to determine whether a client is eligible for another product such as an auto loan. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>LIMIT_BAL</th>\n",
       "      <th>SEX</th>\n",
       "      <th>EDUCATION</th>\n",
       "      <th>MARRIAGE</th>\n",
       "      <th>AGE</th>\n",
       "      <th>PAY_1</th>\n",
       "      <th>PAY_2</th>\n",
       "      <th>PAY_3</th>\n",
       "      <th>PAY_4</th>\n",
       "      <th>PAY_5</th>\n",
       "      <th>...</th>\n",
       "      <th>BILL_AMT4</th>\n",
       "      <th>BILL_AMT5</th>\n",
       "      <th>BILL_AMT6</th>\n",
       "      <th>PAY_AMT1</th>\n",
       "      <th>PAY_AMT2</th>\n",
       "      <th>PAY_AMT3</th>\n",
       "      <th>PAY_AMT4</th>\n",
       "      <th>PAY_AMT5</th>\n",
       "      <th>PAY_AMT6</th>\n",
       "      <th>default payment next month</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>20000</td>\n",
       "      <td>2</td>\n",
       "      <td>2</td>\n",
       "      <td>1</td>\n",
       "      <td>24</td>\n",
       "      <td>2</td>\n",
       "      <td>2</td>\n",
       "      <td>-1</td>\n",
       "      <td>-1</td>\n",
       "      <td>-2</td>\n",
       "      <td>...</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>689</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>120000</td>\n",
       "      <td>2</td>\n",
       "      <td>2</td>\n",
       "      <td>2</td>\n",
       "      <td>26</td>\n",
       "      <td>-1</td>\n",
       "      <td>2</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>...</td>\n",
       "      <td>3272</td>\n",
       "      <td>3455</td>\n",
       "      <td>3261</td>\n",
       "      <td>0</td>\n",
       "      <td>1000</td>\n",
       "      <td>1000</td>\n",
       "      <td>1000</td>\n",
       "      <td>0</td>\n",
       "      <td>2000</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>90000</td>\n",
       "      <td>2</td>\n",
       "      <td>2</td>\n",
       "      <td>2</td>\n",
       "      <td>34</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>...</td>\n",
       "      <td>14331</td>\n",
       "      <td>14948</td>\n",
       "      <td>15549</td>\n",
       "      <td>1518</td>\n",
       "      <td>1500</td>\n",
       "      <td>1000</td>\n",
       "      <td>1000</td>\n",
       "      <td>1000</td>\n",
       "      <td>5000</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>50000</td>\n",
       "      <td>2</td>\n",
       "      <td>2</td>\n",
       "      <td>1</td>\n",
       "      <td>37</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>...</td>\n",
       "      <td>28314</td>\n",
       "      <td>28959</td>\n",
       "      <td>29547</td>\n",
       "      <td>2000</td>\n",
       "      <td>2019</td>\n",
       "      <td>1200</td>\n",
       "      <td>1100</td>\n",
       "      <td>1069</td>\n",
       "      <td>1000</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>50000</td>\n",
       "      <td>1</td>\n",
       "      <td>2</td>\n",
       "      <td>1</td>\n",
       "      <td>57</td>\n",
       "      <td>-1</td>\n",
       "      <td>0</td>\n",
       "      <td>-1</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>...</td>\n",
       "      <td>20940</td>\n",
       "      <td>19146</td>\n",
       "      <td>19131</td>\n",
       "      <td>2000</td>\n",
       "      <td>36681</td>\n",
       "      <td>10000</td>\n",
       "      <td>9000</td>\n",
       "      <td>689</td>\n",
       "      <td>679</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5 rows × 24 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "   LIMIT_BAL  SEX  EDUCATION  MARRIAGE  AGE  PAY_1  PAY_2  PAY_3  PAY_4  \\\n",
       "0      20000    2          2         1   24      2      2     -1     -1   \n",
       "1     120000    2          2         2   26     -1      2      0      0   \n",
       "2      90000    2          2         2   34      0      0      0      0   \n",
       "3      50000    2          2         1   37      0      0      0      0   \n",
       "4      50000    1          2         1   57     -1      0     -1      0   \n",
       "\n",
       "   PAY_5  ...  BILL_AMT4  BILL_AMT5  BILL_AMT6  PAY_AMT1  PAY_AMT2  PAY_AMT3  \\\n",
       "0     -2  ...          0          0          0         0       689         0   \n",
       "1      0  ...       3272       3455       3261         0      1000      1000   \n",
       "2      0  ...      14331      14948      15549      1518      1500      1000   \n",
       "3      0  ...      28314      28959      29547      2000      2019      1200   \n",
       "4      0  ...      20940      19146      19131      2000     36681     10000   \n",
       "\n",
       "   PAY_AMT4  PAY_AMT5  PAY_AMT6  default payment next month  \n",
       "0         0         0         0                           1  \n",
       "1      1000         0      2000                           1  \n",
       "2      1000      1000      5000                           0  \n",
       "3      1100      1069      1000                           0  \n",
       "4      9000       689       679                           0  \n",
       "\n",
       "[5 rows x 24 columns]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Load the data\n",
    "data_url = \"http://archive.ics.uci.edu/ml/machine-learning-databases/00350/default%20of%20credit%20card%20clients.xls\"\n",
    "dataset = pd.read_excel(io=data_url, header=1).drop(columns=['ID']).rename(columns={'PAY_0':'PAY_1'})\n",
    "dataset.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dataset columns:\n",
    "\n",
    "* `LIMIT_BAL`: credit card limit, will be replaced by a synthetic feature\n",
    "* `SEX, EDUCATION, MARRIAGE, AGE`: client demographic features\n",
    "* `BILL_AMT[1-6]`: amount on bill statement for April-September\n",
    "* `PAY_AMT[1-6]`: payment amount for April-September\n",
    "* `default payment next month`: target, whether the customer defaulted the following month"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Extract the sensitive feature\n",
    "A = dataset[\"SEX\"]\n",
    "A_str = A.map({ 2:\"female\", 1:\"male\"})\n",
    "# Extract the target\n",
    "Y = dataset[\"default payment next month\"]\n",
    "categorical_features = ['EDUCATION', 'MARRIAGE','PAY_1', 'PAY_2', 'PAY_3', 'PAY_4', 'PAY_5', 'PAY_6']\n",
    "for col in categorical_features:\n",
    "    dataset[col] = dataset[col].astype('category')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Introduce a Synthetic Feature\n",
    "\n",
    "We manipulate the balance-limit feature `LIMIT_BAL` to make it highly predictive for women but not for men. For example, we can imagine that a lower credit limit indicates that a female client is less likely to default, but provides no information on a male client's probability of default."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "dist_scale = 0.5\n",
    "np.random.seed(12345)\n",
    "# Make 'LIMIT_BAL' informative of the target\n",
    "dataset['LIMIT_BAL'] = Y + np.random.normal(scale=dist_scale, size=dataset.shape[0])\n",
    "# But then make it uninformative for the male clients\n",
    "dataset.loc[A==1, 'LIMIT_BAL'] = np.random.normal(scale=dist_scale, size=dataset[A==1].shape[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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yAjccccdRV/5ylcKv/nNb7YD5OXl+Q4ePHjo7rvvzr/77rsLf/SjH5284YYbPOnp6f6dO3d2To/3c5/7XMnGjRtHfv3rXx/ftWuX+2Mf+1hVQ0PDQYBjx44lv/TSS4f7+/uddXV16z772c96kpKS5jzxfOTIkZR9+/YdHB0ddaxZs2bd3/3d37UeOnTo4Cc/+ckV999/f+6OHTu6brrppooHHnjg5Pr168efffbZtFtuuaX8d7/73ZFwx7A1oVcqopp+w4Arh2ZWce2mMgA+dmEFD754gq8er+aRog3whwdg041aT6+Uirh/f+44X/9FA4lOB9+4dgMffMf0xm1KLV/j4+OO2traeoALLrhg8Lbbbuvev39/8gc/+MEyj8eTMDEx4VixYsU4wC233NJ9zTXXrN6xY0fXww8/nHfjjTd2h85z1VVX9TscDs4///yR3NzcyS1btowC1NTUjB4/fjzp5MmTicePH0/esmVLLcDk5KRs2rRpKPT8D3/4w30AW7ZsGdm1a1f2bHH/4Q9/cP/kJz85BnDNNdcM3nzzza7e3l4HwOWXX96fkpJiUlJSfDk5OZMtLS2uVatWzbkbx4UXXjiYnZ0dyM7ODqSnp/uvu+66foD169eP7N+/P9Xr9Tr27t2bft11160KPWdiYmJOiYwm9GppMIZA02/47eQa3r+xhOQEJwCpiS4+eVEV//jMYdr+7M8p+e0d4GmAgroYB6yUiievnerjG880cHl9If2jk3z2x/tYlZ/O+rLMWIem1BnCnUmPtFAN/dT7br311vLbbrut4/rrr/fu3r3bvXPnzhKA1atXT+bl5fl27drlfv3119OefPLJ0/XmycnJBsDpdJKYmHh6NtzhcODz+cTpdJqLLrpo4KmnnmqcKY7Q810ul/H5fAua3Zs6G+90Opnv+aa/jlCModfk9/txu92+6b+/uYh120qlwtN/CsdgGy/51nDV+pIzHvroOytwJ7m4r7XauuPIMzEIUCkVz+579hg5qYn805+fxwMf3URuWhJffvINAgFd9qXU2QwODjrLy8snAR599NHcqY994hOf8Nx0001VV199da/LFf788iWXXDK8Z8+e9DfffDMJYGBgwLF///5z1sC53W7/4OCgc6bHLrjggsFHHnkkF6xuONnZ2b6cnJyodufJyckJlJWVTTz88MPZAIFAgJdffjllLufQhF4tDW17ATjoqGFz5ZmfoGUkJ3DDhRU8ftjHeG4dnHguBgEqpeJVY/cw/93QxUf+uIK0JBdZqYl87oo17Gvx8tR+GzY4b98P910A/7wBjv4q8udXKkruuOOOtu3bt69au3ZtXW5u7hldK7Zv3+4dGRlx3nzzzT1zOWdJSYnv/vvvb9q2bdvKmpqa+s2bN9e+8cYb51xAunXr1v6f//znWTMtiv3617/etnfv3tSampr6O+64o/TRRx+dcebfbj/4wQ9OPPLII3lr1qypr66uXvuTn/wkay7Pl6XWVGbz5s1mz549sQ5DRdv/fI3A81/nU2VP8Z2bLn7bw91D47zr7md5tOAHvHP4f+DzJ8Ghf6/GCxF51RizOdZxLJRev5amr/3XIb7zYiMvffFPKXBbeUMgYHjfvS8SMIZnPv0nSKTW7UwMw78G/6knZ0Lvcbj5OShcG5nzq6iLxvVr3759TRs3buye/cjF44UXXki9/fbbV7z66quHYx3LUrFv3768jRs3Vs70mGY8akkYbX2DpkAh71wz8yK0vPQktv3RCn7aVQzjA1YdvVJKLZAxht372rm4Ou90Mg/gcAifunglRzqHeP5IBLdPeeU7MNgG1z0CN+62kvpdfw1LbPJNqXP50pe+VLRt27ZVd9111/QNR9U8aUKvlgR/+5scNit456rcsx7zqT9Zyf5AcIF4x/4oRaaUimevneqntX+UqzeWvO2xqzeWkO9O4vu/OxmZwYyB1/8frLgAyv8Y0vLgz3ZA66u6NkjFlbvuuqujra3tjfe+971Dsx+twqEJvVr8JkdJGz7FcSlnTaH7rIeVZaeybsP5TBgX421vRjFApVS82r2/jUSXg8vqC9/2WKLLwf96RynPHfbQOzyx8ME69lufLm7c9tZ9G7dDVgW8+K2Fn18pFbc0oVeLn6cBwTCavQaX89z/ZD/6rtUcNyX0nHg9SsEppeKVP2D4+f52LqnJx52cMOMxHzyvFF/A8Is3OxY+4LFfW99rr37rPmcCbLkZWv4AnfPuaKeUinOa0KtFz99lbZSWVlo/67EbyzJpSagksVfX2CilFub15n66Bse5akPxWY+pK3ZTmpXC80e6Fj7gieegcD2k5595/8bt4EyE17678DGUUnFJE3q16PW2Wsl52crZE3oRwVW8ljx/F2NDfXaHppSKY88d7sIhcElNwVmPEREurs7jpWM9+PwLaF09OQqnfgcr3/32x9Jyoe4a2PdD8M95k0ql1DKgCb1a9Ibaj9NhsllX8fYa1pnkVlrt3Q4f1LIbpdT8PdvQxaaKbDJTZy63Cbm4Op/BcR/7W73zH6zjDfBPQPk7Z3583VYY64emF+c/hlI2cjqdm2pra+urq6vXXnnllSsHBwcXTY65e/du969+9au0mR679957c7OzszfW1dXVV1RUrLvooouqz3bsVG1tba4NGzbU1tXVva23fTjuvffe3BtuuKEc4Hvf+17Wq6++es5e+rNZNL9spc6qr5FWKaQyd9b/vwBYWbMegJbjWm+qlJqfzoExDrQN8J7as8/Oh2yqsDa729/cP/8BW1+zvpeeP/Pjq94DCWlw6Kn5j6GUjZKSkgINDQ0Hjx49eiAhIcF861vfyp/9WdHx7LPPul988cWzJt1XX31136FDhw6ePHnyzc9//vMd27dvX/3aa6+dM8HevXu3u66ubvTQoUMHr7jiigV163nyySez9u/fP6edYafThF4tehkjLQylrsDhCG/jlvTC1QCMe07YGZZSKo69EOwtf65ym5DCjCTy0pN4o3Vg/gO2vQbpRZDx9vaYACSkQPVlcGg3BPzzH0epKLjooouGjh07lvT4449nhmaxL7zwwprm5maX3++noqJiXVtbmwvA7/dTXl6+rq2tzbV169bK66+/vnzjxo21ZWVl63fv3u2+7rrrKleuXLl269atlaHz//SnP80477zzauvr6+uuvPLKlV6v1wFQWlq6/vbbby+pr6+vq6mpqd+7d2/y4cOHEx977LH8b3/724Uz7RQ73dVXXz34kY98xHPfffflAxw4cCDp4osvrl67dm3dpk2b1uzduzf5pZdeSvn7v//7sl/+8pdZtbW19UNDQ3L99deXr1u3rm716tVrb7/99tP/I5eWlq5vb293gbWZ1pYtW9ZMHe9Xv/pV2q9//eusL3/5y2W1tbX1Bw4cSJrP79w1nycpFS3jo0Pkmh4kpyr8JyWlM+DMJsEbod7QSqll5w+NvWSlJlBbdPZWuSEiwrrSDA60LaDkpvU1KN107mNqr4KDT0L767Mfq5avJ/9qBV0HUyN6zoL6ET54X3M4h05OTvLMM89kXH755QOXXXbZ0LZt2xocDgf33HNP3s6dO4sefPDBlmuvvbbnoYceytmxY0fXz372s4y6urrRkpISH4DX63Xt3bu34fHHH8/atm3b6meffbZh06ZNoxs2bKh76aWXUqqqqibvuuuu4hdeeOFIRkZG4I477ij6yle+UvjNb36zHSAvL8938ODBQ3fffXf+3XffXfijH/3o5A033OBJT0/379y5szOc17Bp06aRBx98MB/gpptuqnjggQdOrl+/fvzZZ59Nu+WWW8p/97vfHfniF7/YtmfPnrTHHnvsFMA999zTWlhY6Pf5fFx44YVrfv/736dccMEFo7ONddlllw1feuml/e9///u9H//4x+e9+E8TerWoNR49SC2QUVw9p+cNp60gt6+VwbHJs7abU0qps3mlqZfNFTlhfzK4vjSTF492MzbpJznBObfBxgeh5yhs+PNzH1cVXDDb+KIm9GrRGR8fd9TW1tYDXHDBBYO33XZb9/79+5M/+MEPlnk8noSJiQnHihUrxgFuueWW7muuuWb1jh07uh5++OG8G2+8sTt0nquuuqrf4XBw/vnnj+Tm5k5u2bJlFKCmpmb0+PHjSSdPnkw8fvx48pYtW2oBJicnZdOmTadLXj784Q/3AWzZsmVk165d2fN5LSa4M7PX63Xs3bs3/brrrlsVemxiYmLGi8J3v/vdnEcffTTP5/OJx+NJ2LdvX3I4CX2k2JrQi8gVwL8ATuAhY8zd0x7/J+A9wZupQIExJsvOmNTS0t5oJfQlK9fO6Xkmu5Jy70sc6Rw6Xd+qlFLh6Boco6lnhA9fUB72c2oK3fgDhsbuYeqKM+Y2YLfVmpfCWTp5uQshvxYaX4CLPj23MdTyEeZMeqSFauin3nfrrbeW33bbbR3XX3+9d/fu3e6dO3eWAKxevXoyLy/Pt2vXLvfrr7+e9uSTT56ukU1OTjYATqeTxMREE7rf4XDg8/nE6XSaiy66aOCpp55qnCmO0PNdLpfx+Xzh/UU+zWuvvZZaU1Mz6vf7cbvdvumva7qGhobEf/u3fyt89dVXD+Xn5/u3bt1aOTY25gi+DhMIWB2wRkdHbSt1t+3EIuIE7gOuBOqB7SJyxtXKGHO7MeY8Y8x5wL8CP7UrHrU0DbQfBSC/fM0sR54pOX8lJfTQ6lnAIjWl1LL0SqP1qfeWqtywn1OVZy3ab+oenvuAnuC+GXlhXOcqL4ZTL4MvAjvTKmWzwcFBZ3l5+STAo48+esb/UJ/4xCc8N910U9XVV1/d63KFP798ySWXDO/Zsyf9zTffTAIYGBhw7N+//5x152632z84OBjWR2c///nP07///e/n/+Vf/mV3Tk5OoKysbOLhhx/OBggEArz88stvW7za19fnTElJCeTk5Pibm5tdzz33XGbosbKysonf/va3qQBPPPHEjDOM6enp/oGBgQXl5HYuit0CHDPGnDDGTAA/BD5wjuO3Az+wMR61BJneRkYlFUkN/40VIL24BocY+tqP2xSZUipevdLUS0qCk7Ul4c+0VwYT+saeeSb0zkTIrpz92IoLYXIEOt+Y+zhKRdkdd9zRtn379lVr166ty83N9U19bPv27d6RkRHnzTff3DOXc5aUlPjuv//+pm3btq2sqamp37x5c+0bb7xxzo40W7du7f/5z3+edbZFsU899VR2bW1tfWVl5bqvfe1rxY8//vix888/fwzgBz/4wYlHHnkkb82aNfXV1dVrf/KTn7ytkuSd73zn6Lp160ZWrVq17kMf+tDKqSVAO3bsaPvc5z5Xvm7dujqn02mmPxfg+uuv77333nuL6urq5r0oVkJ1QpEmItcCVxhjbgre/ihwgTHm1hmOrQB+B5QZY962fF9EbgZuBigvL9908qQudlwOhsd9/OGrf8bajBEKPvvK3J7c9Bt49Cq+XX4Pf/GJT9oToIoaEXnVGLM51nHMh16/lp5r//0lROA//uLCOT1v81d/zZ/W5vONazfObcDHt0H/SfjLl2c/tu8k/MsGeN83Ycun5jaOioloXL/27dvXtHHjxu7Zj1w8XnjhhdTbb799xauvvqpbu4dp3759eRs3bqyc6bHF0rZyG/DjmZJ5AGPMA8aYzcaYzfn5i6atqbLZgbYByqUTsufQ4SYkoxSAQH9LhKNSam70+rW0+AOGg+0DrC3JnP3gaVbmpdE4n5Kb7sOQVxPesVnlkJoHbXvnPo5Si8SXvvSlom3btq266667WmMdS7ywM6FvBVZMuV0WvG8m29ByGzXNG809lImH9Dl2uAFO93J2DbdFOCqlVDxr7B5iZMLPutK5J/SVeak09YzM7UmTY9DXZC12DYeItflUaCMqpZagu+66q6Otre2N9773vQvakEm9xc6E/hWgWkSqRCQRK2nfNf0gEakFsoEwPmtUy0lT0wmSxEdqcKOoOXElMZyQi3u8k7FJ3YRFKRWeN4ObQ60r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\n",
      "text/plain": [
       "<Figure size 720x288 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(10, 4), sharey=True)\n",
    "# Plot distribution of LIMIT_BAL for men\n",
    "dataset['LIMIT_BAL'][(A==1) & (Y==0)].plot(kind='kde', label=\"Payment on Time\", ax=ax1, \n",
    "                                           title=\"LIMIT_BAL distribution for men\")\n",
    "dataset['LIMIT_BAL'][(A==1) & (Y==1)].plot(kind='kde', label=\"Payment Default\", ax=ax1)\n",
    "# Plot distribution of LIMIT_BAL for women\n",
    "dataset['LIMIT_BAL'][(A==2) & (Y==0)].plot(kind='kde', label=\"Payment on Time\", ax=ax2, \n",
    "                                           legend=True, title=\"LIMIT_BAL distribution for women\")\n",
    "dataset['LIMIT_BAL'][(A==2) & (Y==1)].plot(kind='kde', label=\"Payment Default\", ax=ax2, \n",
    "                                           legend=True).legend(bbox_to_anchor=(1.6, 1))\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We notice from the above figures that the new `LIMIT_BAL` feature is indeed highly predictive for women, but not for men."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Train-test split\n",
    "df_train, df_test, Y_train, Y_test, A_train, A_test, A_str_train, A_str_test = train_test_split(\n",
    "    dataset.drop(columns=['SEX', 'default payment next month']), \n",
    "    Y, \n",
    "    A, \n",
    "    A_str,\n",
    "    test_size = 0.3, \n",
    "    random_state=12345,\n",
    "    stratify=Y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using a Fairness Unaware Model"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We train an out-of-the-box `lightgbm` model on the modified data and assess several disparity metrics. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "lgb_params = {\n",
    "    'objective' : 'binary',\n",
    "    'metric' : 'auc',\n",
    "    'learning_rate': 0.03,\n",
    "    'num_leaves' : 10,\n",
    "    'max_depth' : 3\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "model = lgb.LGBMClassifier(**lgb_params)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LGBMClassifier(learning_rate=0.03, max_depth=3, metric='auc', num_leaves=10,\n",
       "               objective='binary')"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.fit(df_train, Y_train)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Scores on test set\n",
    "test_scores = model.predict_proba(df_test)[:, 1]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.8500361298806519"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Train AUC\n",
    "roc_auc_score(Y_train, model.predict_proba(df_train)[:, 1])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Predictions (0 or 1) on test set\n",
    "test_preds = (test_scores >= np.mean(Y_train)) * 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# LightGBM feature importance \n",
    "lgb.plot_importance(model, height=0.6, title=\"Features importance (LightGBM)\", importance_type=\"gain\", max_num_features=15) \n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We notice that the synthetic feature `LIMIT_BAL` appears as the most important feature in this model although it has no predictive power for an entire demographic segment in the data. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Helper functions\n",
    "def get_metrics_df(models_dict, y_true, group):\n",
    "    metrics_dict = {\n",
    "        \"Overall selection rate\": (\n",
    "            lambda x: selection_rate(y_true, x), True),\n",
    "        \"Demographic parity difference\": (\n",
    "            lambda x: demographic_parity_difference(y_true, x, sensitive_features=group), True),\n",
    "        \"Demographic parity ratio\": (\n",
    "            lambda x: demographic_parity_ratio(y_true, x, sensitive_features=group), True),\n",
    "        \"-----\": (lambda x: \"\", True),\n",
    "        \"Overall balanced error rate\": (\n",
    "            lambda x: 1-balanced_accuracy_score(y_true, x), True),\n",
    "        \"Balanced error rate difference\": (\n",
    "            lambda x: difference_from_summary(\n",
    "                balanced_accuracy_score_group_summary(y_true, x, sensitive_features=group)), True),\n",
    "        \"Equalized odds difference\": (\n",
    "            lambda x: equalized_odds_difference(y_true, x, sensitive_features=group), True),\n",
    "        \"------\": (lambda x: \"\", True),\n",
    "        \"Overall AUC\": (\n",
    "            lambda x: roc_auc_score(y_true, x), False),\n",
    "        \"AUC difference\": (\n",
    "            lambda x: difference_from_summary(\n",
    "                roc_auc_score_group_summary(y_true, x, sensitive_features=group)), False),\n",
    "    }\n",
    "    df_dict = {}\n",
    "    for metric_name, (metric_func, use_preds) in metrics_dict.items():\n",
    "        df_dict[metric_name] = [metric_func(preds) if use_preds else metric_func(scores) \n",
    "                                for model_name, (preds, scores) in models_dict.items()]\n",
    "    return pd.DataFrame.from_dict(df_dict, orient=\"index\", columns=models_dict.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We calculate several performance and disparity metrics below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Unmitigated</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>Overall selection rate</th>\n",
       "      <td>0.267111</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Demographic parity difference</th>\n",
       "      <td>0.0499407</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Demographic parity ratio</th>\n",
       "      <td>0.825666</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>-----</th>\n",
       "      <td></td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Overall balanced error rate</th>\n",
       "      <td>0.22133</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Balanced error rate difference</th>\n",
       "      <td>0.178303</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Equalized odds difference</th>\n",
       "      <td>0.344951</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>------</th>\n",
       "      <td></td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Overall AUC</th>\n",
       "      <td>0.852206</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>AUC difference</th>\n",
       "      <td>0.189891</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                               Unmitigated\n",
       "Overall selection rate            0.267111\n",
       "Demographic parity difference    0.0499407\n",
       "Demographic parity ratio          0.825666\n",
       "-----                                     \n",
       "Overall balanced error rate        0.22133\n",
       "Balanced error rate difference    0.178303\n",
       "Equalized odds difference         0.344951\n",
       "------                                    \n",
       "Overall AUC                       0.852206\n",
       "AUC difference                    0.189891"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Metrics\n",
    "models_dict = {\"Unmitigated\": (test_preds, test_scores)}\n",
    "get_metrics_df(models_dict, Y_test, A_str_test)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As the overall performance metric we use the _area under ROC curve_ (AUC), which is suited to classification problems with a large imbalance between positive and negative examples. For binary classifiers, this is the same as _balanced accuracy_.\n",
    "\n",
    "As the fairness metric we use *equalized odds difference*, which quantifies the disparity in accuracy experienced by different demographics. Our goal is to assure that neither of the two groups (men vs women) has substantially larger false-positive rates or false-negative rates than the other group. The equalized odds difference is equal to the larger of the following two numbers: (1) the difference between false-positive rates of the two groups, (2) the difference between false-negative rates of the two groups.\n",
    "\n",
    "The table above shows the overall AUC of 0.85 (based on continuous predictions) and the overall balanced error rate of 0.22 (based on 0/1 predictions). Both of these are satisfactory in our application context. However, there is a large disparity in accuracy rates (as indicated by the balanced error rate difference) and even larger when we consider the equalized-odds difference. As a sanity check, we also show the demographic parity ratio, whose level (slightly above 0.8) is considered satisfactory in this context."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mitigating Equalized Odds Difference with Postprocessing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We attempt to mitigate the disparities in the `lightgbm` predictions using the Fairlearn postprocessing algorithm `ThresholdOptimizer`. This algorithm finds a suitable threshold for the scores (class probabilities) produced by the `lightgbm` model by optimizing the accuracy rate under the constraint that the equalized odds difference (on training data) is zero. Since our goal is to optimize balanced accuracy, we resample the training data to have the same number of positive and negative examples. This means that `ThresholdOptimizer` is effectively optimizing balanced accuracy on the original data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "postprocess_est = ThresholdOptimizer(\n",
    "    estimator=model,\n",
    "    constraints=\"equalized_odds\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Balanced data set is obtained by sampling the same number of points from the majority class (Y=0)\n",
    "# as there are points in the minority class (Y=1)\n",
    "balanced_idx1 = df_train[Y_train==1].index\n",
    "pp_train_idx = balanced_idx1.union(Y_train[Y_train==0].sample(n=balanced_idx1.size, random_state=1234).index)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "df_train_balanced = df_train.loc[pp_train_idx, :]\n",
    "Y_train_balanced = Y_train.loc[pp_train_idx]\n",
    "A_train_balanced = A_train.loc[pp_train_idx]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "postprocess_est.fit(df_train_balanced, Y_train_balanced, sensitive_features=A_train_balanced)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "postprocess_preds = postprocess_est.predict(df_test, sensitive_features=A_test)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Unmitigated</th>\n",
       "      <th>ThresholdOptimizer</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>Overall selection rate</th>\n",
       "      <td>0.267111</td>\n",
       "      <td>0.225</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Demographic parity difference</th>\n",
       "      <td>0.0499407</td>\n",
       "      <td>0.0127329</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Demographic parity ratio</th>\n",
       "      <td>0.825666</td>\n",
       "      <td>0.945305</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>-----</th>\n",
       "      <td></td>\n",
       "      <td></td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Overall balanced error rate</th>\n",
       "      <td>0.22133</td>\n",
       "      <td>0.322958</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Balanced error rate difference</th>\n",
       "      <td>0.178303</td>\n",
       "      <td>0.00167003</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Equalized odds difference</th>\n",
       "      <td>0.344951</td>\n",
       "      <td>0.00233857</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>------</th>\n",
       "      <td></td>\n",
       "      <td></td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Overall AUC</th>\n",
       "      <td>0.852206</td>\n",
       "      <td>0.677042</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>AUC difference</th>\n",
       "      <td>0.189891</td>\n",
       "      <td>0.00167003</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                               Unmitigated ThresholdOptimizer\n",
       "Overall selection rate            0.267111              0.225\n",
       "Demographic parity difference    0.0499407          0.0127329\n",
       "Demographic parity ratio          0.825666           0.945305\n",
       "-----                                                        \n",
       "Overall balanced error rate        0.22133           0.322958\n",
       "Balanced error rate difference    0.178303         0.00167003\n",
       "Equalized odds difference         0.344951         0.00233857\n",
       "------                                                       \n",
       "Overall AUC                       0.852206           0.677042\n",
       "AUC difference                    0.189891         0.00167003"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "models_dict = {\"Unmitigated\": (test_preds, test_scores),\n",
    "              \"ThresholdOptimizer\": (postprocess_preds, postprocess_preds)}\n",
    "get_metrics_df(models_dict, Y_test, A_str_test)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `ThresholdOptimizer` algorithm significantly reduces the disparity according to multiple metrics. However, the performance metrics (balanced error rate as well as AUC) get worse. Before deploying such a model in practice, it would be important to examine in more detail why we observe such a sharp trade-off. In our case it is because the available features are much less informative for one of the demographic groups than for the other.\n",
    "\n",
    "Note that unlike the unmitigated model, `ThresholdOptimizer` produces 0/1 predictions, so its balanced error rate difference is equal to the AUC difference, and its overall balanced error rate is equal to 1 - overall AUC.\n",
    "\n",
    "Below, we compare this model with the unmitigated `lightgbm` model using the Fairlearn dashboard. As the performance metric, we can select the balanced accuracy. The dashboard right now does not directly show the equalized odds difference, but a similar information is shown in the _Disparity in Accuracy_ view, where we can examine the difference between overprediction and underprediction rates of the two groups."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Unmitigated Model vs ThresholdOptimizer: Dashboard Demo**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "3d4fa1123240472887aaea364df3feaa",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "FairlearnWidget(value={'true_y': [1, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 1…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<fairlearn.widget._fairlearn_dashboard.FairlearnDashboard at 0x7fec90a8d2b0>"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "FairlearnDashboard(sensitive_features=A_str_test, sensitive_feature_names=['Sex'],\n",
    "                   y_true=Y_test,\n",
    "                   y_pred={\"Unmitigated\": test_preds,\n",
    "                          \"ThresholdOptimizer\": postprocess_preds})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mitigating Equalized Odds Difference with GridSearch"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now attempt to mitigate disparities using the `GridSearch` algorithm. Unlike `ThresholdOptimizer`, the predictors produced by `GridSearch` do not access the sensitive feature at test time. Also, rather than training a single model, we train multiple models corresponding to different trade-off points between the performance metric (balanced accuracy) and fairness metric (equalized odds difference)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n",
      "Finished loading model, total used 100 iterations\n"
     ]
    }
   ],
   "source": [
    "# Train GridSearch\n",
    "sweep = GridSearch(model,\n",
    "                   constraints=EqualizedOdds(),\n",
    "                   grid_size=41,\n",
    "                   grid_limit=2)\n",
    "\n",
    "sweep.fit(df_train_balanced, Y_train_balanced, sensitive_features=A_train_balanced)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "sweep_preds = [predictor.predict(df_test) for predictor in sweep._predictors] \n",
    "sweep_scores = [predictor.predict_proba(df_test)[:, 1] for predictor in sweep._predictors] "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "equalized_odds_sweep = [\n",
    "    equalized_odds_difference(Y_test, preds, sensitive_features=A_str_test)\n",
    "    for preds in sweep_preds\n",
    "]\n",
    "balanced_accuracy_sweep = [balanced_accuracy_score(Y_test, preds) for preds in sweep_preds]\n",
    "auc_sweep = [roc_auc_score(Y_test, scores) for scores in sweep_scores]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Select only non-dominated models (with respect to balanced accuracy and equalized odds difference)\n",
    "all_results = pd.DataFrame(\n",
    "    {\"predictor\": sweep._predictors, \"accuracy\": balanced_accuracy_sweep, \"disparity\": equalized_odds_sweep}\n",
    ") \n",
    "non_dominated = [] \n",
    "for row in all_results.itertuples(): \n",
    "    accuracy_for_lower_or_eq_disparity = all_results[\"accuracy\"][all_results[\"disparity\"] <= row.disparity] \n",
    "    if row.accuracy >= accuracy_for_lower_or_eq_disparity.max(): \n",
    "        non_dominated.append(True)\n",
    "    else:\n",
    "        non_dominated.append(False)\n",
    "\n",
    "equalized_odds_sweep_non_dominated = np.asarray(equalized_odds_sweep)[non_dominated]\n",
    "balanced_accuracy_non_dominated = np.asarray(balanced_accuracy_sweep)[non_dominated]\n",
    "auc_non_dominated = np.asarray(auc_sweep)[non_dominated]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot equalized odds difference vs balanced accuracy\n",
    "plt.scatter(balanced_accuracy_non_dominated, equalized_odds_sweep_non_dominated, label=\"GridSearch Models\")\n",
    "plt.scatter(balanced_accuracy_score(Y_test, test_preds),\n",
    "            equalized_odds_difference(Y_test, test_preds, sensitive_features=A_str_test), \n",
    "            label=\"Unmitigated Model\")\n",
    "plt.scatter(balanced_accuracy_score(Y_test, postprocess_preds), \n",
    "            equalized_odds_difference(Y_test, postprocess_preds, sensitive_features=A_str_test),\n",
    "            label=\"ThresholdOptimizer Model\")\n",
    "plt.xlabel(\"Balanced Accuracy\")\n",
    "plt.ylabel(\"Equalized Odds Difference\")\n",
    "plt.legend(bbox_to_anchor=(1.55, 1))\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As intended, `GridSearch` models appear along the trade-off curve between the large balanced accuracy (but also large disparity), and low disparity (but worse balanced accuracy). This gives the data scientist a flexibility to select a model that fits the application context best."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot equalized odds difference vs AUC\n",
    "plt.scatter(auc_non_dominated, equalized_odds_sweep_non_dominated, label=\"GridSearch Models\")\n",
    "plt.scatter(roc_auc_score(Y_test, test_scores),\n",
    "            equalized_odds_difference(Y_test, test_preds, sensitive_features=A_str_test), \n",
    "            label=\"Unmitigated Model\")\n",
    "plt.scatter(roc_auc_score(Y_test, postprocess_preds), \n",
    "            equalized_odds_difference(Y_test, postprocess_preds, sensitive_features=A_str_test),\n",
    "            label=\"ThresholdOptimizer Model\")\n",
    "plt.xlabel(\"AUC\")\n",
    "plt.ylabel(\"Equalized Odds Difference\")\n",
    "plt.legend(bbox_to_anchor=(1.55, 1))\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, `GridSearch` models appear along the trade-off curve between AUC and equalized odds difference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [],
   "source": [
    "model_sweep_dict = {\"GridSearch_{}\".format(i): sweep_preds[i] for i in range(len(sweep_preds)) if non_dominated[i]}\n",
    "model_sweep_dict.update({\"Unmitigated\": test_preds, \"ThresholdOptimizer\": postprocess_preds})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Grid Search: Dashboard Demo**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We compare the `GridSearch` candidate models with the unmitigated `lightgbm` model and the `ThresholdOptimizer` model using the Fairlearn dashboard. We can select the balanced accuracy as the performance metric and examine the trade-off curve between balanced accuracy and the disparity in balanced accuracy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "067feb73cf1f4adb92353676d068146f",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "FairlearnWidget(value={'true_y': [1, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 1…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/plain": [
       "<fairlearn.widget._fairlearn_dashboard.FairlearnDashboard at 0x7fec90be55c0>"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "FairlearnDashboard(sensitive_features=A_str_test, sensitive_feature_names=['Sex'],\n",
    "                   y_true=Y_test,\n",
    "                   y_pred=model_sweep_dict)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}