2_Training.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Computer Vision Nanodegree\n",
    "\n",
    "## Project: Image Captioning\n",
    "\n",
    "---\n",
    "\n",
    "In this notebook, you will train your CNN-RNN model.  \n",
    "\n",
    "You are welcome and encouraged to try out many different architectures and hyperparameters when searching for a good model.\n",
    "\n",
    "This does have the potential to make the project quite messy!  Before submitting your project, make sure that you clean up:\n",
    "- the code you write in this notebook.  The notebook should describe how to train a single CNN-RNN architecture, corresponding to your final choice of hyperparameters.  You should structure the notebook so that the reviewer can replicate your results by running the code in this notebook.  \n",
    "- the output of the code cell in **Step 2**.  The output should show the output obtained when training the model from scratch.\n",
    "\n",
    "This notebook **will be graded**.  \n",
    "\n",
    "Feel free to use the links below to navigate the notebook:\n",
    "- [Step 1](#step1): Training Setup\n",
    "- [Step 2](#step2): Train your Model\n",
    "- [Step 3](#step3): (Optional) Validate your Model"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step1'></a>\n",
    "## Step 1: Training Setup\n",
    "\n",
    "In this step of the notebook, you will customize the training of your CNN-RNN model by specifying hyperparameters and setting other options that are important to the training procedure.  The values you set now will be used when training your model in **Step 2** below.\n",
    "\n",
    "You should only amend blocks of code that are preceded by a `TODO` statement.  **Any code blocks that are not preceded by a `TODO` statement should not be modified**.\n",
    "\n",
    "### Task #1\n",
    "\n",
    "Begin by setting the following variables:\n",
    "- `batch_size` - the batch size of each training batch.  It is the number of image-caption pairs used to amend the model weights in each training step. \n",
    "- `vocab_threshold` - the minimum word count threshold.  Note that a larger threshold will result in a smaller vocabulary, whereas a smaller threshold will include rarer words and result in a larger vocabulary.  \n",
    "- `vocab_from_file` - a Boolean that decides whether to load the vocabulary from file. \n",
    "- `embed_size` - the dimensionality of the image and word embeddings.  \n",
    "- `hidden_size` - the number of features in the hidden state of the RNN decoder.  \n",
    "- `num_epochs` - the number of epochs to train the model.  We recommend that you set `num_epochs=3`, but feel free to increase or decrease this number as you wish.  [This paper](https://arxiv.org/pdf/1502.03044.pdf) trained a captioning model on a single state-of-the-art GPU for 3 days, but you'll soon see that you can get reasonable results in a matter of a few hours!  (_But of course, if you want your model to compete with current research, you will have to train for much longer._)\n",
    "- `save_every` - determines how often to save the model weights.  We recommend that you set `save_every=1`, to save the model weights after each epoch.  This way, after the `i`th epoch, the encoder and decoder weights will be saved in the `models/` folder as `encoder-i.pkl` and `decoder-i.pkl`, respectively.\n",
    "- `print_every` - determines how often to print the batch loss to the Jupyter notebook while training.  Note that you **will not** observe a monotonic decrease in the loss function while training - this is perfectly fine and completely expected!  You are encouraged to keep this at its default value of `100` to avoid clogging the notebook, but feel free to change it.\n",
    "- `log_file` - the name of the text file containing - for every step - how the loss and perplexity evolved during training.\n",
    "\n",
    "If you're not sure where to begin to set some of the values above, you can peruse [this paper](https://arxiv.org/pdf/1502.03044.pdf) and [this paper](https://arxiv.org/pdf/1411.4555.pdf) for useful guidance!  **To avoid spending too long on this notebook**, you are encouraged to consult these suggested research papers to obtain a strong initial guess for which hyperparameters are likely to work best.  Then, train a single model, and proceed to the next notebook (**3_Inference.ipynb**).  If you are unhappy with your performance, you can return to this notebook to tweak the hyperparameters (and/or the architecture in **model.py**) and re-train your model.\n",
    "\n",
    "### Question 1\n",
    "\n",
    "**Question:** Describe your CNN-RNN architecture in detail.  With this architecture in mind, how did you select the values of the variables in Task 1?  If you consulted a research paper detailing a successful implementation of an image captioning model, please provide the reference.\n",
    "\n",
    "**Answer:** \n",
    "\n",
    "\n",
    "### (Optional) Task #2\n",
    "\n",
    "Note that we have provided a recommended image transform `transform_train` for pre-processing the training images, but you are welcome (and encouraged!) to modify it as you wish.  When modifying this transform, keep in mind that:\n",
    "- the images in the dataset have varying heights and widths, and \n",
    "- if using a pre-trained model, you must perform the corresponding appropriate normalization.\n",
    "\n",
    "### Question 2\n",
    "\n",
    "**Question:** How did you select the transform in `transform_train`?  If you left the transform at its provided value, why do you think that it is a good choice for your CNN architecture?\n",
    "\n",
    "**Answer:** \n",
    "\n",
    "### Task #3\n",
    "\n",
    "Next, you will specify a Python list containing the learnable parameters of the model.  For instance, if you decide to make all weights in the decoder trainable, but only want to train the weights in the embedding layer of the encoder, then you should set `params` to something like:\n",
    "```\n",
    "params = list(decoder.parameters()) + list(encoder.embed.parameters()) \n",
    "```\n",
    "\n",
    "### Question 3\n",
    "\n",
    "**Question:** How did you select the trainable parameters of your architecture?  Why do you think this is a good choice?\n",
    "\n",
    "**Answer:** \n",
    "\n",
    "### Task #4\n",
    "\n",
    "Finally, you will select an [optimizer](http://pytorch.org/docs/master/optim.html#torch.optim.Optimizer).\n",
    "\n",
    "### Question 4\n",
    "\n",
    "**Question:** How did you select the optimizer used to train your model?\n",
    "\n",
    "**Answer:** "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch\n",
    "import torch.nn as nn\n",
    "from torchvision import transforms\n",
    "import sys\n",
    "sys.path.append('/opt/cocoapi/PythonAPI')\n",
    "from pycocotools.coco import COCO\n",
    "from data_loader import get_loader\n",
    "from model import EncoderCNN, DecoderRNN\n",
    "import math\n",
    "\n",
    "\n",
    "## TODO #1: Select appropriate values for the Python variables below.\n",
    "batch_size = ...          # batch size\n",
    "vocab_threshold = ...        # minimum word count threshold\n",
    "vocab_from_file = ...    # if True, load existing vocab file\n",
    "embed_size = ...           # dimensionality of image and word embeddings\n",
    "hidden_size = ...          # number of features in hidden state of the RNN decoder\n",
    "num_epochs = 3             # number of training epochs\n",
    "save_every = 1             # determines frequency of saving model weights\n",
    "print_every = 100          # determines window for printing average loss\n",
    "log_file = 'training_log.txt'       # name of file with saved training loss and perplexity\n",
    "\n",
    "# (Optional) TODO #2: Amend the image transform below.\n",
    "transform_train = transforms.Compose([ \n",
    "    transforms.Resize(256),                          # smaller edge of image resized to 256\n",
    "    transforms.RandomCrop(224),                      # get 224x224 crop from random location\n",
    "    transforms.RandomHorizontalFlip(),               # horizontally flip image with probability=0.5\n",
    "    transforms.ToTensor(),                           # convert the PIL Image to a tensor\n",
    "    transforms.Normalize((0.485, 0.456, 0.406),      # normalize image for pre-trained model\n",
    "                         (0.229, 0.224, 0.225))])\n",
    "\n",
    "# Build data loader.\n",
    "data_loader = get_loader(transform=transform_train,\n",
    "                         mode='train',\n",
    "                         batch_size=batch_size,\n",
    "                         vocab_threshold=vocab_threshold,\n",
    "                         vocab_from_file=vocab_from_file)\n",
    "\n",
    "# The size of the vocabulary.\n",
    "vocab_size = len(data_loader.dataset.vocab)\n",
    "\n",
    "# Initialize the encoder and decoder. \n",
    "encoder = EncoderCNN(embed_size)\n",
    "decoder = DecoderRNN(embed_size, hidden_size, vocab_size)\n",
    "\n",
    "# Move models to GPU if CUDA is available. \n",
    "device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n",
    "encoder.to(device)\n",
    "decoder.to(device)\n",
    "\n",
    "# Define the loss function. \n",
    "criterion = nn.CrossEntropyLoss().cuda() if torch.cuda.is_available() else nn.CrossEntropyLoss()\n",
    "\n",
    "# TODO #3: Specify the learnable parameters of the model.\n",
    "params = ...\n",
    "\n",
    "# TODO #4: Define the optimizer.\n",
    "optimizer = ...\n",
    "\n",
    "# Set the total number of training steps per epoch.\n",
    "total_step = math.ceil(len(data_loader.dataset.caption_lengths) / data_loader.batch_sampler.batch_size)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step2'></a>\n",
    "## Step 2: Train your Model\n",
    "\n",
    "Once you have executed the code cell in **Step 1**, the training procedure below should run without issue.  \n",
    "\n",
    "It is completely fine to leave the code cell below as-is without modifications to train your model.  However, if you would like to modify the code used to train the model below, you must ensure that your changes are easily parsed by your reviewer.  In other words, make sure to provide appropriate comments to describe how your code works!  \n",
    "\n",
    "You may find it useful to load saved weights to resume training.  In that case, note the names of the files containing the encoder and decoder weights that you'd like to load (`encoder_file` and `decoder_file`).  Then you can load the weights by using the lines below:\n",
    "\n",
    "```python\n",
    "# Load pre-trained weights before resuming training.\n",
    "encoder.load_state_dict(torch.load(os.path.join('./models', encoder_file)))\n",
    "decoder.load_state_dict(torch.load(os.path.join('./models', decoder_file)))\n",
    "```\n",
    "\n",
    "While trying out parameters, make sure to take extensive notes and record the settings that you used in your various training runs.  In particular, you don't want to encounter a situation where you've trained a model for several hours but can't remember what settings you used :).\n",
    "\n",
    "### A Note on Tuning Hyperparameters\n",
    "\n",
    "To figure out how well your model is doing, you can look at how the training loss and perplexity evolve during training - and for the purposes of this project, you are encouraged to amend the hyperparameters based on this information.  \n",
    "\n",
    "However, this will not tell you if your model is overfitting to the training data, and, unfortunately, overfitting is a problem that is commonly encountered when training image captioning models.  \n",
    "\n",
    "For this project, you need not worry about overfitting. **This project does not have strict requirements regarding the performance of your model**, and you just need to demonstrate that your model has learned **_something_** when you generate captions on the test data.  For now, we strongly encourage you to train your model for the suggested 3 epochs without worrying about performance; then, you should immediately transition to the next notebook in the sequence (**3_Inference.ipynb**) to see how your model performs on the test data.  If your model needs to be changed, you can come back to this notebook, amend hyperparameters (if necessary), and re-train the model.\n",
    "\n",
    "That said, if you would like to go above and beyond in this project, you can read about some approaches to minimizing overfitting in section 4.3.1 of [this paper](http://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7505636).  In the next (optional) step of this notebook, we provide some guidance for assessing the performance on the validation dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch.utils.data as data\n",
    "import numpy as np\n",
    "import os\n",
    "import requests\n",
    "import time\n",
    "\n",
    "# Open the training log file.\n",
    "f = open(log_file, 'w')\n",
    "\n",
    "old_time = time.time()\n",
    "response = requests.request(\"GET\", \n",
    "                            \"http://metadata.google.internal/computeMetadata/v1/instance/attributes/keep_alive_token\", \n",
    "                            headers={\"Metadata-Flavor\":\"Google\"})\n",
    "\n",
    "for epoch in range(1, num_epochs+1):\n",
    "    \n",
    "    for i_step in range(1, total_step+1):\n",
    "        \n",
    "        if time.time() - old_time > 60:\n",
    "            old_time = time.time()\n",
    "            requests.request(\"POST\", \n",
    "                             \"https://nebula.udacity.com/api/v1/remote/keep-alive\", \n",
    "                             headers={'Authorization': \"STAR \" + response.text})\n",
    "        \n",
    "        # Randomly sample a caption length, and sample indices with that length.\n",
    "        indices = data_loader.dataset.get_train_indices()\n",
    "        # Create and assign a batch sampler to retrieve a batch with the sampled indices.\n",
    "        new_sampler = data.sampler.SubsetRandomSampler(indices=indices)\n",
    "        data_loader.batch_sampler.sampler = new_sampler\n",
    "        \n",
    "        # Obtain the batch.\n",
    "        images, captions = next(iter(data_loader))\n",
    "\n",
    "        # Move batch of images and captions to GPU if CUDA is available.\n",
    "        images = images.to(device)\n",
    "        captions = captions.to(device)\n",
    "        \n",
    "        # Zero the gradients.\n",
    "        decoder.zero_grad()\n",
    "        encoder.zero_grad()\n",
    "        \n",
    "        # Pass the inputs through the CNN-RNN model.\n",
    "        features = encoder(images)\n",
    "        outputs = decoder(features, captions)\n",
    "        \n",
    "        # Calculate the batch loss.\n",
    "        loss = criterion(outputs.view(-1, vocab_size), captions.view(-1))\n",
    "        \n",
    "        # Backward pass.\n",
    "        loss.backward()\n",
    "        \n",
    "        # Update the parameters in the optimizer.\n",
    "        optimizer.step()\n",
    "            \n",
    "        # Get training statistics.\n",
    "        stats = 'Epoch [%d/%d], Step [%d/%d], Loss: %.4f, Perplexity: %5.4f' % (epoch, num_epochs, i_step, total_step, loss.item(), np.exp(loss.item()))\n",
    "        \n",
    "        # Print training statistics (on same line).\n",
    "        print('\\r' + stats, end=\"\")\n",
    "        sys.stdout.flush()\n",
    "        \n",
    "        # Print training statistics to file.\n",
    "        f.write(stats + '\\n')\n",
    "        f.flush()\n",
    "        \n",
    "        # Print training statistics (on different line).\n",
    "        if i_step % print_every == 0:\n",
    "            print('\\r' + stats)\n",
    "            \n",
    "    # Save the weights.\n",
    "    if epoch % save_every == 0:\n",
    "        torch.save(decoder.state_dict(), os.path.join('./models', 'decoder-%d.pkl' % epoch))\n",
    "        torch.save(encoder.state_dict(), os.path.join('./models', 'encoder-%d.pkl' % epoch))\n",
    "\n",
    "# Close the training log file.\n",
    "f.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='step3'></a>\n",
    "## Step 3: (Optional) Validate your Model\n",
    "\n",
    "To assess potential overfitting, one approach is to assess performance on a validation set.  If you decide to do this **optional** task, you are required to first complete all of the steps in the next notebook in the sequence (**3_Inference.ipynb**); as part of that notebook, you will write and test code (specifically, the `sample` method in the `DecoderRNN` class) that uses your RNN decoder to generate captions.  That code will prove incredibly useful here. \n",
    "\n",
    "If you decide to validate your model, please do not edit the data loader in **data_loader.py**.  Instead, create a new file named **data_loader_val.py** containing the code for obtaining the data loader for the validation data.  You can access:\n",
    "- the validation images at filepath `'/opt/cocoapi/images/train2014/'`, and\n",
    "- the validation image caption annotation file at filepath `'/opt/cocoapi/annotations/captions_val2014.json'`.\n",
    "\n",
    "The suggested approach to validating your model involves creating a json file such as [this one](https://github.com/cocodataset/cocoapi/blob/master/results/captions_val2014_fakecap_results.json) containing your model's predicted captions for the validation images.  Then, you can write your own script or use one that you [find online](https://github.com/tylin/coco-caption) to calculate the BLEU score of your model.  You can read more about the BLEU score, along with other evaluation metrics (such as TEOR and Cider) in section 4.1 of [this paper](https://arxiv.org/pdf/1411.4555.pdf).  For more information about how to use the annotation file, check out the [website](http://cocodataset.org/#download) for the COCO dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# (Optional) TODO: Validate your model."
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}