Debiasing_MIT.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "Part2_Debiasing_Solution.ipynb",
      "provenance": [],
      "collapsed_sections": [
        "Ag_e7xtTzT1W",
        "NDj7KBaW8Asz"
      ],
      "include_colab_link": true
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "accelerator": "GPU"
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/Nimafrj/Debiasing/blob/main/Debiasing_MIT.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Ag_e7xtTzT1W"
      },
      "source": [
        "<table align=\"center\">\n",
        "  <td align=\"center\"><a target=\"_blank\" href=\"http://introtodeeplearning.com\">\n",
        "        <img src=\"https://i.ibb.co/Jr88sn2/mit.png\" style=\"padding-bottom:5px;\" />\n",
        "      Visit MIT Deep Learning</a></td>\n",
        "  <td align=\"center\"><a target=\"_blank\" href=\"https://colab.research.google.com/github/aamini/introtodeeplearning/blob/master/lab2/solutions/Part2_Debiasing_Solution.ipynb\">\n",
        "        <img src=\"https://i.ibb.co/2P3SLwK/colab.png\"  style=\"padding-bottom:5px;\" />Run in Google Colab</a></td>\n",
        "  <td align=\"center\"><a target=\"_blank\" href=\"https://github.com/aamini/introtodeeplearning/blob/master/lab2/solutions/Part2_Debiasing_Solution.ipynb\">\n",
        "        <img src=\"https://i.ibb.co/xfJbPmL/github.png\"  height=\"70px\" style=\"padding-bottom:5px;\"  />View Source on GitHub</a></td>\n",
        "</table>\n",
        "\n",
        "# Copyright Information"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "rNbf1pRlSDby"
      },
      "source": [
        "# Copyright 2021 MIT 6.S191 Introduction to Deep Learning. All Rights Reserved.\n",
        "# \n",
        "# Licensed under the MIT License. You may not use this file except in compliance\n",
        "# with the License. Use and/or modification of this code outside of 6.S191 must\n",
        "# reference:\n",
        "#\n",
        "# © MIT 6.S191: Introduction to Deep Learning\n",
        "# http://introtodeeplearning.com\n",
        "#"
      ],
      "execution_count": 1,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "QOpPUH3FR179"
      },
      "source": [
        "# Laboratory 2: Computer Vision\n",
        "\n",
        "# Part 2: Debiasing Facial Detection Systems\n",
        "\n",
        "In the second portion of the lab, we'll explore two prominent aspects of applied deep learning: facial detection and algorithmic bias. \n",
        "\n",
        "Deploying fair, unbiased AI systems is critical to their long-term acceptance. Consider the task of facial detection: given an image, is it an image of a face?  This seemingly simple, but extremely important, task is subject to significant amounts of algorithmic bias among select demographics. \n",
        "\n",
        "In this lab, we'll investigate [one recently published approach](http://introtodeeplearning.com/AAAI_MitigatingAlgorithmicBias.pdf) to addressing algorithmic bias. We'll build a facial detection model that learns the *latent variables* underlying face image datasets and uses this to adaptively re-sample the training data, thus mitigating any biases that may be present in order  to train a *debiased* model.\n",
        "\n",
        "\n",
        "Run the next code block for a short video from Google that explores how and why it's important to consider bias when thinking about machine learning:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "XQh5HZfbupFF",
        "outputId": "ddec7ed4-0970-4402-c152-fc9d6b3a11c5",
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 320
        }
      },
      "source": [
        "import IPython\n",
        "IPython.display.YouTubeVideo('59bMh59JQDo')"
      ],
      "execution_count": 2,
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/html": [
              "\n",
              "        <iframe\n",
              "            width=\"400\"\n",
              "            height=\"300\"\n",
              "            src=\"https://www.youtube.com/embed/59bMh59JQDo\"\n",
              "            frameborder=\"0\"\n",
              "            allowfullscreen\n",
              "        ></iframe>\n",
              "        "
            ],
            "text/plain": [
              "<IPython.lib.display.YouTubeVideo at 0x7f1c0bd700d0>"
            ],
            "image/jpeg": "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\n"
          },
          "metadata": {},
          "execution_count": 2
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3Ezfc6Yv6IhI"
      },
      "source": [
        "Let's get started by installing the relevant dependencies:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "E46sWVKK6LP9",
        "outputId": "20f98b67-082d-4358-83a1-d765348ade56",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "source": [
        "# Import Tensorflow 2.0\n",
        "%tensorflow_version 2.x\n",
        "import tensorflow as tf\n",
        "\n",
        "import IPython\n",
        "import functools\n",
        "import matplotlib.pyplot as plt\n",
        "import numpy as np\n",
        "from tqdm import tqdm\n",
        "\n",
        "# Download and import the MIT 6.S191 package\n",
        "!pip install mitdeeplearning\n",
        "import mitdeeplearning as mdl"
      ],
      "execution_count": 3,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Collecting mitdeeplearning\n",
            "  Downloading mitdeeplearning-0.2.0.tar.gz (2.1 MB)\n",
            "\u001b[K     |████████████████████████████████| 2.1 MB 4.3 MB/s \n",
            "\u001b[?25hRequirement already satisfied: numpy in /usr/local/lib/python3.7/dist-packages (from mitdeeplearning) (1.19.5)\n",
            "Requirement already satisfied: regex in /usr/local/lib/python3.7/dist-packages (from mitdeeplearning) (2019.12.20)\n",
            "Requirement already satisfied: tqdm in /usr/local/lib/python3.7/dist-packages (from mitdeeplearning) (4.62.3)\n",
            "Requirement already satisfied: gym in /usr/local/lib/python3.7/dist-packages (from mitdeeplearning) (0.17.3)\n",
            "Requirement already satisfied: scipy in /usr/local/lib/python3.7/dist-packages (from gym->mitdeeplearning) (1.4.1)\n",
            "Requirement already satisfied: cloudpickle<1.7.0,>=1.2.0 in /usr/local/lib/python3.7/dist-packages (from gym->mitdeeplearning) (1.3.0)\n",
            "Requirement already satisfied: pyglet<=1.5.0,>=1.4.0 in /usr/local/lib/python3.7/dist-packages (from gym->mitdeeplearning) (1.5.0)\n",
            "Requirement already satisfied: future in /usr/local/lib/python3.7/dist-packages (from pyglet<=1.5.0,>=1.4.0->gym->mitdeeplearning) (0.16.0)\n",
            "Building wheels for collected packages: mitdeeplearning\n",
            "  Building wheel for mitdeeplearning (setup.py) ... \u001b[?25l\u001b[?25hdone\n",
            "  Created wheel for mitdeeplearning: filename=mitdeeplearning-0.2.0-py3-none-any.whl size=2115442 sha256=7834dab99c59b4c67dd705ab5d01a8694bf2d85dc8fef4f6dbfc513b8fb64d37\n",
            "  Stored in directory: /root/.cache/pip/wheels/9a/b9/4f/99b7c8c5c75355550b83e1fcfc02956fb40c35eb01e2262877\n",
            "Successfully built mitdeeplearning\n",
            "Installing collected packages: mitdeeplearning\n",
            "Successfully installed mitdeeplearning-0.2.0\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "V0e77oOM3udR"
      },
      "source": [
        "## 2.1 Datasets\n",
        "\n",
        "We'll be using three datasets in this lab. In order to train our facial detection models, we'll need a dataset of positive examples (i.e., of faces) and a dataset of negative examples (i.e., of things that are not faces). We'll use these data to train our models to classify images as either faces or not faces. Finally, we'll need a test dataset of face images. Since we're concerned about the potential *bias* of our learned models against certain demographics, it's important that the test dataset we use has equal representation across the demographics or features of interest. In this lab, we'll consider skin tone and gender. \n",
        "\n",
        "1.   **Positive training data**: [CelebA Dataset](http://mmlab.ie.cuhk.edu.hk/projects/CelebA.html). A large-scale (over 200K images) of celebrity faces.   \n",
        "2.   **Negative training data**: [ImageNet](http://www.image-net.org/). Many images across many different categories. We'll take negative examples from a variety of non-human categories. \n",
        "[Fitzpatrick Scale](https://en.wikipedia.org/wiki/Fitzpatrick_scale) skin type classification system, with each image labeled as \"Lighter'' or \"Darker''.\n",
        "\n",
        "Let's begin by importing these datasets. We've written a class that does a bit of data pre-processing to import the training data in a usable format."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "RWXaaIWy6jVw",
        "outputId": "d7fdc377-954e-4f80-ff4f-507c163d7dd0",
        "colab": {
          "base_uri": "https://localhost:8080/"
        }
      },
      "source": [
        "# Get the training data: both images from CelebA and ImageNet\n",
        "path_to_training_data = tf.keras.utils.get_file('train_face.h5', 'https://www.dropbox.com/s/hlz8atheyozp1yx/train_face.h5?dl=1')\n",
        "# Instantiate a TrainingDatasetLoader using the downloaded dataset\n",
        "loader = mdl.lab2.TrainingDatasetLoader(path_to_training_data)"
      ],
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Downloading data from https://www.dropbox.com/s/hlz8atheyozp1yx/train_face.h5?dl=1\n",
            " 988184576/1263889489 [======================>.......] - ETA: 10s"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "yIE321rxa_b3"
      },
      "source": [
        "We can look at the size of the training dataset and grab a batch of size 100:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "DjPSjZZ_bGqe"
      },
      "source": [
        "number_of_training_examples = loader.get_train_size()\n",
        "(images, labels) = loader.get_batch(100)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "sxtkJoqF6oH1"
      },
      "source": [
        "Play around with displaying images to get a sense of what the training data actually looks like!"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "Jg17jzwtbxDA"
      },
      "source": [
        "### Examining the CelebA training dataset ###\n",
        "\n",
        "#@title Change the sliders to look at positive and negative training examples! { run: \"auto\" }\n",
        "\n",
        "face_images = images[np.where(labels==1)[0]]\n",
        "not_face_images = images[np.where(labels==0)[0]]\n",
        "\n",
        "idx_face = 23 #@param {type:\"slider\", min:0, max:50, step:1}\n",
        "idx_not_face = 9 #@param {type:\"slider\", min:0, max:50, step:1}\n",
        "\n",
        "plt.figure(figsize=(5,5))\n",
        "plt.subplot(1, 2, 1)\n",
        "plt.imshow(face_images[idx_face])\n",
        "plt.title(\"Face\"); plt.grid(False)\n",
        "\n",
        "plt.subplot(1, 2, 2)\n",
        "plt.imshow(not_face_images[idx_not_face])\n",
        "plt.title(\"Not Face\"); plt.grid(False)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "NDj7KBaW8Asz"
      },
      "source": [
        "### Thinking about bias\n",
        "\n",
        "Remember we'll be training our facial detection classifiers on the large, well-curated CelebA dataset (and ImageNet), and then evaluating their accuracy by testing them on an independent test dataset. Our goal is to build a model that trains on CelebA *and* achieves high classification accuracy on the the test dataset across all demographics, and to thus show that this model does not suffer from any hidden bias. \n",
        "\n",
        "What exactly do we mean when we say a classifier is biased? In order to formalize this, we'll need to think about [*latent variables*](https://en.wikipedia.org/wiki/Latent_variable), variables that define a dataset but are not strictly observed. As defined in the generative modeling lecture, we'll use the term *latent space* to refer to the probability distributions of the aforementioned latent variables. Putting these ideas together, we consider a classifier *biased* if its classification decision changes after it sees some additional latent features. This notion of bias may be helpful to keep in mind throughout the rest of the lab. "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "AIFDvU4w8OIH"
      },
      "source": [
        "## 2.2 CNN for facial detection \n",
        "\n",
        "First, we'll define and train a CNN on the facial classification task, and evaluate its accuracy. Later, we'll evaluate the performance of our debiased models against this baseline CNN. The CNN model has a relatively standard architecture consisting of a series of convolutional layers with batch normalization followed by two fully connected layers to flatten the convolution output and generate a class prediction. \n",
        "\n",
        "### Define and train the CNN model\n",
        "\n",
        "Like we did in the first part of the lab, we'll define our CNN model, and then train on the CelebA and ImageNet datasets using the `tf.GradientTape` class and the `tf.GradientTape.gradient` method."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "82EVTAAW7B_X"
      },
      "source": [
        "### Define the CNN model ###\n",
        "\n",
        "n_filters = 12 # base number of convolutional filters\n",
        "\n",
        "'''Function to define a standard CNN model'''\n",
        "def make_standard_classifier(n_outputs=1):\n",
        "  Conv2D = functools.partial(tf.keras.layers.Conv2D, padding='same', activation='relu')\n",
        "  BatchNormalization = tf.keras.layers.BatchNormalization\n",
        "  Flatten = tf.keras.layers.Flatten\n",
        "  Dense = functools.partial(tf.keras.layers.Dense, activation='relu')\n",
        "\n",
        "  model = tf.keras.Sequential([\n",
        "    Conv2D(filters=1*n_filters, kernel_size=5,  strides=2),\n",
        "    BatchNormalization(),\n",
        "    \n",
        "    Conv2D(filters=2*n_filters, kernel_size=5,  strides=2),\n",
        "    BatchNormalization(),\n",
        "\n",
        "    Conv2D(filters=4*n_filters, kernel_size=3,  strides=2),\n",
        "    BatchNormalization(),\n",
        "\n",
        "    Conv2D(filters=6*n_filters, kernel_size=3,  strides=2),\n",
        "    BatchNormalization(),\n",
        "\n",
        "    Flatten(),\n",
        "    Dense(512),\n",
        "    Dense(n_outputs, activation=None),\n",
        "  ])\n",
        "  return model\n",
        "\n",
        "standard_classifier = make_standard_classifier()"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "c-eWf3l_lCri"
      },
      "source": [
        "Now let's train the standard CNN!"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "eJlDGh1o31G1"
      },
      "source": [
        "### Train the standard CNN ###\n",
        "\n",
        "# Training hyperparameters\n",
        "batch_size = 32\n",
        "num_epochs = 2  # keep small to run faster\n",
        "learning_rate = 5e-4\n",
        "\n",
        "optimizer = tf.keras.optimizers.Adam(learning_rate) # define our optimizer\n",
        "loss_history = mdl.util.LossHistory(smoothing_factor=0.99) # to record loss evolution\n",
        "plotter = mdl.util.PeriodicPlotter(sec=2, scale='semilogy')\n",
        "if hasattr(tqdm, '_instances'): tqdm._instances.clear() # clear if it exists\n",
        "\n",
        "@tf.function\n",
        "def standard_train_step(x, y):\n",
        "  with tf.GradientTape() as tape:\n",
        "    # feed the images into the model\n",
        "    logits = standard_classifier(x) \n",
        "    # Compute the loss\n",
        "    loss = tf.nn.sigmoid_cross_entropy_with_logits(labels=y, logits=logits)\n",
        "\n",
        "  # Backpropagation\n",
        "  grads = tape.gradient(loss, standard_classifier.trainable_variables)\n",
        "  optimizer.apply_gradients(zip(grads, standard_classifier.trainable_variables))\n",
        "  return loss\n",
        "\n",
        "# The training loop!\n",
        "for epoch in range(num_epochs):\n",
        "  for idx in tqdm(range(loader.get_train_size()//batch_size)):\n",
        "    # Grab a batch of training data and propagate through the network\n",
        "    x, y = loader.get_batch(batch_size)\n",
        "    loss = standard_train_step(x, y)\n",
        "\n",
        "    # Record the loss and plot the evolution of the loss as a function of training\n",
        "    loss_history.append(loss.numpy().mean())\n",
        "    plotter.plot(loss_history.get())"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "AKMdWVHeCxj8"
      },
      "source": [
        "### Evaluate performance of the standard CNN\n",
        "\n",
        "Next, let's evaluate the classification performance of our CelebA-trained standard CNN on the training dataset.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "35-PDgjdWk6_"
      },
      "source": [
        "### Evaluation of standard CNN ###\n",
        "\n",
        "# TRAINING DATA\n",
        "# Evaluate on a subset of CelebA+Imagenet\n",
        "(batch_x, batch_y) = loader.get_batch(5000)\n",
        "y_pred_standard = tf.round(tf.nn.sigmoid(standard_classifier.predict(batch_x)))\n",
        "acc_standard = tf.reduce_mean(tf.cast(tf.equal(batch_y, y_pred_standard), tf.float32))\n",
        "\n",
        "print(\"Standard CNN accuracy on (potentially biased) training set: {:.4f}\".format(acc_standard.numpy()))"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Qu7R14KaEEvU"
      },
      "source": [
        "We will also evaluate our networks on an independent test dataset containing faces that were not seen during training. For the test data, we'll look at the classification accuracy across four different demographics, based on the Fitzpatrick skin scale and sex-based labels: dark-skinned male, dark-skinned female, light-skinned male, and light-skinned female. \n",
        "\n",
        "Let's take a look at some sample faces in the test set. "
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "vfDD8ztGWk6x"
      },
      "source": [
        "### Load test dataset and plot examples ###\n",
        "\n",
        "test_faces = mdl.lab2.get_test_faces()\n",
        "keys = [\"Light Female\", \"Light Male\", \"Dark Female\", \"Dark Male\"]\n",
        "for group, key in zip(test_faces,keys): \n",
        "  plt.figure(figsize=(5,5))\n",
        "  plt.imshow(np.hstack(group))\n",
        "  plt.title(key, fontsize=15)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "uo1z3cdbEUMM"
      },
      "source": [
        "Now, let's evaluate the probability of each of these face demographics being classified as a face using the standard CNN classifier we've just trained."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "GI4O0Y1GAot9"
      },
      "source": [
        "### Evaluate the standard CNN on the test data ### \n",
        "\n",
        "standard_classifier_logits = [standard_classifier(np.array(x, dtype=np.float32)) for x in test_faces]\n",
        "standard_classifier_probs = tf.squeeze(tf.sigmoid(standard_classifier_logits))\n",
        "\n",
        "# Plot the prediction accuracies per demographic\n",
        "xx = range(len(keys))\n",
        "yy = standard_classifier_probs.numpy().mean(1)\n",
        "plt.bar(xx, yy)\n",
        "plt.xticks(xx, keys)\n",
        "plt.ylim(max(0,yy.min()-yy.ptp()/2.), yy.max()+yy.ptp()/2.)\n",
        "plt.title(\"Standard classifier predictions\");"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "j0Cvvt90DoAm"
      },
      "source": [
        "Take a look at the accuracies for this first model across these four groups. What do you observe? Would you consider this model biased or unbiased? What are some reasons why a trained model may have biased accuracies? "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0AKcHnXVtgqJ"
      },
      "source": [
        "## 2.3 Mitigating algorithmic bias\n",
        "\n",
        "Imbalances in the training data can result in unwanted algorithmic bias. For example, the majority of faces in CelebA (our training set) are those of light-skinned females. As a result, a classifier trained on CelebA will be better suited at recognizing and classifying faces with features similar to these, and will thus be biased.\n",
        "\n",
        "How could we overcome this? A naive solution -- and one that is being adopted by many companies and organizations -- would be to annotate different subclasses (i.e., light-skinned females, males with hats, etc.) within the training data, and then manually even out the data with respect to these groups.\n",
        "\n",
        "But this approach has two major disadvantages. First, it requires annotating massive amounts of data, which is not scalable. Second, it requires that we know what potential biases (e.g., race, gender, pose, occlusion, hats, glasses, etc.) to look for in the data. As a result, manual annotation may not capture all the different features that are imbalanced within the training data.\n",
        "\n",
        "Instead, let's actually **learn** these features in an unbiased, unsupervised manner, without the need for any annotation, and then train a classifier fairly with respect to these features. In the rest of this lab, we'll do exactly that."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "nLemS7dqECsI"
      },
      "source": [
        "## 2.4 Variational autoencoder (VAE) for learning latent structure\n",
        "\n",
        "As you saw, the accuracy of the CNN varies across the four demographics we looked at. To think about why this may be, consider the dataset the model was trained on, CelebA. If certain features, such as dark skin or hats, are *rare* in CelebA, the model may end up biased against these as a result of training with a biased dataset. That is to say, its classification accuracy will be worse on faces that have under-represented features, such as dark-skinned faces or faces with hats, relevative to faces with features well-represented in the training data! This is a problem. \n",
        "\n",
        "Our goal is to train a *debiased* version of this classifier -- one that accounts for potential disparities in feature representation within the training data. Specifically, to build a debiased facial classifier, we'll train a model that **learns a representation of the underlying latent space** to the face training data. The model then uses this information to mitigate unwanted biases by sampling faces with rare features, like dark skin or hats, *more frequently* during training. The key design requirement for our model is that it can learn an *encoding* of the latent features in the face data in an entirely *unsupervised* way. To achieve this, we'll turn to variational autoencoders (VAEs).\n",
        "\n",
        "![The concept of a VAE](https://i.ibb.co/3s4S6Gc/vae.jpg)\n",
        "\n",
        "As shown in the schematic above and in Lecture 4, VAEs rely on an encoder-decoder structure to learn a latent representation of the input data. In the context of computer vision, the encoder network takes in input images, encodes them into a series of variables defined by a mean and standard deviation, and then draws from the distributions defined by these parameters to generate a set of sampled latent variables. The decoder network then \"decodes\" these variables to generate a reconstruction of the original image, which is used during training to help the model identify which latent variables are important to learn. \n",
        "\n",
        "Let's formalize two key aspects of the VAE model and define relevant functions for each.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KmbXKtcPkTXA"
      },
      "source": [
        "### Understanding VAEs: loss function\n",
        "\n",
        "In practice, how can we train a VAE? In learning the latent space, we constrain the means and standard deviations to approximately follow a unit Gaussian. Recall that these are learned parameters, and therefore must factor into the loss computation, and that the decoder portion of the VAE is using these parameters to output a reconstruction that should closely match the input image, which also must factor into the loss. What this means is that we'll have two terms in our VAE loss function:\n",
        "\n",
        "1.  **Latent loss ($L_{KL}$)**: measures how closely the learned latent variables match a unit Gaussian and is defined by the Kullback-Leibler (KL) divergence.\n",
        "2.   **Reconstruction loss ($L_{x}{(x,\\hat{x})}$)**: measures how accurately the reconstructed outputs match the input and is given by the $L^1$ norm of the input image and its reconstructed output."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Ux3jK2wc153s"
      },
      "source": [
        "The equation for the latent loss is provided by:\n",
        "\n",
        "$$L_{KL}(\\mu, \\sigma) = \\frac{1}{2}\\sum_{j=0}^{k-1} (\\sigma_j + \\mu_j^2 - 1 - \\log{\\sigma_j})$$\n",
        "\n",
        "The equation for the reconstruction loss is provided by:\n",
        "\n",
        "$$L_{x}{(x,\\hat{x})} = ||x-\\hat{x}||_1$$\n",
        "\n",
        "Thus for the VAE loss we have:\n",
        "\n",
        "$$L_{VAE} = c\\cdot L_{KL} + L_{x}{(x,\\hat{x})}$$\n",
        "\n",
        "where $c$ is a weighting coefficient used for regularization. Now we're ready to define our VAE loss function:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "S00ASo1ImSuh"
      },
      "source": [
        "### Defining the VAE loss function ###\n",
        "\n",
        "''' Function to calculate VAE loss given:\n",
        "      an input x, \n",
        "      reconstructed output x_recon, \n",
        "      encoded means mu, \n",
        "      encoded log of standard deviation logsigma, \n",
        "      weight parameter for the latent loss kl_weight\n",
        "'''\n",
        "def vae_loss_function(x, x_recon, mu, logsigma, kl_weight=0.0005):\n",
        "  # TODO: Define the latent loss. Note this is given in the equation for L_{KL}\n",
        "  # in the text block directly above\n",
        "  latent_loss = 0.5 * tf.reduce_sum(tf.exp(logsigma) + tf.square(mu) - 1.0 - logsigma, axis=1)\n",
        "  # latent_loss = # TODO\n",
        "\n",
        "  # TODO: Define the reconstruction loss as the mean absolute pixel-wise \n",
        "  # difference between the input and reconstruction. Hint: you'll need to \n",
        "  # use tf.reduce_mean, and supply an axis argument which specifies which \n",
        "  # dimensions to reduce over. For example, reconstruction loss needs to average \n",
        "  # over the height, width, and channel image dimensions.\n",
        "  # https://www.tensorflow.org/api_docs/python/tf/math/reduce_mean\n",
        "  reconstruction_loss = tf.reduce_mean(tf.abs(x-x_recon), axis=(1,2,3))\n",
        "  # reconstruction_loss = # TODO\n",
        "\n",
        "  # TODO: Define the VAE loss. Note this is given in the equation for L_{VAE}\n",
        "  # in the text block directly above\n",
        "  vae_loss = kl_weight * latent_loss + reconstruction_loss\n",
        "  # vae_loss = # TODO\n",
        "  \n",
        "  return vae_loss"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "E8mpb3pJorpu"
      },
      "source": [
        "Great! Now that we have a more concrete sense of how VAEs work, let's explore how we can leverage this network structure to train a *debiased* facial classifier."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "DqtQH4S5fO8F"
      },
      "source": [
        "### Understanding VAEs: reparameterization \n",
        "\n",
        "As you may recall from lecture, VAEs use a \"reparameterization  trick\" for sampling learned latent variables. Instead of the VAE encoder generating a single vector of real numbers for each latent variable, it generates a vector of means and a vector of standard deviations that are constrained to roughly follow Gaussian distributions. We then sample from the standard deviations and add back the mean to output this as our sampled latent vector. Formalizing this for a latent variable $z$ where we sample $\\epsilon \\sim \\mathcal{N}(0,(I))$ we have:\n",
        "\n",
        "$$z = \\mu + e^{\\left(\\frac{1}{2} \\cdot \\log{\\Sigma}\\right)}\\circ \\epsilon$$\n",
        "\n",
        "where $\\mu$ is the mean and $\\Sigma$ is the covariance matrix. This is useful because it will let us neatly define the loss function for the VAE, generate randomly sampled latent variables, achieve improved network generalization, **and** make our complete VAE network differentiable so that it can be trained via backpropagation. Quite powerful!\n",
        "\n",
        "Let's define a function to implement the VAE sampling operation:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "cT6PGdNajl3K"
      },
      "source": [
        "### VAE Reparameterization ###\n",
        "\n",
        "\"\"\"Reparameterization trick by sampling from an isotropic unit Gaussian.\n",
        "# Arguments\n",
        "    z_mean, z_logsigma (tensor): mean and log of standard deviation of latent distribution (Q(z|X))\n",
        "# Returns\n",
        "    z (tensor): sampled latent vector\n",
        "\"\"\"\n",
        "def sampling(z_mean, z_logsigma):\n",
        "  # By default, random.normal is \"standard\" (ie. mean=0 and std=1.0)\n",
        "  batch, latent_dim = z_mean.shape\n",
        "  epsilon = tf.random.normal(shape=(batch, latent_dim))\n",
        "\n",
        "  # TODO: Define the reparameterization computation!\n",
        "  # Note the equation is given in the text block immediately above.\n",
        "  z = z_mean + tf.math.exp(0.5 * z_logsigma) * epsilon\n",
        "  # z = # TODO\n",
        "  return z"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qtHEYI9KNn0A"
      },
      "source": [
        "## 2.5 Debiasing variational autoencoder (DB-VAE)\n",
        "\n",
        "Now, we'll use the general idea behind the VAE architecture to build a model, termed a [*debiasing variational autoencoder*](https://lmrt.mit.edu/sites/default/files/AIES-19_paper_220.pdf) or DB-VAE, to mitigate (potentially) unknown biases present within the training idea. We'll train our DB-VAE model on the facial detection task, run the debiasing operation during training, evaluate on the PPB dataset, and compare its accuracy to our original, biased CNN model.    \n",
        "\n",
        "### The DB-VAE model\n",
        "\n",
        "The key idea behind this debiasing approach is to use the latent variables learned via a VAE to adaptively re-sample the CelebA data during training. Specifically, we will alter the probability that a given image is used during training based on how often its latent features appear in the dataset. So, faces with rarer features (like dark skin, sunglasses, or hats) should become more likely to be sampled during training, while the sampling probability for faces with features that are over-represented in the training dataset should decrease (relative to uniform random sampling across the training data). \n",
        "\n",
        "A general schematic of the DB-VAE approach is shown here:\n",
        "\n",
        "![DB-VAE](https://raw.githubusercontent.com/aamini/introtodeeplearning/2019/lab2/img/DB-VAE.png)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ziA75SN-UxxO"
      },
      "source": [
        "Recall that we want to apply our DB-VAE to a *supervised classification* problem -- the facial detection task. Importantly, note how the encoder portion in the DB-VAE architecture also outputs a single supervised variable, $z_o$, corresponding to the class prediction -- face or not face. Usually, VAEs are not trained to output any supervised variables (such as a class prediction)! This is another key distinction between the DB-VAE and a traditional VAE. \n",
        "\n",
        "Keep in mind that we only want to learn the latent representation of *faces*, as that's what we're ultimately debiasing against, even though we are training a model on a binary classification problem. We'll need to ensure that, **for faces**, our DB-VAE model both learns a representation of the unsupervised latent variables, captured by the distribution $q_\\phi(z|x)$, **and** outputs a supervised class prediction $z_o$, but that, **for negative examples**, it only outputs a class prediction $z_o$."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "XggIKYPRtOZR"
      },
      "source": [
        "### Defining the DB-VAE loss function\n",
        "\n",
        "This means we'll need to be a bit clever about the loss function for the DB-VAE. The form of the loss will depend on whether it's a face image or a non-face image that's being considered. \n",
        "\n",
        "For **face images**, our loss function will have two components:\n",
        "\n",
        "\n",
        "1.   **VAE loss ($L_{VAE}$)**: consists of the latent loss and the reconstruction loss.\n",
        "2.   **Classification loss ($L_y(y,\\hat{y})$)**: standard cross-entropy loss for a binary classification problem. \n",
        "\n",
        "In contrast, for images of **non-faces**, our loss function is solely the classification loss. \n",
        "\n",
        "We can write a single expression for the loss by defining an indicator variable $\\mathcal{I}_f$which reflects which training data are images of faces ($\\mathcal{I}_f(y) = 1$ ) and which are images of non-faces ($\\mathcal{I}_f(y) = 0$). Using this, we obtain:\n",
        "\n",
        "$$L_{total} = L_y(y,\\hat{y}) + \\mathcal{I}_f(y)\\Big[L_{VAE}\\Big]$$\n",
        "\n",
        "Let's write a function to define the DB-VAE loss function:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "VjieDs8Ovcqs"
      },
      "source": [
        "### Loss function for DB-VAE ###\n",
        "\n",
        "\"\"\"Loss function for DB-VAE.\n",
        "# Arguments\n",
        "    x: true input x\n",
        "    x_pred: reconstructed x\n",
        "    y: true label (face or not face)\n",
        "    y_logit: predicted labels\n",
        "    mu: mean of latent distribution (Q(z|X))\n",
        "    logsigma: log of standard deviation of latent distribution (Q(z|X))\n",
        "# Returns\n",
        "    total_loss: DB-VAE total loss\n",
        "    classification_loss = DB-VAE classification loss\n",
        "\"\"\"\n",
        "def debiasing_loss_function(x, x_pred, y, y_logit, mu, logsigma):\n",
        "\n",
        "  # TODO: call the relevant function to obtain VAE loss\n",
        "  vae_loss = vae_loss_function(x, x_pred, mu, logsigma)\n",
        "  # vae_loss = vae_loss_function('''TODO''') # TODO\n",
        "\n",
        "  # TODO: define the classification loss using sigmoid_cross_entropy\n",
        "  # https://www.tensorflow.org/api_docs/python/tf/nn/sigmoid_cross_entropy_with_logits\n",
        "  classification_loss = tf.nn.sigmoid_cross_entropy_with_logits(labels=y, logits=y_logit)\n",
        "  # classification_loss = # TODO\n",
        "\n",
        "  # Use the training data labels to create variable face_indicator:\n",
        "  #   indicator that reflects which training data are images of faces\n",
        "  face_indicator = tf.cast(tf.equal(y, 1), tf.float32)\n",
        "\n",
        "  # TODO: define the DB-VAE total loss! Use tf.reduce_mean to average over all\n",
        "  # samples\n",
        "  total_loss = tf.reduce_mean(\n",
        "      classification_loss + \n",
        "      face_indicator * vae_loss\n",
        "  )\n",
        "  # total_loss = # TODO\n",
        "\n",
        "  return total_loss, classification_loss"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "YIu_2LzNWwWY"
      },
      "source": [
        "### DB-VAE architecture\n",
        "\n",
        "Now we're ready to define the DB-VAE architecture. To build the DB-VAE, we will use the standard CNN classifier from above as our encoder, and then define a decoder network. We will create and initialize the two models, and then construct the end-to-end VAE. We will use a latent space with 100 latent variables.\n",
        "\n",
        "The decoder network will take as input the sampled latent variables, run them through a series of deconvolutional layers, and output a reconstruction of the original input image."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "JfWPHGrmyE7R"
      },
      "source": [
        "### Define the decoder portion of the DB-VAE ###\n",
        "\n",
        "n_filters = 12 # base number of convolutional filters, same as standard CNN\n",
        "latent_dim = 100 # number of latent variables\n",
        "\n",
        "def make_face_decoder_network():\n",
        "  # Functionally define the different layer types we will use\n",
        "  Conv2DTranspose = functools.partial(tf.keras.layers.Conv2DTranspose, padding='same', activation='relu')\n",
        "  BatchNormalization = tf.keras.layers.BatchNormalization\n",
        "  Flatten = tf.keras.layers.Flatten\n",
        "  Dense = functools.partial(tf.keras.layers.Dense, activation='relu')\n",
        "  Reshape = tf.keras.layers.Reshape\n",
        "\n",
        "  # Build the decoder network using the Sequential API\n",
        "  decoder = tf.keras.Sequential([\n",
        "    # Transform to pre-convolutional generation\n",
        "    Dense(units=4*4*6*n_filters),  # 4x4 feature maps (with 6N occurances)\n",
        "    Reshape(target_shape=(4, 4, 6*n_filters)),\n",
        "\n",
        "    # Upscaling convolutions (inverse of encoder)\n",
        "    Conv2DTranspose(filters=4*n_filters, kernel_size=3,  strides=2),\n",
        "    Conv2DTranspose(filters=2*n_filters, kernel_size=3,  strides=2),\n",
        "    Conv2DTranspose(filters=1*n_filters, kernel_size=5,  strides=2),\n",
        "    Conv2DTranspose(filters=3, kernel_size=5,  strides=2),\n",
        "  ])\n",
        "\n",
        "  return decoder"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "yWCMu12w1BuD"
      },
      "source": [
        "Now, we will put this decoder together with the standard CNN classifier as our encoder to define the DB-VAE. Note that at this point, there is nothing special about how we put the model together that makes it a \"debiasing\" model -- that will come when we define the training operation. Here, we will define the core VAE architecture by sublassing the `Model` class; defining encoding, reparameterization, and decoding operations; and calling the network end-to-end."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "dSFDcFBL13c3"
      },
      "source": [
        "### Defining and creating the DB-VAE ###\n",
        "\n",
        "class DB_VAE(tf.keras.Model):\n",
        "  def __init__(self, latent_dim):\n",
        "    super(DB_VAE, self).__init__()\n",
        "    self.latent_dim = latent_dim\n",
        "\n",
        "    # Define the number of outputs for the encoder. Recall that we have \n",
        "    # `latent_dim` latent variables, as well as a supervised output for the \n",
        "    # classification.\n",
        "    num_encoder_dims = 2*self.latent_dim + 1\n",
        "\n",
        "    self.encoder = make_standard_classifier(num_encoder_dims)\n",
        "    self.decoder = make_face_decoder_network()\n",
        "\n",
        "  # function to feed images into encoder, encode the latent space, and output\n",
        "  #   classification probability \n",
        "  def encode(self, x):\n",
        "    # encoder output\n",
        "    encoder_output = self.encoder(x)\n",
        "\n",
        "    # classification prediction\n",
        "    y_logit = tf.expand_dims(encoder_output[:, 0], -1)\n",
        "    # latent variable distribution parameters\n",
        "    z_mean = encoder_output[:, 1:self.latent_dim+1] \n",
        "    z_logsigma = encoder_output[:, self.latent_dim+1:]\n",
        "\n",
        "    return y_logit, z_mean, z_logsigma\n",
        "\n",
        "  # VAE reparameterization: given a mean and logsigma, sample latent variables\n",
        "  def reparameterize(self, z_mean, z_logsigma):\n",
        "    # TODO: call the sampling function defined above\n",
        "    z = sampling(z_mean, z_logsigma)\n",
        "    # z = # TODO\n",
        "    return z\n",
        "\n",
        "  # Decode the latent space and output reconstruction\n",
        "  def decode(self, z):\n",
        "    # TODO: use the decoder to output the reconstruction\n",
        "    reconstruction = self.decoder(z)\n",
        "    # reconstruction = # TODO\n",
        "    return reconstruction\n",
        "\n",
        "  # The call function will be used to pass inputs x through the core VAE\n",
        "  def call(self, x): \n",
        "    # Encode input to a prediction and latent space\n",
        "    y_logit, z_mean, z_logsigma = self.encode(x)\n",
        "\n",
        "    # TODO: reparameterization\n",
        "    z = self.reparameterize(z_mean, z_logsigma)\n",
        "    # z = # TODO\n",
        "\n",
        "    # TODO: reconstruction\n",
        "    recon = self.decode(z)\n",
        "    # recon = # TODO\n",
        "    return y_logit, z_mean, z_logsigma, recon\n",
        "\n",
        "  # Predict face or not face logit for given input x\n",
        "  def predict(self, x):\n",
        "    y_logit, z_mean, z_logsigma = self.encode(x)\n",
        "    return y_logit\n",
        "\n",
        "dbvae = DB_VAE(latent_dim)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "M-clbYAj2waY"
      },
      "source": [
        "As stated, the encoder architecture is identical to the CNN from earlier in this lab. Note the outputs of our constructed DB_VAE model in the `call` function: `y_logit, z_mean, z_logsigma, z`. Think carefully about why each of these are outputted and their significance to the problem at hand.\n",
        "\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "nbDNlslgQc5A"
      },
      "source": [
        "### Adaptive resampling for automated debiasing with DB-VAE\n",
        "\n",
        "So, how can we actually use DB-VAE to train a debiased facial detection classifier?\n",
        "\n",
        "Recall the DB-VAE architecture: as input images are fed through the network, the encoder learns an estimate $\\mathcal{Q}(z|X)$ of the latent space. We want to increase the relative frequency of rare data by increased sampling of under-represented regions of the latent space. We can approximate $\\mathcal{Q}(z|X)$ using the frequency distributions of each of the learned latent variables, and then define the probability distribution of selecting a given datapoint $x$ based on this approximation. These probability distributions will be used during training to re-sample the data.\n",
        "\n",
        "You'll write a function to execute this update of the sampling probabilities, and then call this function within the DB-VAE training loop to actually debias the model. "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Fej5FDu37cf7"
      },
      "source": [
        "First, we've defined a short helper function `get_latent_mu` that returns the latent variable means returned by the encoder after a batch of images is inputted to the network:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "ewWbf7TE7wVc"
      },
      "source": [
        "# Function to return the means for an input image batch\n",
        "def get_latent_mu(images, dbvae, batch_size=1024):\n",
        "  N = images.shape[0]\n",
        "  mu = np.zeros((N, latent_dim))\n",
        "  for start_ind in range(0, N, batch_size):\n",
        "    end_ind = min(start_ind+batch_size, N+1)\n",
        "    batch = (images[start_ind:end_ind]).astype(np.float32)/255.\n",
        "    _, batch_mu, _ = dbvae.encode(batch)\n",
        "    mu[start_ind:end_ind] = batch_mu\n",
        "  return mu"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "wn4yK3SC72bo"
      },
      "source": [
        "Now, let's define the actual resampling algorithm `get_training_sample_probabilities`. Importantly note the argument `smoothing_fac`. This parameter tunes the degree of debiasing: for `smoothing_fac=0`, the re-sampled training set will tend towards falling uniformly over the latent space, i.e., the most extreme debiasing."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "HiX9pmmC7_wn"
      },
      "source": [
        "### Resampling algorithm for DB-VAE ###\n",
        "\n",
        "'''Function that recomputes the sampling probabilities for images within a batch\n",
        "      based on how they distribute across the training data'''\n",
        "def get_training_sample_probabilities(images, dbvae, bins=10, smoothing_fac=0.001): \n",
        "    print(\"Recomputing the sampling probabilities\")\n",
        "    \n",
        "    # TODO: run the input batch and get the latent variable means\n",
        "    mu = get_latent_mu(images, dbvae)\n",
        "    # mu = get_latent_mu('''TODO''') # TODO\n",
        "\n",
        "    # sampling probabilities for the images\n",
        "    training_sample_p = np.zeros(mu.shape[0])\n",
        "    \n",
        "    # consider the distribution for each latent variable \n",
        "    for i in range(latent_dim):\n",
        "      \n",
        "        latent_distribution = mu[:,i]\n",
        "        # generate a histogram of the latent distribution\n",
        "        hist_density, bin_edges =  np.histogram(latent_distribution, density=True, bins=bins)\n",
        "\n",
        "        # find which latent bin every data sample falls in \n",
        "        bin_edges[0] = -float('inf')\n",
        "        bin_edges[-1] = float('inf')\n",
        "        \n",
        "        # TODO: call the digitize function to find which bins in the latent distribution \n",
        "        #    every data sample falls in to\n",
        "        # https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.digitize.html\n",
        "        bin_idx = np.digitize(latent_distribution, bin_edges)\n",
        "        # bin_idx = np.digitize('''TODO''', '''TODO''') # TODO\n",
        "\n",
        "        # smooth the density function\n",
        "        hist_smoothed_density = hist_density + smoothing_fac\n",
        "        hist_smoothed_density = hist_smoothed_density / np.sum(hist_smoothed_density)\n",
        "\n",
        "        # invert the density function \n",
        "        p = 1.0/(hist_smoothed_density[bin_idx-1])\n",
        "        \n",
        "        # TODO: normalize all probabilities\n",
        "        p = p / np.sum(p)\n",
        "        # p = # TODO\n",
        "        \n",
        "        # TODO: update sampling probabilities by considering whether the newly\n",
        "        #     computed p is greater than the existing sampling probabilities.\n",
        "        training_sample_p = np.maximum(p, training_sample_p)\n",
        "        # training_sample_p = # TODO\n",
        "        \n",
        "    # final normalization\n",
        "    training_sample_p /= np.sum(training_sample_p)\n",
        "\n",
        "    return training_sample_p"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pF14fQkVUs-a"
      },
      "source": [
        "Now that we've defined the resampling update, we can train our DB-VAE model on the CelebA/ImageNet training data, and run the above operation to re-weight the importance of particular data points as we train the model. Remember again that we only want to debias for features relevant to *faces*, not the set of negative examples. Complete the code block below to execute the training loop!"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "xwQs-Gu5bKEK"
      },
      "source": [
        "### Training the DB-VAE ###\n",
        "\n",
        "# Hyperparameters\n",
        "batch_size = 32\n",
        "learning_rate = 5e-4\n",
        "latent_dim = 100\n",
        "\n",
        "# DB-VAE needs slightly more epochs to train since its more complex than \n",
        "# the standard classifier so we use 6 instead of 2\n",
        "num_epochs = 6  \n",
        "\n",
        "# instantiate a new DB-VAE model and optimizer\n",
        "dbvae = DB_VAE(100)\n",
        "optimizer = tf.keras.optimizers.Adam(learning_rate)\n",
        "\n",
        "# To define the training operation, we will use tf.function which is a powerful tool \n",
        "#   that lets us turn a Python function into a TensorFlow computation graph.\n",
        "@tf.function\n",
        "def debiasing_train_step(x, y):\n",
        "\n",
        "  with tf.GradientTape() as tape:\n",
        "    # Feed input x into dbvae. Note that this is using the DB_VAE call function!\n",
        "    y_logit, z_mean, z_logsigma, x_recon = dbvae(x)\n",
        "\n",
        "    '''TODO: call the DB_VAE loss function to compute the loss'''\n",
        "    loss, class_loss = debiasing_loss_function(x, x_recon, y, y_logit, z_mean, z_logsigma)\n",
        "    # loss, class_loss = debiasing_loss_function('''TODO arguments''') # TODO\n",
        "  \n",
        "  '''TODO: use the GradientTape.gradient method to compute the gradients.\n",
        "     Hint: this is with respect to the trainable_variables of the dbvae.'''\n",
        "  grads = tape.gradient(loss, dbvae.trainable_variables)\n",
        "  # grads = tape.gradient('''TODO''', '''TODO''') # TODO\n",
        "\n",
        "  # apply gradients to variables\n",
        "  optimizer.apply_gradients(zip(grads, dbvae.trainable_variables))\n",
        "  return loss\n",
        "\n",
        "# get training faces from data loader\n",
        "all_faces = loader.get_all_train_faces()\n",
        "\n",
        "if hasattr(tqdm, '_instances'): tqdm._instances.clear() # clear if it exists\n",
        "\n",
        "# The training loop -- outer loop iterates over the number of epochs\n",
        "for i in range(num_epochs):\n",
        "\n",
        "  IPython.display.clear_output(wait=True)\n",
        "  print(\"Starting epoch {}/{}\".format(i+1, num_epochs))\n",
        "\n",
        "  # Recompute data sampling proabilities\n",
        "  '''TODO: recompute the sampling probabilities for debiasing'''\n",
        "  p_faces = get_training_sample_probabilities(all_faces, dbvae)\n",
        "  # p_faces = get_training_sample_probabilities('''TODO''', '''TODO''') # TODO\n",
        "  \n",
        "  # get a batch of training data and compute the training step\n",
        "  for j in tqdm(range(loader.get_train_size() // batch_size)):\n",
        "    # load a batch of data\n",
        "    (x, y) = loader.get_batch(batch_size, p_pos=p_faces)\n",
        "    # loss optimization\n",
        "    loss = debiasing_train_step(x, y)\n",
        "    \n",
        "    # plot the progress every 200 steps\n",
        "    if j % 500 == 0: \n",
        "      mdl.util.plot_sample(x, y, dbvae)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "uZBlWDPOVcHg"
      },
      "source": [
        "Wonderful! Now we should have a trained and (hopefully!) debiased facial classification model, ready for evaluation!"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Eo34xC7MbaiQ"
      },
      "source": [
        "## 2.6 Evaluation of DB-VAE on Test Dataset\n",
        "\n",
        "Finally let's test our DB-VAE model on the test dataset, looking specifically at its accuracy on each the \"Dark Male\", \"Dark Female\", \"Light Male\", and \"Light Female\" demographics. We will compare the performance of this debiased model against the (potentially biased) standard CNN from earlier in the lab."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "bgK77aB9oDtX"
      },
      "source": [
        "dbvae_logits = [dbvae.predict(np.array(x, dtype=np.float32)) for x in test_faces]\n",
        "dbvae_probs = tf.squeeze(tf.sigmoid(dbvae_logits))\n",
        "\n",
        "xx = np.arange(len(keys))\n",
        "plt.bar(xx, standard_classifier_probs.numpy().mean(1), width=0.2, label=\"Standard CNN\")\n",
        "plt.bar(xx+0.2, dbvae_probs.numpy().mean(1), width=0.2, label=\"DB-VAE\")\n",
        "plt.xticks(xx, keys); \n",
        "plt.title(\"Network predictions on test dataset\")\n",
        "plt.ylabel(\"Probability\"); plt.legend(bbox_to_anchor=(1.04,1), loc=\"upper left\");\n"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "rESoXRPQo_mq"
      },
      "source": [
        "## 2.7 Conclusion and submission information\n",
        "\n",
        "We encourage you to think about and maybe even address some questions raised by the approach and results outlined here:\n",
        "\n",
        "*  How does the accuracy of the DB-VAE across the four demographics compare to that of the standard CNN? Do you find this result surprising in any way?\n",
        "*  How can the performance of the DB-VAE classifier be improved even further? We purposely did not optimize hyperparameters to leave this up to you!\n",
        "*  In which applications (either related to facial detection or not!) would debiasing in this way be desired? Are there applications where you may not want to debias your model? \n",
        "* Do you think it should be necessary for companies to demonstrate that their models, particularly in the context of tasks like facial detection, are not biased? If so, do you have thoughts on how this could be standardized and implemented?\n",
        "* Do you have ideas for other ways to address issues of bias, particularly in terms of the training data?\n",
        "\n",
        "Try to optimize your model to achieve improved performance. **MIT students and affiliates will be eligible for prizes during the IAP offering.** To enter the competition, MIT students and affiliates should upload the following to the course Canvas:\n",
        "\n",
        "* Jupyter notebook with the code you used to generate your results;\n",
        "* copy of the bar plot from section 2.6 showing the performance of your model;\n",
        "* a description and/or diagram of the architecture and hyperparameters you used -- if there are any additional or interesting modifications you made to the template code, please include these in your description;\n",
        "* discussion of why these modifications helped improve performance.\n",
        "\n",
        "Hopefully this lab has shed some light on a few concepts, from vision based tasks, to VAEs, to algorithmic bias. We like to think it has, but we're biased ;).\n",
        "\n",
        "<img src=\"https://i.ibb.co/BjLSRMM/ezgif-2-253dfd3f9097.gif\" />"
      ]
    }
  ]
}