notebooks/single_model_audit.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Addressing Bias and Fairness in Machine Learning: A Practical Guide and Hands-on Tutorial\n",
    "## KDD 2023 Hands-on Tutorial\n",
    "### Rayid Ghani, Kit Rodolfa, Pedro Saleiro, Sérgio Jesus"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <font color=red>Auditing a Single Model using [Aequitas](http://www.datasciencepublicpolicy.org/projects/aequitas/)</font>\n",
    "A more in-depth demo notebook is at https://github.com/dssg/aequitas/blob/master/docs/source/examples/compas_demo.ipynb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Install dependencies, import packages and data\n",
    "This is needed every time you open this notebook in colab to install dependencies"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install aequitas==0.42.0\n",
    "from IPython.core.display import display, HTML\n",
    "display(HTML(\"<style>.container { width:75% !important; }</style>\"))\n",
    "import yaml\n",
    "import os\n",
    "import pandas as pd\n",
    "import numpy as np\n",
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "from aequitas.group import Group\n",
    "from aequitas.bias import Bias\n",
    "from aequitas.fairness import Fairness\n",
    "import aequitas.plot as ap\n",
    "DATAPATH = 'https://github.com/dssg/fairness_tutorial/raw/master/data/'\n",
    "DPI = 200\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What has already happened?\n",
    "\n",
    "We've already cleaned data, generated features, created train-test sets, built 1000s of models on each training set and scored each test set with them, and calculated various evaluation metrics. \n",
    "\n",
    "As described earlier, the goal here is to select top 1000 project submissions that are likely to not get funded in order to prioritize resource allocation. That corresponds to the metric **Precision at top 1000**.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Let's take a look at the performance of the models on one test set based on  **Precision at top 1000**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# code to load results and plot histogram with p@1000 for all models\n",
    "evals_df = pd.read_csv(DATAPATH +'split2_evals.csv.gz', compression='gzip')\n",
    "\n",
    "ax = sns.distplot(evals_df['model_precision'])\n",
    "ax.set_title('Precision at 1000 across all the models')\n",
    "plt.gcf().set_size_inches((5, 3))\n",
    "plt.gcf().set_dpi(DPI)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## We're now going to take the \"best\" model based on precision at top 1000 and audit its predicitons"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <font color=green>Auditing the Model with Highest Precision at top 1000</font>\n",
    "\n",
    "### What do we need to audit the predictions?\n",
    "1. predictions (scores or thresholded based on top 1000)\n",
    "2. labels\n",
    "3. attributes to audit (and a reference group within each attribute)\n",
    "4. fairness metric(s)\n",
    "5. disparity tolerance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load predictions, labels, and attributes to audit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load pre-computed predictions, labels, attributes dataframe\n",
    "df = pd.read_csv(DATAPATH + 'single_audit_df.csv.gz', compression='gzip')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Aequitas needs predictions (binary score), the label value, and the attributes to audit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "# take a look at the dataframe we just loaded\n",
    "df.head(10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The score has been binarized (0/1) by taking the top 1000 highest scored predictions and calling them 1 \n",
    "# because we care about selecting the top 1000 projects)\n",
    "df['score'].value_counts()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define Attributes to Audit and Reference Group for each Attribute"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "attributes_and_reference_groups={'poverty_level':'lower', 'metro_type':'suburban_rural', 'teacher_sex':'male'}\n",
    "attributes_to_audit = list(attributes_and_reference_groups.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Select fairness metric(s) that we care about"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "metrics = ['tpr']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define  Disparity Tolerance "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "disparity_tolerance = 1.30"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## Run Aequitas (based on the settings above)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initialize Aequitas\n",
    "g = Group()\n",
    "b = Bias()\n",
    "\n",
    "# get_crosstabs returns a dataframe of the group counts and group value bias metrics.\n",
    "xtab, _ = g.get_crosstabs(df, attr_cols=attributes_to_audit)\n",
    "bdf = b.get_disparity_predefined_groups(xtab, original_df=df, ref_groups_dict=attributes_and_reference_groups)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Look at Audit Results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Now we are going to focus our analysis on the fairness metric(s) of interest in this case study: TPR across different groups. The aequitas plot module exposes the disparities_metrics() plot, which displays both the disparities and the group-wise metric results side by side."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Check for Fairness in Poverty Level "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ap.disparity(bdf, metrics, 'poverty_level', fairness_threshold = disparity_tolerance)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ap.absolute(bdf, metrics, 'poverty_level', fairness_threshold = disparity_tolerance)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Check for Fairness in Metro_Type (where the school is based)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ap.disparity(bdf, metrics, 'metro_type', fairness_threshold = disparity_tolerance)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ap.absolute(bdf, metrics, 'metro_type', fairness_threshold = disparity_tolerance)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Check for Fairness in the Sex of the Teacher submitting the project "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "ap.disparity(bdf, metrics, 'teacher_sex', fairness_threshold = disparity_tolerance)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ap.absolute(bdf, metrics, 'teacher_sex', fairness_threshold = disparity_tolerance)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Deeper Dive into the audit results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Look at the underlying data: Disparities for all metrics "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bdf[['attribute_name', 'attribute_value'] + b.list_disparities(bdf)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Look at the underlying data: All Metrics"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "absolute_metrics = g.list_absolute_metrics(xtab)\n",
    "xtab[['attribute_name', 'attribute_value'] + absolute_metrics]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Look at the underlying data: All raw counts"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "xtab[[col for col in xtab.columns if col not in absolute_metrics]]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}