11-FairLearn.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Detect and Mitigate Unfairness in Models\n",
    "\n",
    "Machine learning models can incorporate unintentional bias, which can lead to issues with *fairness*. For example, a model that predicts the likelihood of diabetes might work well for some age groups, but not for others - subjecting a subset of patients to unnecessary tests, or depriving them of tests that would confirm a diabetes diagnosis.\n",
    "\n",
    "In this notebook, you'll use the **Fairlearn** package to analyze a model and find any disparity in prediction performance for different subsets of patients based on age.\n",
    "\n",
    "## Install the required SDKs\n",
    "\n",
    "To use the Fairlearn package with Azure Machine Learning, you need to install the Azure Machine Learning and Fairlearn Python packages, so run the following cell to do that."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install --upgrade azureml-sdk azureml-widgets azureml-contrib-fairness\n",
    "!pip install --upgrade fairlearn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Train a model\n",
    "\n",
    "You'll start by training a classification model to predict the likelihood of diabetes. In addition to splitting the data into training a test sets of features and labels, you'll extract *sensitive* features that are used to define subpopulations of the data for which you want to compare fairness. In this case, you'll use the **Age** column to define two categories of patient: those over 50 years old, and those 50 or younger."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import numpy as np\n",
    "from sklearn.model_selection import train_test_split\n",
    "from sklearn.tree import DecisionTreeClassifier\n",
    "\n",
    "# load the diabetes dataset\n",
    "print(\"Loading Data...\")\n",
    "data = pd.read_csv('data/diabetes.csv')\n",
    "\n",
    "# Separate features and labels\n",
    "features = ['Pregnancies','PlasmaGlucose','DiastolicBloodPressure','TricepsThickness','SerumInsulin','BMI','DiabetesPedigree','Age']\n",
    "X, y = data[features].values, data['Diabetic'].values\n",
    "\n",
    "# Get sensitive features\n",
    "S = data[['Age']].astype(int)\n",
    "# Change value to represent age groups\n",
    "S['Age'] = np.where(S.Age > 50, 'Over 50', '50 or younger')\n",
    "\n",
    "# Split data into training set and test set\n",
    "X_train, X_test, y_train, y_test, S_train, S_test = train_test_split(X, y, S, test_size=0.20, random_state=0, stratify=y)\n",
    "\n",
    "# Train a classification model\n",
    "print(\"Training model...\")\n",
    "diabetes_model = DecisionTreeClassifier().fit(X_train, y_train)\n",
    "\n",
    "print(\"Model trained.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that you've trained a model, you can use the Fairlearn package to compare its behavior for different sensitive feature values. In this case, you'll:\n",
    "\n",
    "- Use the fairlearn **selection_rate** function to return the selection rate (percentage of positive predictions) for the overall population.\n",
    "- Use **scikit-learn** metric functions to calculate overall accuracy, recall, and precision metrics.\n",
    "- Use a **MetricFrame** to calculate selection rate, accuracy, recall, and precision for each age group in the **Age** sensitive feature. Note that a mix of **fairlearn** and **scikit-learn** metric functions are used to calculate the performance values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from fairlearn.metrics import selection_rate, MetricFrame\n",
    "from sklearn.metrics import accuracy_score, recall_score, precision_score\n",
    "\n",
    "# Get predictions for the witheld test data\n",
    "y_hat = diabetes_model.predict(X_test)\n",
    "\n",
    "# Get overall metrics\n",
    "print(\"Overall Metrics:\")\n",
    "# Get selection rate from fairlearn\n",
    "overall_selection_rate = selection_rate(y_test, y_hat) # Get selection rate from fairlearn\n",
    "print(\"\\tSelection Rate:\", overall_selection_rate)\n",
    "# Get standard metrics from scikit-learn\n",
    "overall_accuracy = accuracy_score(y_test, y_hat)\n",
    "print(\"\\tAccuracy:\", overall_accuracy)\n",
    "overall_recall = recall_score(y_test, y_hat)\n",
    "print(\"\\tRecall:\", overall_recall)\n",
    "overall_precision = precision_score(y_test, y_hat)\n",
    "print(\"\\tPrecision:\", overall_precision)\n",
    "\n",
    "# Get metrics by sensitive group from fairlearn\n",
    "print('\\nMetrics by Group:')\n",
    "metrics = {'selection_rate': selection_rate,\n",
    "           'accuracy': accuracy_score,\n",
    "           'recall': recall_score,\n",
    "           'precision': precision_score}\n",
    "\n",
    "group_metrics = MetricFrame(metrics,\n",
    "                             y_test, y_hat,\n",
    "                             sensitive_features=S_test['Age'])\n",
    "\n",
    "print(group_metrics.by_group)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From these metrics, you should be able to discern that a larger proportion of the older patients are predicted to be diabetic. *Accuracy* should be more or less equal for the two groups, but a closer inspection of *precision* and *recall* indicates some disparity in how well the model predicts for each age group.\n",
    "\n",
    "In this scenario, consider *recall*. This metric indicates the proportion of positive cases that were correctly identified by the model. In other words, of all the patients who are actually diabetic, how many did the model find? The model does a better job of this for patients in the older age group than for younger patients.\n",
    "\n",
    "It's often easier to compare metrics visually. To do this, you'll use the Fairlearn dashboard:\n",
    "\n",
    "1. Run the cell below. (*note that a warning about future changes may be displayed - ignore this for now*)\n",
    "2. When the widget is displayed, use the **Get started** link to start configuring your visualization.\n",
    "3. Select the sensitive features you want to compare (in this case, there's only one: **Age**).\n",
    "4. Select the model performance metric you want to compare (in this case, it's a binary classification model so the options are *Accuracy*, *Balanced accuracy*, *Precision*, and *Recall*). Start with **Recall**.\n",
    "5. View the dashboard visualization, which shows:\n",
    "    - **Disparity in performance** - how the selected performance metric compares for the subpopulations, including *underprediction* (false negatives) and *overprediction* (false positives).\n",
    "    - **Disparity in predictions** - A comparison of the number of positive cases per subpopulation.\n",
    "6. Edit the configuration to compare the predictions based on different performance metrics."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from fairlearn.widget import FairlearnDashboard\n",
    "\n",
    "# View this model in Fairlearn's fairness dashboard, and see the disparities which appear:\n",
    "FairlearnDashboard(sensitive_features=S_test, \n",
    "                   sensitive_feature_names=['Age'],\n",
    "                   y_true=y_test,\n",
    "                   y_pred={\"diabetes_model\": diabetes_model.predict(X_test)})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The results show a much higher selection rate for patients over 50 than for younger patients. However, in reality, age is a genuine factor in diabetes, so you would expect more positive cases among older patients.\n",
    "\n",
    "If we base model performance on *accuracy* (in other words, the percentage of predictions the model gets right), then it seems to work more or less equally for both subpopulations. However, based on the *precision* and *recall* metrics, the model tends to perform better for patients who are over 50 years old.\n",
    "\n",
    "Let's see what happens if we exclude the **Age** feature when training the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Separate features and labels\n",
    "ageless = features.copy()\n",
    "ageless.remove('Age')\n",
    "X2, y2 = data[ageless].values, data['Diabetic'].values\n",
    "\n",
    "# Split data into training set and test set\n",
    "X_train2, X_test2, y_train2, y_test2, S_train2, S_test2 = train_test_split(X2, y2, S, test_size=0.20, random_state=0, stratify=y2)\n",
    "\n",
    "# Train a classification model\n",
    "print(\"Training model...\")\n",
    "ageless_model = DecisionTreeClassifier().fit(X_train2, y_train2)\n",
    "print(\"Model trained.\")\n",
    "\n",
    "# View this model in Fairlearn's fairness dashboard, and see the disparities which appear:\n",
    "FairlearnDashboard(sensitive_features=S_test2, \n",
    "                   sensitive_feature_names=['Age'],\n",
    "                   y_true=y_test2,\n",
    "                   y_pred={\"ageless_diabetes_model\": ageless_model.predict(X_test2)})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Explore the model in the dashboard.\n",
    "\n",
    "When you review *recall*, note that the disparity has reduced, but the overall recall has also reduced because the model now significantly underpredicts positive cases for older patients. Even though **Age** was not a feature used in training, the model still exhibits some disparity in how well it predicts for older and younger patients.\n",
    "\n",
    "In this scenario, simply removing the **Age** feature slightly reduces the disparity in *recall*, but increases the disparity in *precision* and *accuracy*. This underlines one the key difficulties in applying fairness to machine learning models - you must be clear about what *fairness* means in a particular context, and optimize for that.\n",
    "\n",
    "## Register the model and upload the dashboard data to your workspace\n",
    "\n",
    "You've trained the model and reviewed the dashboard locally in this notebook; but it might be useful to register the model in your Azure Machine Learning workspace and create an experiment to record the dashboard data so you can track and share your fairness analysis.\n",
    "\n",
    "Let's start by registering the original model (which included **Age** as a feature).\n",
    "\n",
    "> **Note**: If prompted, follow the link and enter the authentication code provided to sign into your Azure subscription."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from azureml.core import Workspace, Experiment, Model\n",
    "import joblib\n",
    "import os\n",
    "\n",
    "# Load the Azure ML workspace from the saved config file\n",
    "ws = Workspace.from_config()\n",
    "print('Ready to work with', ws.name)\n",
    "\n",
    "# Save the trained model\n",
    "model_file = 'diabetes_model.pkl'\n",
    "joblib.dump(value=diabetes_model, filename=model_file)\n",
    "\n",
    "# Register the model\n",
    "print('Registering model...')\n",
    "registered_model = Model.register(model_path=model_file,\n",
    "                                  model_name='diabetes_classifier',\n",
    "                                  workspace=ws)\n",
    "model_id= registered_model.id\n",
    "\n",
    "\n",
    "print('Model registered.', model_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you can use the FairLearn package to create binary classification group metric sets for one or more models, and use an Azure Machine Learning experiment to upload the metrics.\n",
    "\n",
    "> **Note**: This may take a while. When the experiment has completed, the dashboard data will be downloaded and displayed to verify that it was uploaded successfully."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from fairlearn.metrics._group_metric_set import _create_group_metric_set\n",
    "from azureml.contrib.fairness import upload_dashboard_dictionary, download_dashboard_by_upload_id\n",
    "\n",
    "#  Create a dictionary of model(s) you want to assess for fairness \n",
    "sf = { 'Age': S_test.Age}\n",
    "ys_pred = { model_id:diabetes_model.predict(X_test) }\n",
    "dash_dict = _create_group_metric_set(y_true=y_test,\n",
    "                                    predictions=ys_pred,\n",
    "                                    sensitive_features=sf,\n",
    "                                    prediction_type='binary_classification')\n",
    "\n",
    "exp = Experiment(ws, \"Diabetes_Fairness\")\n",
    "print(exp)\n",
    "\n",
    "run = exp.start_logging()\n",
    "\n",
    "# Upload the dashboard to Azure Machine Learning\n",
    "try:\n",
    "    dashboard_title = \"Fairness insights of Diabetes Classifier\"\n",
    "    upload_id = upload_dashboard_dictionary(run,\n",
    "                                            dash_dict,\n",
    "                                            dashboard_name=dashboard_title)\n",
    "    print(\"\\nUploaded to id: {0}\\n\".format(upload_id))\n",
    "\n",
    "    # To test the dashboard, you can download it\n",
    "    downloaded_dict = download_dashboard_by_upload_id(run, upload_id)\n",
    "    print(downloaded_dict)\n",
    "finally:\n",
    "    run.complete()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The preceding code downloaded the metrics generated in the experiement just to confirm it completed successfully. The real benefit of uploading the metrics to an experiement is that you can now view the FairLearn dashboard in Azure Machine Learning studio.\n",
    "\n",
    "Run the cell below to see the experiment details, and click the **View Run details** link in the widget to see the run in Azure Machine Learning studio. Then view the **Fairness** tab of the experiment run to view the dashboard, which behaves the same way as the widget you viewed previously in this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from azureml.widgets import RunDetails\n",
    "\n",
    "RunDetails(run).show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also find the fairness dashboard by selecting a model in the **Models** page of Azure Machine Learning studio and reviewing its **Fairness** tab. This enables your organization to maintain a log of fairness analysis for the models you train and register."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mitigate unfairness in the model\n",
    "\n",
    "Now that you've analyzed the model for fairness, you can use any of the *mitigation* techniques supported by the FairLearn package to find a model that achieves the best balance of predictive performance and fairness.\n",
    "\n",
    "In this exercise, you'll use the **GridSearch** feature, which trains multiple models in an attempt to minimize the disparity of predictive performance for the sensitive features in the dataset (in this case, the age groups). You'll optimize the models by applying the **EqualizedOdds** parity constraint, which tries to ensure that models that exhibit similar true and false positive rates for each sensitive feature grouping. \n",
    "\n",
    "> *This may take some time to run*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from fairlearn.reductions import GridSearch, EqualizedOdds\n",
    "import joblib\n",
    "import os\n",
    "\n",
    "print('Finding mitigated models...')\n",
    "\n",
    "# Train multiple models\n",
    "sweep = GridSearch(DecisionTreeClassifier(),\n",
    "                   constraints=EqualizedOdds(),\n",
    "                   grid_size=20)\n",
    "\n",
    "sweep.fit(X_train, y_train, sensitive_features=S_train.Age)\n",
    "models = sweep.predictors_\n",
    "\n",
    "# Save the models and get predictions from them (plus the original unmitigated one for comparison)\n",
    "model_dir = 'mitigated_models'\n",
    "os.makedirs(model_dir, exist_ok=True)\n",
    "model_name = 'diabetes_unmitigated'\n",
    "print(model_name)\n",
    "joblib.dump(value=diabetes_model, filename=os.path.join(model_dir, '{0}.pkl'.format(model_name)))\n",
    "predictions = {model_name: diabetes_model.predict(X_test)}\n",
    "i = 0\n",
    "for model in models:\n",
    "    i += 1\n",
    "    model_name = 'diabetes_mitigated_{0}'.format(i)\n",
    "    print(model_name)\n",
    "    joblib.dump(value=model, filename=os.path.join(model_dir, '{0}.pkl'.format(model_name)))\n",
    "    predictions[model_name] = model.predict(X_test)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you can use the FairLearn dashboard to compare the mitigated models:\n",
    "\n",
    "Run the following cell and then use the wizard to visualize **Age** by **Recall**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "FairlearnDashboard(sensitive_features=S_test, \n",
    "                   sensitive_feature_names=['Age'],\n",
    "                   y_true=y_test,\n",
    "                   y_pred=predictions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The models are shown on a scatter plot. You can compare the models by measuring the disparity in predictions (in other words, the selection rate) or the disparity in the selected performance metric (in this case, *recall*). In this scenario, we expect disparity in selection rates (because we know that age *is* a factor in diabetes, with more positive cases in the older age group). What we're interested in is the disparity in predictive performance, so select the option to measure **Disparity in recall**.\n",
    "\n",
    "The chart shows clusters of models with the overall *recall* metric on the X axis, and the disparity in recall on the Y axis. Therefore, the ideal model (with high recall and low disparity) would be at the bottom right corner of the plot. You can choose the right balance of predictive performance and fairness for your particular needs, and select an appropriate model to see its details.\n",
    "\n",
    "An important point to reinforce is that applying fairness to a model is a trade-off between overall predictive performance and disparity across sensitive feature groups - generally you must sacrifice some overall predictive performance to ensure that the model predicts fairly for all segments of the population.\n",
    "\n",
    "> **Note**: Viewing the *precision* metric may result in a warning that precision is being set to 0.0 due to no predicted samples - you can ignore this.\n",
    "\n",
    "## Upload the mitigation dashboard metrics to Azure Machine Learning\n",
    "\n",
    "As before, you might want to keep track of your mitigation experimentation. To do this, you can:\n",
    "\n",
    "1. Register the models found by the GridSearch process.\n",
    "2. Compute the performance and disparity metrics for the models.\n",
    "3. Upload the metrics in an Azure Machine Learning experiment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Register the models\n",
    "registered_model_predictions = dict()\n",
    "for model_name, prediction_data in predictions.items():\n",
    "    model_file = os.path.join(model_dir, model_name + \".pkl\")\n",
    "    registered_model = Model.register(model_path=model_file,\n",
    "                                      model_name=model_name,\n",
    "                                      workspace=ws)\n",
    "    registered_model_predictions[registered_model.id] = prediction_data\n",
    "\n",
    "#  Create a group metric set for binary classification based on the Age feature for all of the models\n",
    "sf = { 'Age': S_test.Age}\n",
    "dash_dict = _create_group_metric_set(y_true=y_test,\n",
    "                                     predictions=registered_model_predictions,\n",
    "                                     sensitive_features=sf,\n",
    "                                     prediction_type='binary_classification')\n",
    "\n",
    "exp = Experiment(ws, \"Diabetes_Fairness_Mitigation\")\n",
    "print(exp)\n",
    "\n",
    "run = exp.start_logging()\n",
    "RunDetails(run).show()\n",
    "\n",
    "# Upload the dashboard to Azure Machine Learning\n",
    "try:\n",
    "    dashboard_title = \"Fairness Comparison of Diabetes Models\"\n",
    "    upload_id = upload_dashboard_dictionary(run,\n",
    "                                            dash_dict,\n",
    "                                            dashboard_name=dashboard_title)\n",
    "    print(\"\\nUploaded to id: {0}\\n\".format(upload_id))\n",
    "finally:\n",
    "    run.complete()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **Note**: A warning that precision is being set to 0.0 due to no predicted samples may be displayed - you can ignore this.\n",
    "\n",
    "\n",
    "When the experiement has finished running, click the **View Run details** link in the widget to view the run in Azure Machine Learning studio, and view the FairLearn dashboard on the **fairness** tab."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.6 - AzureML",
   "language": "python",
   "name": "python3-azureml"
  },
  "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": 4
}