notebooks/cifar10_example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<center>  <h1> SQwash: Distributionally Robust Learning in PyTorch with 1 Additional Line of Code </h1> </center>\n",
    "<center> Krishna Pillutla, Yassine Laguel, Jérôme Malick, Zaid Harchaoui </center>\n",
    "\n",
    "In this notebook we demonstrate how the SQwash package can be used to train distributionally robust models in PyTorch with one additional line of code using the CIFAR-10 dataset. \n",
    "\n",
    "## 1. Define the model\n",
    "We start by defining a simple convolutional neural network. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch\n",
    "import torch.nn as nn\n",
    "torch.manual_seed(0)\n",
    "import random\n",
    "random.seed(1)\n",
    "\n",
    "output_sizes_dict = {1: 16, 2: 8}\n",
    "\n",
    "class ConvCifar(nn.Module):\n",
    "    def __init__(self, num_classes=10, num_layers=5, num_channels=256):\n",
    "        super().__init__()\n",
    "        lst = [nn.Conv2d(3, num_channels, 3, padding=1, stride=2)]\n",
    "        for i in range(1, num_layers):\n",
    "            stride = 2 if i < 3 else 1 # stride the first three convolutions\n",
    "            lst.append(nn.Conv2d(num_channels, num_channels, 3, padding=1, stride=stride))\n",
    "            lst.append(nn.ReLU(inplace=True))\n",
    "        self.features = nn.Sequential(*lst)\n",
    "        assert num_layers >= 1\n",
    "        output_size = output_sizes_dict.get(num_layers, 4)\n",
    "        self.classifier = nn.Linear(num_channels * output_size * output_size, num_classes)\n",
    "\n",
    "    def forward(self, x):\n",
    "        x = self.features(x)\n",
    "        x = x.view(x.size(0), -1)\n",
    "        return self.classifier(x)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "device = torch.device('cuda:0') if torch.cuda.is_available() else torch.device('cpu')\n",
    "net = ConvCifar().to(device)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Load the data\n",
    "\n",
    "Let us load the CIFAR-10 dataset and the corresponding dataloader. For details, see [this PyTorch tutorial](https://pytorch.org/tutorials/beginner/blitz/cifar10_tutorial.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Files already downloaded and verified\n",
      "Files already downloaded and verified\n"
     ]
    }
   ],
   "source": [
    "import torchvision\n",
    "import torchvision.transforms as transforms\n",
    "\n",
    "transform = transforms.Compose(\n",
    "    [transforms.ToTensor(),\n",
    "     transforms.Normalize((0.4914, 0.4822, 0.4465), (0.2023, 0.1994, 0.2010))]\n",
    ")\n",
    "\n",
    "batch_size = 128\n",
    "\n",
    "trainset = torchvision.datasets.CIFAR10(root='./data', train=True,\n",
    "                                        download=True, transform=transform)\n",
    "trainloader = torch.utils.data.DataLoader(trainset, batch_size=batch_size,\n",
    "                                          shuffle=True, num_workers=2)\n",
    "\n",
    "testset = torchvision.datasets.CIFAR10(root='./data', train=False,\n",
    "                                       download=True, transform=transform)\n",
    "testloader = torch.utils.data.DataLoader(testset, batch_size=batch_size,\n",
    "                                         shuffle=False, num_workers=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us write a simple function to calculate the test accuracy of the model. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Accuracy at initialization = 10.0 %\n"
     ]
    }
   ],
   "source": [
    "@torch.no_grad()\n",
    "def compute_accuracy(net, dataloader):\n",
    "    correct = 0\n",
    "    total = 0\n",
    "    for x, y in dataloader:\n",
    "        x, y = x.to(device), y.to(device)\n",
    "        pred = net(x)\n",
    "        correct += (pred.argmax(axis=1) == y).sum().item()\n",
    "        total += pred.shape[0]\n",
    "    return correct / total\n",
    "print('Accuracy at initialization =', compute_accuracy(net, testloader)*100, '%')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Train a model with the cross entropy loss (usual training)\n",
    "Let us write out a simple training loop to train this model with the cross entropy loss. This code is taken from the [PyTorch tutorial](https://pytorch.org/tutorials/beginner/blitz/cifar10_tutorial.html). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Epoch\tTrain Loss\tTest Accuracy\tTime\n",
      "1\t1.97\t\t37.60% \t\t9.12s\n",
      "2\t1.55\t\t49.65% \t\t8.89s\n",
      "3\t1.36\t\t52.28% \t\t8.65s\n",
      "4\t1.24\t\t57.01% \t\t8.72s\n",
      "5\t1.14\t\t58.52% \t\t9.06s\n",
      "6\t1.04\t\t61.80% \t\t9.38s\n",
      "7\t0.95\t\t61.47% \t\t9.49s\n",
      "8\t0.86\t\t64.08% \t\t9.01s\n",
      "9\t0.78\t\t65.06% \t\t9.38s\n",
      "10\t0.69\t\t63.04% \t\t9.2s\n",
      "11\t0.60\t\t65.86% \t\t9.07s\n",
      "12\t0.51\t\t66.59% \t\t9.53s\n",
      "13\t0.42\t\t66.72% \t\t9.43s\n",
      "14\t0.33\t\t66.91% \t\t9.96s\n",
      "15\t0.25\t\t66.53% \t\t9.1s\n",
      "16\t0.18\t\t65.40% \t\t9.14s\n",
      "17\t0.12\t\t67.83% \t\t8.94s\n",
      "18\t0.07\t\t67.28% \t\t8.61s\n",
      "19\t0.06\t\t67.68% \t\t8.63s\n",
      "20\t0.04\t\t68.14% \t\t9.05s\n",
      "21\t0.03\t\t68.12% \t\t9.51s\n",
      "22\t0.01\t\t69.42% \t\t9.79s\n",
      "23\t0.00\t\t69.73% \t\t9.8s\n",
      "24\t0.00\t\t69.87% \t\t9.63s\n",
      "25\t0.00\t\t69.95% \t\t9.85s\n",
      "26\t0.00\t\t69.94% \t\t9.39s\n",
      "27\t0.00\t\t70.05% \t\t9.38s\n",
      "28\t0.00\t\t69.96% \t\t9.29s\n",
      "29\t0.00\t\t70.05% \t\t9.55s\n",
      "30\t0.00\t\t69.92% \t\t8.84s\n",
      "31\t0.00\t\t70.08% \t\t8.55s\n",
      "32\t0.00\t\t69.94% \t\t8.8s\n",
      "33\t0.00\t\t70.01% \t\t9.15s\n",
      "34\t0.00\t\t69.93% \t\t9.28s\n",
      "35\t0.00\t\t69.94% \t\t9.52s\n",
      "36\t0.00\t\t69.92% \t\t9.37s\n",
      "37\t0.00\t\t70.00% \t\t9.63s\n",
      "38\t0.00\t\t69.95% \t\t9.05s\n",
      "39\t0.00\t\t70.03% \t\t9.06s\n",
      "40\t0.00\t\t70.04% \t\t9.84s\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "net = ConvCifar().to(device)\n",
    "criterion = torch.nn.CrossEntropyLoss()\n",
    "optimizer = torch.optim.SGD(net.parameters(), lr=0.04, momentum=0.0)\n",
    "\n",
    "logs = []  # test accuracy\n",
    "\n",
    "print('Epoch\\tTrain Loss\\tTest Accuracy\\tTime')\n",
    "\n",
    "for epoch in range(40):  # loop over the dataset multiple times\n",
    "    running_loss = 0.0\n",
    "    start_time = time.time()\n",
    "    for i, (x, y) in enumerate(trainloader):\n",
    "        x, y = x.to(device), y.to(device) \n",
    "        # zero the parameter gradients\n",
    "        optimizer.zero_grad()\n",
    "        # forward\n",
    "        outputs = net(x)\n",
    "        loss = criterion(outputs, y)\n",
    "        # backward\n",
    "        loss.backward()\n",
    "        # optimize\n",
    "        optimizer.step()\n",
    "        # Statistics\n",
    "        running_loss = running_loss * i / (i+1) + loss.item() / (i+1)\n",
    "    logs.append(compute_accuracy(net, testloader))\n",
    "    print(f'{epoch+1}\\t{running_loss:.2f}\\t\\t{100 * logs[-1]:.2f}%', \n",
    "          f'\\t\\t{round(time.time() - start_time, 2)}s')\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Train the same model to be distributionally robust using `sqwash`\n",
    "\n",
    "To get distributional robustness with `sqwash`, we only need to start by\n",
    "- defining the `SuperquantileReducer`, and,\n",
    "- setting `reduction='none'` in the criterion. \n",
    "\n",
    "With this in place, the 1 additional line we need to make to our training loop is \n",
    "- reduce the losses with the `SuperquantileReducer` object defined above. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Epoch\tTrain Loss\tTest Accuracy\tTime\n",
      "1\t2.27\t\t33.41% \t\t9.67s\n",
      "2\t2.06\t\t40.29% \t\t9.48s\n",
      "3\t1.90\t\t48.27% \t\t9.44s\n",
      "4\t1.80\t\t53.66% \t\t9.16s\n",
      "5\t1.70\t\t53.76% \t\t8.89s\n",
      "6\t1.59\t\t54.94% \t\t8.61s\n",
      "7\t1.49\t\t60.92% \t\t9.09s\n",
      "8\t1.38\t\t62.49% \t\t9.15s\n",
      "9\t1.27\t\t64.47% \t\t9.48s\n",
      "10\t1.15\t\t64.37% \t\t9.91s\n",
      "11\t1.00\t\t64.73% \t\t9.49s\n",
      "12\t0.86\t\t65.20% \t\t9.69s\n",
      "13\t0.69\t\t67.09% \t\t9.49s\n",
      "14\t0.52\t\t66.46% \t\t9.49s\n",
      "15\t0.37\t\t66.40% \t\t9.73s\n",
      "16\t0.25\t\t66.41% \t\t9.41s\n",
      "17\t0.18\t\t66.97% \t\t9.41s\n",
      "18\t0.13\t\t68.14% \t\t8.72s\n",
      "19\t0.10\t\t63.97% \t\t8.94s\n",
      "20\t0.08\t\t67.49% \t\t9.27s\n",
      "21\t0.06\t\t67.75% \t\t9.05s\n",
      "22\t0.05\t\t67.44% \t\t9.33s\n",
      "23\t0.03\t\t68.72% \t\t9.88s\n",
      "24\t0.03\t\t68.82% \t\t9.4s\n",
      "25\t0.04\t\t68.08% \t\t9.48s\n",
      "26\t0.03\t\t68.11% \t\t8.9s\n",
      "27\t0.01\t\t68.89% \t\t9.45s\n",
      "28\t0.00\t\t69.87% \t\t9.64s\n",
      "29\t0.00\t\t70.34% \t\t9.63s\n",
      "30\t0.00\t\t70.45% \t\t9.7s\n",
      "31\t0.00\t\t70.55% \t\t9.18s\n",
      "32\t0.00\t\t70.56% \t\t9.39s\n",
      "33\t0.00\t\t70.46% \t\t8.88s\n",
      "34\t0.00\t\t70.53% \t\t8.97s\n",
      "35\t0.00\t\t70.56% \t\t9.19s\n",
      "36\t0.00\t\t70.54% \t\t9.0s\n",
      "37\t0.00\t\t70.54% \t\t9.54s\n",
      "38\t0.00\t\t70.55% \t\t9.67s\n",
      "39\t0.00\t\t70.50% \t\t9.76s\n",
      "40\t0.00\t\t70.46% \t\t9.44s\n"
     ]
    }
   ],
   "source": [
    "from sqwash import SuperquantileReducer\n",
    "\n",
    "net = ConvCifar().to(device)\n",
    "reducer = SuperquantileReducer(superquantile_tail_fraction=0.6)  # keep 60% of the worst losses in each batch\n",
    "criterion = torch.nn.CrossEntropyLoss(reduction='none')  # NOTE: set reduction='none' so that we get the batch losses\n",
    "optimizer = torch.optim.SGD(net.parameters(), lr=0.04, momentum=0.0)\n",
    "\n",
    "logs_sq = []  # test accuracy\n",
    "\n",
    "print('Epoch\\tTrain Loss\\tTest Accuracy\\tTime')\n",
    "\n",
    "for epoch in range(40):  # loop over the dataset multiple times\n",
    "    running_loss = 0.0\n",
    "    start_time = time.time()\n",
    "    for i, (x, y) in enumerate(trainloader):\n",
    "        x, y = x.to(device), y.to(device) \n",
    "        # zero the parameter gradients\n",
    "        optimizer.zero_grad()\n",
    "        # forward\n",
    "        outputs = net(x)\n",
    "        batch_loss = criterion(outputs, y)\n",
    "        loss = reducer(batch_loss)  # The 1 additional line to reduce batch losses using the superquantile\n",
    "        # backward\n",
    "        loss.backward()\n",
    "        # optimize\n",
    "        optimizer.step()\n",
    "        # Statistics\n",
    "        running_loss = running_loss * i / (i+1) + loss.item() / (i+1)\n",
    "    logs_sq.append(compute_accuracy(net, testloader))\n",
    "    print(f'{epoch+1}\\t{running_loss:.2f}\\t\\t{100 * logs_sq[-1]:.2f}%', \n",
    "          f'\\t\\t{round(time.time() - start_time, 2)}s')\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Make a plot to visualize the test loss\n",
    "Let us plot the average test loss for regular training and the distributionally robust training."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0.6, 0.71)"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "\n",
    "plt.plot(logs, label='Usual learning', linewidth=3, linestyle='dotted')\n",
    "plt.plot(logs_sq, label='Distributionally robust\\nlearning with SQwash', linewidth=3, linestyle='solid')\n",
    "plt.xlabel('Epochs', fontsize=18)\n",
    "plt.ylabel('Accuracy %', fontsize=18)\n",
    "plt.title('SQwash in action (CIFAR-10)', fontsize=18)\n",
    "plt.legend(bbox_to_anchor=(1.04,0.5), loc=\"center left\", borderaxespad=0, fontsize=18)\n",
    "plt.ylim((0.6, 0.71))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More generally, we find that distributionally robust learning with the superquantile helps with improving the performance on the worst-performing subgroups of data. The following figure, taken from [this paper](https://ieeexplore.ieee.org/document/9400318) illustrates this for the case of distributed training of machine learning models on mobile devices (a.k.a. federated learning)\n",
    "\n",
    "![](../fig/usual_vs_sq.png)\n",
    "\n",
    "From this historgram of the misclassification error (= 1 - Accuracy), we see that the right tail is thinner for the `SQ`, which is based on distributionally robust learning with the superquantile. \n",
    "\n",
    "This denotes smaller misclassification error on the subgroups of data with the worst performance. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "PyT 1.7, TF 1.5",
   "language": "python",
   "name": "pyt17_tf15"
  },
  "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.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}