examples/FairGBM-python-notebooks/UCI-Adult-example-with-hyperparameter-tuning.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "cff42768",
   "metadata": {},
   "source": [
    "# FairGBM example with hyperparameter tuning (using UCI Adult dataset)\n",
    "\n",
    "**IMPORTANT**: as FairGBM is a research project, the default hyperparameters will not be as reliable as the default `lightgbm` or `sklearn` hyperparameters.\n",
    "\n",
    "Therefore we earnestly **recommend performing hyperparameter-tuning** on the `fairgbm` hyperparameters, most importantly on the `multiplier_learning_rate` parameter!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8822e0d4",
   "metadata": {},
   "source": [
    "This notebook has extra requirements besides `fairgbm`. Simply run ```pip install -r requirements.txt``` to get them!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "4bdcc068",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from pathlib import Path\n",
    "import pandas as pd\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "cbe2ed76",
   "metadata": {},
   "outputs": [],
   "source": [
    "N_TRIALS = 20\n",
    "N_JOBS = max(2, os.cpu_count())\n",
    "SEED = 42\n",
    "\n",
    "PERF_METRIC = \"accuracy\"\n",
    "FAIR_METRIC = \"equalized_odds_ratio\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10ff123f",
   "metadata": {},
   "source": [
    "### Load data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "27034067",
   "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>age</th>\n",
       "      <th>workclass</th>\n",
       "      <th>fnlwgt</th>\n",
       "      <th>education</th>\n",
       "      <th>education-num</th>\n",
       "      <th>marital-status</th>\n",
       "      <th>occupation</th>\n",
       "      <th>relationship</th>\n",
       "      <th>race</th>\n",
       "      <th>sex</th>\n",
       "      <th>capital-gain</th>\n",
       "      <th>capital-loss</th>\n",
       "      <th>hours-per-week</th>\n",
       "      <th>native-country</th>\n",
       "      <th>target</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>39.0</td>\n",
       "      <td>State-gov</td>\n",
       "      <td>77516.0</td>\n",
       "      <td>Bachelors</td>\n",
       "      <td>13.0</td>\n",
       "      <td>Never-married</td>\n",
       "      <td>Adm-clerical</td>\n",
       "      <td>Not-in-family</td>\n",
       "      <td>White</td>\n",
       "      <td>Male</td>\n",
       "      <td>2174.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>40.0</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>50.0</td>\n",
       "      <td>Self-emp-not-inc</td>\n",
       "      <td>83311.0</td>\n",
       "      <td>Bachelors</td>\n",
       "      <td>13.0</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Exec-managerial</td>\n",
       "      <td>Husband</td>\n",
       "      <td>White</td>\n",
       "      <td>Male</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>13.0</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>38.0</td>\n",
       "      <td>Private</td>\n",
       "      <td>215646.0</td>\n",
       "      <td>HS-grad</td>\n",
       "      <td>9.0</td>\n",
       "      <td>Divorced</td>\n",
       "      <td>Handlers-cleaners</td>\n",
       "      <td>Not-in-family</td>\n",
       "      <td>White</td>\n",
       "      <td>Male</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>40.0</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>53.0</td>\n",
       "      <td>Private</td>\n",
       "      <td>234721.0</td>\n",
       "      <td>11th</td>\n",
       "      <td>7.0</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Handlers-cleaners</td>\n",
       "      <td>Husband</td>\n",
       "      <td>Black</td>\n",
       "      <td>Male</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>40.0</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>28.0</td>\n",
       "      <td>Private</td>\n",
       "      <td>338409.0</td>\n",
       "      <td>Bachelors</td>\n",
       "      <td>13.0</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Prof-specialty</td>\n",
       "      <td>Wife</td>\n",
       "      <td>Black</td>\n",
       "      <td>Female</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>40.0</td>\n",
       "      <td>Cuba</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "    age         workclass    fnlwgt  education  education-num  \\\n",
       "0  39.0         State-gov   77516.0  Bachelors           13.0   \n",
       "1  50.0  Self-emp-not-inc   83311.0  Bachelors           13.0   \n",
       "2  38.0           Private  215646.0    HS-grad            9.0   \n",
       "3  53.0           Private  234721.0       11th            7.0   \n",
       "4  28.0           Private  338409.0  Bachelors           13.0   \n",
       "\n",
       "       marital-status         occupation   relationship   race     sex  \\\n",
       "0       Never-married       Adm-clerical  Not-in-family  White    Male   \n",
       "1  Married-civ-spouse    Exec-managerial        Husband  White    Male   \n",
       "2            Divorced  Handlers-cleaners  Not-in-family  White    Male   \n",
       "3  Married-civ-spouse  Handlers-cleaners        Husband  Black    Male   \n",
       "4  Married-civ-spouse     Prof-specialty           Wife  Black  Female   \n",
       "\n",
       "   capital-gain  capital-loss  hours-per-week native-country target  \n",
       "0        2174.0           0.0            40.0  United-States  <=50K  \n",
       "1           0.0           0.0            13.0  United-States  <=50K  \n",
       "2           0.0           0.0            40.0  United-States  <=50K  \n",
       "3           0.0           0.0            40.0  United-States  <=50K  \n",
       "4           0.0           0.0            40.0           Cuba  <=50K  "
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from utils import load_uci_adult\n",
    "train_set, other_set = load_uci_adult()\n",
    "train_set.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60ee6071",
   "metadata": {},
   "source": [
    "Split features (X), labels (Y), and sensitive attributes (S).\n",
    "\n",
    "**NOTE**: the labels (Y) and sensitive attributes (S) must be in numeric format!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "03425560",
   "metadata": {},
   "outputs": [],
   "source": [
    "UCI_ADULT_TARGET_COL = \"target\"\n",
    "UCI_ADULT_SENSITIVE_COL = \"sex\"\n",
    "\n",
    "def split_X_Y_S_uci_adult(data) -> tuple:\n",
    "    \"\"\"Splits the given UCI Adult data into features, target, and sensitive attributes.\n",
    "    \n",
    "    Returns\n",
    "    -------\n",
    "    X, Y, S : tuple[pd.DataFrame, pd.Series, pd.Series]\n",
    "        A tuple conmtaining the dataset's features, labels, and sensitive attributes.\n",
    "    \"\"\"\n",
    "    ignored_cols = [UCI_ADULT_TARGET_COL, UCI_ADULT_SENSITIVE_COL, \"fnlwgt\"]\n",
    "    feature_cols = [col for col in data.columns if col not in ignored_cols]\n",
    "\n",
    "    X = data[feature_cols]\n",
    "    \n",
    "    # Convert label to numeric\n",
    "    Y = np.array(\n",
    "        [0 if \"<=50K\" in val.strip() else 1 for val in data[UCI_ADULT_TARGET_COL]],\n",
    "        dtype=int)\n",
    "\n",
    "    # Convert sensitive attributes to numeric\n",
    "    # NOTE! You can use two or more sensitive groups!\n",
    "    S = np.array(\n",
    "        [1 if val == \"Female\" else 0 for val in data[UCI_ADULT_SENSITIVE_COL]],\n",
    "        dtype=int)\n",
    "    \n",
    "    return X, Y, S"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b99f0de",
   "metadata": {},
   "source": [
    "In this example we're using only two sensitive attributes (sex=\"Female\" or sex=\"Male\").\n",
    "\n",
    "However, _FairGBM is **not** restricted to binary sensitive attributes_: you can use two or more as long as they're encoded in a single numeric column."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d9c295d",
   "metadata": {},
   "source": [
    "---\n",
    "Split test data into validation and test (we need a validation set for hyperparameter tuning)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "c352ac97",
   "metadata": {},
   "outputs": [],
   "source": [
    "VALIDATION_SIZE_N = int(0.5 * len(other_set))\n",
    "\n",
    "indices = np.random.permutation(len(other_set))\n",
    "val_indices = indices[VALIDATION_SIZE_N: ]\n",
    "test_indices = indices[: VALIDATION_SIZE_N]\n",
    "\n",
    "val_set = other_set.iloc[val_indices]\n",
    "test_set = other_set.iloc[test_indices]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "7db7d742",
   "metadata": {},
   "outputs": [],
   "source": [
    "X_train, Y_train, S_train = split_X_Y_S_uci_adult(train_set)\n",
    "X_val, Y_val, S_val = split_X_Y_S_uci_adult(val_set)\n",
    "X_test, Y_test, S_test = split_X_Y_S_uci_adult(test_set);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0cad6eeb",
   "metadata": {},
   "source": [
    "###  Define FairGBM hyperparameter search space and tuner\n",
    "\n",
    "We're using the [`hyperparameter-tuning`](https://pypi.org/project/hyperparameter-tuning/) package (essentially contains a series of useful wrappers around `optuna`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "b02185ad",
   "metadata": {},
   "outputs": [],
   "source": [
    "# This file contains an example hyperparameter search space for FairGBM\n",
    "HYPERPARAM_SPACE_PATH = \"fairgbm_equalized-odds.yaml\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a59dcd13",
   "metadata": {},
   "source": [
    "This tuner configuration will maximize the average of `accuracy` and `equal_odds_ratio`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "0fd15f66",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "[I 2023-09-22 13:18:25,236] A new study created in memory with name: no-name-f0c88745-490d-4264-9468-c9106a7bb3cb\n"
     ]
    }
   ],
   "source": [
    "from hpt.tuner import ObjectiveFunction, OptunaTuner\n",
    "\n",
    "obj_func = ObjectiveFunction(\n",
    "    X_train=X_train, y_train=Y_train, s_train=S_train,\n",
    "    X_val=X_val, y_val=Y_val, s_val=S_val,\n",
    "    hyperparameter_space=HYPERPARAM_SPACE_PATH,\n",
    "    eval_metric=PERF_METRIC,\n",
    "    other_eval_metric=FAIR_METRIC,\n",
    "    threshold=0.50,\n",
    "    alpha=0.50,   # relative weight of `eval_metric` vs `other_eval_metric`\n",
    ")\n",
    "\n",
    "tuner = OptunaTuner(\n",
    "    objective_function=obj_func,\n",
    "    direction=\"maximize\",\n",
    "    seed=SEED,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44bb27d7",
   "metadata": {},
   "source": [
    "### Run HPT tuner"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0c4eaf2e",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "# Then just run optimize as you would for an optuna.Study object\n",
    "tuner.optimize(n_trials=N_TRIALS, n_jobs=N_JOBS, show_progress_bar=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "1bea2408",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "obj_func.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6650cb19",
   "metadata": {},
   "source": [
    "Hyperparameter tuning (HPT) results are stored in `tuner.results`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "97525554",
   "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>accuracy</th>\n",
       "      <th>equalized_odds_ratio</th>\n",
       "      <th>equalized_odds_diff</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>17</th>\n",
       "      <td>0.372313</td>\n",
       "      <td>0.865521</td>\n",
       "      <td>0.105420</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>13</th>\n",
       "      <td>0.862916</td>\n",
       "      <td>0.849381</td>\n",
       "      <td>0.112689</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12</th>\n",
       "      <td>0.836998</td>\n",
       "      <td>0.821629</td>\n",
       "      <td>0.023367</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>0.759980</td>\n",
       "      <td>0.761170</td>\n",
       "      <td>0.017205</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>0.863776</td>\n",
       "      <td>0.706801</td>\n",
       "      <td>0.049897</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "    accuracy  equalized_odds_ratio  equalized_odds_diff\n",
       "17  0.372313              0.865521             0.105420\n",
       "13  0.862916              0.849381             0.112689\n",
       "12  0.836998              0.821629             0.023367\n",
       "10  0.759980              0.761170             0.017205\n",
       "6   0.863776              0.706801             0.049897"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Show results with best fairness\n",
    "tuner.results.sort_values(by=FAIR_METRIC, ascending=False).head()[\n",
    "    [PERF_METRIC, FAIR_METRIC, \"equalized_odds_diff\"]\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68f91d90",
   "metadata": {},
   "source": [
    "### Reconstruct classifier from best HPT trial"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "a1ea2dab",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Best trial was #13.\n"
     ]
    }
   ],
   "source": [
    "print(f\"Best trial was #{obj_func.best_trial.id}.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "34c35492",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CPU times: user 3min 19s, sys: 7.47 ms, total: 3min 19s\n",
      "Wall time: 3min 19s\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "fairgbm_clf = obj_func.reconstruct_model(obj_func.best_trial)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "071ed3c6",
   "metadata": {},
   "source": [
    "### Compute test predictions\n",
    "\n",
    "**Note**: the sensitive attributes are only used in training and not at inference time!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "9c3f665e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Compute test predictions (select only probabilities for positive class)\n",
    "Y_test_pred = fairgbm_clf.predict_proba(X_test)[:, 1]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d8df57e",
   "metadata": {},
   "source": [
    "### And evaluate test performance and fairness"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "12782e2a",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/root/miniconda/lib/python3.11/site-packages/sklearn/metrics/_classification.py:2845: FutureWarning: Setting the eps parameter is deprecated and will be removed in 1.5. Instead eps will always havea default value of `np.finfo(y_pred.dtype).eps`.\n",
      "  warnings.warn(\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'accuracy': 0.8605651105651105,\n",
       " 'tpr': 0.6402088772845953,\n",
       " 'fnr': 0.3597911227154047,\n",
       " 'fpr': 0.07164658634538153,\n",
       " 'tnr': 0.9283534136546184,\n",
       " 'precision': 0.7332535885167464,\n",
       " 'ppr': 0.20540540540540542,\n",
       " 'squared_loss': 0.09729872177266831,\n",
       " 'log_loss': 0.30427899668335334,\n",
       " 'tnr_ratio': 0.9972660818988818,\n",
       " 'tnr_diff': 0.002542347647430776,\n",
       " 'fnr_ratio': 0.9200230149597238,\n",
       " 'fnr_diff': 0.029159838823315187,\n",
       " 'precision_ratio': 0.7124308929468922,\n",
       " 'precision_diff': 0.22543997898607837,\n",
       " 'fpr_ratio': 0.9649882409696676,\n",
       " 'fpr_diff': 0.002542347647430776,\n",
       " 'tpr_ratio': 0.9561213853896781,\n",
       " 'tpr_diff': 0.029159838823315187,\n",
       " 'accuracy_ratio': 0.9366861367713762,\n",
       " 'accuracy_diff': 0.05689994486803318,\n",
       " 'ppr_ratio': 0.5894314550428764,\n",
       " 'ppr_diff': 0.09754295770200405,\n",
       " 'equalized_odds_ratio': 0.9561213853896781,\n",
       " 'equalized_odds_diff': 0.029159838823315187}"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from hpt.evaluation import evaluate_predictions\n",
    "\n",
    "test_eval = evaluate_predictions(\n",
    "    y_true=Y_test, y_pred_scores=Y_test_pred,\n",
    "    sensitive_attribute=S_test,\n",
    "    threshold=0.50,\n",
    ")\n",
    "\n",
    "test_eval"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "0477514c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "FairGBM results:\n",
      "\t Accuracy : 86.1%\n",
      "\t Equalized odds ratio (higher is better): 95.6%\n",
      "\t Equalized odds difference (lower is better): 2.9%\n"
     ]
    }
   ],
   "source": [
    "print(f\"FairGBM results:\")\n",
    "print(f\"\\t Accuracy : {test_eval['accuracy']:.1%}\")\n",
    "print(f\"\\t Equalized odds ratio (higher is better): {test_eval['equalized_odds_ratio']:.1%}\")\n",
    "print(f\"\\t Equalized odds difference (lower is better): {test_eval['equalized_odds_diff']:.1%}\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}