Mod2_Wk3 Programming Assignment.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Programming Assignment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Language model for the Shakespeare dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Instructions\n",
    "\n",
    "In this notebook, you will use the text preprocessing tools and RNN models to build a character-level language model. You will then train your model on the works of Shakespeare, and use the network to generate your own text..\n",
    "\n",
    "Some code cells are provided you in the notebook. You should avoid editing provided code, and make sure to execute the cells in order to avoid unexpected errors. Some cells begin with the line: \n",
    "\n",
    "`#### GRADED CELL ####`\n",
    "\n",
    "Don't move or edit this first line - this is what the automatic grader looks for to recognise graded cells. These cells require you to write your own code to complete them, and are automatically graded when you submit the notebook. Don't edit the function name or signature provided in these cells, otherwise the automatic grader might not function properly. Inside these graded cells, you can use any functions or classes that are imported below, but make sure you don't use any variables that are outside the scope of the function.\n",
    "\n",
    "### How to submit\n",
    "\n",
    "Complete all the tasks you are asked for in the worksheet. When you have finished and are happy with your code, press the **Submit Assignment** button at the top of this notebook.\n",
    "\n",
    "### Let's get started!\n",
    "\n",
    "We'll start running some imports, and loading the dataset. Do not edit the existing imports in the following cell. If you would like to make further Tensorflow imports, you should add them here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### PACKAGE IMPORTS ####\n",
    "\n",
    "# Run this cell first to import all required packages. Do not make any imports elsewhere in the notebook\n",
    "\n",
    "import tensorflow as tf\n",
    "import numpy as np\n",
    "import json\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "\n",
    "# If you would like to make further imports from tensorflow, add them here\n",
    "\n",
    "from tensorflow.keras.preprocessing.text import Tokenizer\n",
    "from tensorflow.keras.preprocessing.sequence import pad_sequences\n",
    "from tensorflow.keras.models import Model, Sequential\n",
    "from tensorflow.keras.layers import Embedding, GRU, Dense"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Shakespeare image](data/shakespeare.png)\n",
    "\n",
    "#### The Shakespeare dataset\n",
    "\n",
    "In this assignment, you will use a subset of the [Shakespeare dataset](http://shakespeare.mit.edu). It consists of a single text file with several excerpts concatenated together. The data is in raw text form, and so far has not yet had any preprocessing. \n",
    "\n",
    "Your goal is to construct an unsupervised character-level sequence model that can generate text according to a distribution learned from the dataset."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Load and inspect the dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the text file into a string\n",
    "\n",
    "with open('data/Shakespeare.txt', 'r', encoding='utf-8') as file:\n",
    "    text = file.read()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a list of chunks of text\n",
    "\n",
    "text_chunks = text.split('.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To give you a feel for what the text looks like, we will print a few chunks from the list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "You say that Edward is your brother's son:\n",
      "So say we too, but not by Edward's wife;\n",
      "For first he was contract to Lady Lucy--\n",
      "Your mother lives a witness to that vow--\n",
      "And afterward by substitute betroth'd\n",
      "To Bona, sister to the King of France\n",
      "\n",
      "\n",
      "GREMIO:\n",
      "You are too blunt: go to it orderly\n",
      "\n",
      "\n",
      "MIRANDA:\n",
      "More to know\n",
      "Did never meddle with my thoughts\n",
      " I have begun,\n",
      "And now I give my sensual race the rein:\n",
      "Fit thy consent to my sharp appetite;\n",
      "Lay by all nicety and prolixious blushes,\n",
      "That banish what they sue for; redeem thy brother\n",
      "By yielding up thy body to my will;\n",
      "Or else he must not only die the death,\n",
      "But thy unkindness shall his death draw out\n",
      "To lingering sufferance\n",
      "\n",
      "\n",
      "JULIET:\n",
      "O, bid me leap, rather than marry Paris,\n",
      "From off the battlements of yonder tower;\n",
      "Or walk in thievish ways; or bid me lurk\n",
      "Where serpents are; chain me with roaring bears;\n",
      "Or shut me nightly in a charnel-house,\n",
      "O'er-cover'd quite with dead men's rattling bones,\n",
      "With reeky shanks and yellow chapless skulls;\n",
      "Or bid me go into a new-made grave\n",
      "And hide me with a dead man in his shroud;\n",
      "Things that, to hear them told, have made me tremble;\n",
      "And I will do it without fear or doubt,\n",
      "To live an unstain'd wife to my sweet love\n"
     ]
    }
   ],
   "source": [
    "# Display some randomly selected text samples\n",
    "\n",
    "num_samples = 5\n",
    "inx = np.random.choice(len(text_chunks), num_samples, replace=False)\n",
    "for chunk in np.array(text_chunks)[inx]:\n",
    "    print(chunk)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create a character-level tokenizer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should now write a function that returns a `Tokenizer` object. The function takes a list of strings as an argument, and should create a `Tokenizer` according to the following specification:\n",
    "\n",
    "* The number of tokens should be unlimited (there should be as many as required by the dataset).\n",
    "* Tokens should be created at the character level (not at the word level, which is the default behaviour).\n",
    "* No characters should be filtered out or ignored.\n",
    "* The original capitalization should be retained (do not convert the text to lower case)\n",
    "\n",
    "The `Tokenizer` should be fit to the `list_of_strings` argument and returned by the function. \n",
    "\n",
    "**Hint:** you may need to refer to the [documentation](https://www.tensorflow.org/api_docs/python/tf/keras/preprocessing/text/Tokenizer) for the `Tokenizer`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### GRADED CELL ####\n",
    "\n",
    "# Complete the following function.\n",
    "# Make sure not to change the function name or arguments.\n",
    "\n",
    "def create_character_tokenizer(list_of_strings):\n",
    "    \"\"\"\n",
    "    This function takes a list of strings as its argument. It should create \n",
    "    and return a Tokenizer according to the above specifications. \n",
    "    \"\"\"\n",
    "    tokeniser = Tokenizer(num_words=None, filters=None, char_level=True, lower=False)\n",
    "    tokeniser.fit_on_texts(list_of_strings)\n",
    "    \n",
    "    return tokeniser\n",
    "    \n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the tokenizer\n",
    "\n",
    "tokenizer = create_character_tokenizer(text_chunks)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Tokenize the text\n",
    "\n",
    "You should now write a function to use the tokenizer to map each string in `text_chunks` to its corresponding encoded sequence. The following function takes a fitted `Tokenizer` object in the first argument (as returned by `create_character_tokenizer`) and a list of strings in the second argument. The function should return a list of lists, where each sublist is a sequence of integer tokens encoding the text sequences according to the mapping stored in the tokenizer.\n",
    "\n",
    "**Hint:** you may need to refer to the [documentation](https://www.tensorflow.org/api_docs/python/tf/keras/preprocessing/text/Tokenizer) for the `Tokenizer`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### GRADED CELL ####\n",
    "\n",
    "# Complete the following function.\n",
    "# Make sure not to change the function name or arguments.\n",
    "\n",
    "def strings_to_sequences(tokenizer, list_of_strings):\n",
    "    \"\"\"\n",
    "    This function takes a tokenizer object and a list of strings as its arguments.\n",
    "    It should use the tokenizer to map the text chunks to sequences of tokens and\n",
    "    then return this list of encoded sequences.\n",
    "    \"\"\"\n",
    "    return tokenizer.texts_to_sequences(list_of_strings)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Encode the text chunks into tokens\n",
    "\n",
    "seq_chunks = strings_to_sequences(tokenizer, text_chunks)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Pad the encoded sequences and store them in a numpy array"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since not all of the text chunks are the same length, you will need to pad them in order to train on batches. You should now complete the following function, which takes the list of lists of tokens, and creates a single numpy array with the token sequences in the rows, according to the following specification:\n",
    "\n",
    "* The longest allowed sequence should be 500 tokens. Any sequence that is longer should be shortened by truncating the beginning of the sequence.\n",
    "* Use zeros for padding the sequences. The zero padding should be placed before the sequences as required.\n",
    "\n",
    "The function should then return the resulting numpy array.\n",
    "\n",
    "**Hint:** you may want to refer to the [documentation](https://www.tensorflow.org/api_docs/python/tf/keras/preprocessing/sequence/pad_sequences) for the `pad_sequences` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### GRADED CELL ####\n",
    "\n",
    "# Complete the following function.\n",
    "# Make sure not to change the function name or arguments.\n",
    "\n",
    "def make_padded_dataset(sequence_chunks):\n",
    "    \"\"\"\n",
    "    This function takes a list of lists of tokenized sequences, and transforms\n",
    "    them into a 2D numpy array, padding the sequences as necessary according to\n",
    "    the above specification. The function should then return the numpy array.\n",
    "    \"\"\"\n",
    "    pad_seq = pad_sequences(sequence_chunks, maxlen=500, padding='pre', truncating='pre', value=0)\n",
    "    return pad_seq\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Pad the token sequence chunks and get the numpy array\n",
    "\n",
    "padded_sequences = make_padded_dataset(seq_chunks)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create model inputs and targets\n",
    "\n",
    "Now you are ready to build your RNN model. The model will receive a sequence of characters and predict the next character in the sequence. At training time, the model can be passed an input sequence, with the target sequence is shifted by one.\n",
    "\n",
    "For example, the expression `To be or not to be` appears in Shakespeare's play 'Hamlet'. Given input `To be or not to b`, the correct prediction is `o be or not to be`. Notice that the prediction is the same length as the input!\n",
    "\n",
    "![sequence_prediction_example](data/rnn_example.png)\n",
    "\n",
    "You should now write the following function to create an input and target array from the current `padded_sequences` array. The function has a single argument that is a 2D numpy array of shape `(num_examples, max_seq_len)`. It should fulfil the following specification:\n",
    "\n",
    "* The function should return an input array and an output array, both of size `(num_examples, max_seq_len - 1)`.\n",
    "* The input array should contain the first `max_seq_len - 1` tokens of each sequence. \n",
    "* The output array should contain the last `max_seq_len - 1` tokens of each sequence. \n",
    "\n",
    "The function should then return the tuple `(input_array, output_array)`. Note that it is possible to complete this function using numpy indexing alone!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### GRADED CELL ####\n",
    "\n",
    "# Complete the following function.\n",
    "# Make sure not to change the function name or arguments.\n",
    "\n",
    "def create_inputs_and_targets(array_of_sequences):\n",
    "    \"\"\"\n",
    "    This function takes a 2D numpy array of token sequences, and returns a tuple of two\n",
    "    elements: the first element is the input array and the second element is the output\n",
    "    array, which are defined according to the above specification.\n",
    "    \"\"\"   \n",
    "    input_seq = array_of_sequences[:, :-1]\n",
    "    output_seq = array_of_sequences[:, 1:]\n",
    "    \n",
    "    return input_seq, output_seq\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the input and output arrays\n",
    "\n",
    "input_seq, target_seq = create_inputs_and_targets(padded_sequences)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Preprocess sequence array for stateful RNN\n",
    "\n",
    "We will build our RNN language model to be stateful, so that the internal state of the RNN will be maintained across batches. For this to be effective, we need to make sure that each element of every batch follows on from the corresponding element of the preceding batch (you may want to look back at the \"Stateful RNNs\" reading notebook earlier in the week).\n",
    "\n",
    "The following code processes the input and output sequence arrays so that they are ready to be split into batches for training a stateful RNN, by re-ordering the sequence examples (the rows) according to a specified batch size. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Fix the batch size for training\n",
    "\n",
    "batch_size = 32"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prepare input and output arrays for training the stateful RNN\n",
    "\n",
    "num_examples = input_seq.shape[0]\n",
    "\n",
    "num_processed_examples = num_examples - (num_examples % batch_size)\n",
    "\n",
    "input_seq = input_seq[:num_processed_examples]\n",
    "target_seq = target_seq[:num_processed_examples]\n",
    "\n",
    "steps = int(num_processed_examples / 32)  # steps per epoch\n",
    "\n",
    "inx = np.empty((0,), dtype=np.int32)\n",
    "for i in range(steps):\n",
    "    inx = np.concatenate((inx, i + np.arange(0, num_processed_examples, steps)))\n",
    "\n",
    "input_seq_stateful = input_seq[inx]\n",
    "target_seq_stateful = target_seq[inx]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Split the data into training and validation sets\n",
    "\n",
    "We will set aside approximately 20% of the data for validation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the training and validation splits\n",
    "\n",
    "num_train_examples = int(batch_size * ((0.8 * num_processed_examples) // batch_size))\n",
    "\n",
    "input_train = input_seq_stateful[:num_train_examples]\n",
    "target_train = target_seq_stateful[:num_train_examples]\n",
    "\n",
    "input_valid = input_seq_stateful[num_train_examples:]\n",
    "target_valid = target_seq_stateful[num_train_examples:]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create training and validation Dataset objects\n",
    "\n",
    "You should now write a function to take the training and validation input and target arrays, and create training and validation `tf.data.Dataset` objects. The function takes an input array and target array in the first two arguments, and the batch size in the third argument. Your function should do the following:\n",
    "\n",
    "* Create a `Dataset` using the `from_tensor_slices` static method, passing in a tuple of the input and output numpy arrays.\n",
    "* Batch the `Dataset` using the `batch_size` argument, setting `drop_remainder` to `True`. \n",
    "\n",
    "The function should then return the `Dataset` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### GRADED CELL ####\n",
    "\n",
    "# Complete the following function.\n",
    "# Make sure not to change the function name or arguments.\n",
    "\n",
    "def make_Dataset(input_array, target_array, batch_size):\n",
    "    \"\"\"\n",
    "    This function takes two 2D numpy arrays in the first two arguments, and an integer\n",
    "    batch_size in the third argument. It should create and return a Dataset object \n",
    "    using the two numpy arrays and batch size according to the above specification.\n",
    "    \"\"\"\n",
    "    dataset = tf.data.Dataset.from_tensor_slices((input_array, target_array)).batch(batch_size, drop_remainder=True)\n",
    "\n",
    "    return dataset\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create the training and validation Datasets\n",
    "\n",
    "train_data = make_Dataset(input_train, target_train, batch_size)\n",
    "valid_data = make_Dataset(input_valid, target_valid, batch_size)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Build the recurrent neural network model"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You are now ready to build your RNN character-level language model. You should write the following function to build the model; the function takes arguments for the batch size and vocabulary size (number of tokens). Using the Sequential API, your function should build your model according to the following specifications:\n",
    "\n",
    "* The first layer should be an Embedding layer with an embedding dimension of 256 and set the vocabulary size to `vocab_size` from the function argument.\n",
    "* The Embedding layer should also mask the zero padding in the input sequences.\n",
    "* The Embedding layer should also set the `batch_input_shape` to `(batch_size, None)` (a fixed batch size is required for stateful RNNs).\n",
    "* The next layer should be a (uni-directional) GRU layer with 1024 units, set to be a stateful RNN layer.\n",
    "* The GRU layer should return the full sequence, instead of just the output state at the final time step.\n",
    "* The final layer should be a Dense layer with `vocab_size` units and no activation function.\n",
    "\n",
    "In total, the network should have 3 layers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### GRADED CELL ####\n",
    "\n",
    "# Complete the following function.\n",
    "# Make sure not to change the function name or arguments.\n",
    "\n",
    "def get_model(vocab_size, batch_size):\n",
    "    \"\"\"\n",
    "    This function takes a vocabulary size and batch size, and builds and returns a \n",
    "    Sequential model according to the above specification.\n",
    "    \"\"\"\n",
    "    model = Sequential([\n",
    "        Embedding(vocab_size, 256, mask_zero=True, batch_input_shape=(batch_size, None)),\n",
    "        GRU(1024, stateful=True, return_sequences=True),\n",
    "        Dense(vocab_size)\n",
    "    ])\n",
    "    return model\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model: \"sequential_1\"\n",
      "_________________________________________________________________\n",
      "Layer (type)                 Output Shape              Param #   \n",
      "=================================================================\n",
      "embedding_1 (Embedding)      (32, None, 256)           16640     \n",
      "_________________________________________________________________\n",
      "gru_1 (GRU)                  (32, None, 1024)          3938304   \n",
      "_________________________________________________________________\n",
      "dense_1 (Dense)              (32, None, 65)            66625     \n",
      "=================================================================\n",
      "Total params: 4,021,569\n",
      "Trainable params: 4,021,569\n",
      "Non-trainable params: 0\n",
      "_________________________________________________________________\n"
     ]
    }
   ],
   "source": [
    "# Build the model and print the model summary\n",
    "\n",
    "model = get_model(len(tokenizer.word_index) + 1, batch_size)\n",
    "model.summary()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Compile and train the model\n",
    "\n",
    "You are now ready to compile and train the model. For this model and dataset, the training time is very long. Therefore for this assignment it is not a requirement to train the model. We have pre-trained a model for you (using the code below) and saved the model weights, which can be loaded to get the model predictions. \n",
    "\n",
    "It is recommended to use accelerator hardware (e.g. using Colab) when training this model. It would also be beneficial to increase the size of the model, e.g. by stacking extra recurrent layers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Choose whether to train a new model or load the pre-trained model\n",
    "\n",
    "skip_training = True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Compile and train the model, or load pre-trained weights\n",
    "\n",
    "if not skip_training:\n",
    "    checkpoint_callback=tf.keras.callbacks.ModelCheckpoint(filepath='./models/ckpt',\n",
    "                                                           save_weights_only=True,\n",
    "                                                           save_best_only=True)\n",
    "    model.compile(optimizer='adam', loss=tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True),\n",
    "                  metrics=['sparse_categorical_accuracy'])\n",
    "    history = model.fit(train_data, epochs=15, validation_data=valid_data, \n",
    "                        validation_steps=50, callbacks=[checkpoint_callback])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save model history as a json file, or load it if using pre-trained weights\n",
    "\n",
    "if not skip_training:\n",
    "    history_dict = dict()\n",
    "    for k, v in history.history.items():\n",
    "        history_dict[k] = [float(val) for val in history.history[k]]\n",
    "    with open('models/history.json', 'w+') as json_file:\n",
    "        json.dump(history_dict, json_file, sort_keys=True, indent=4)\n",
    "else:\n",
    "    with open('models/history.json', 'r') as json_file:\n",
    "        history_dict = json.load(json_file)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Plot the learning curves"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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u4BjlZiY6FJTU4NdhoiINIMFCxZsd851DnYdrYWOkSIiJ4eGHh9bXdhLTU1l/vz5wS5DRESagZltDHYNrYmOkSIiJ4eGHh81jFNERERERKQNUtgTERERERFpgxT2RERERERE2qBWN2dPRERERERanoqKCnJzcykrKwt2KW1GZGQkKSkphIeHH9f2CnsiIiIiInLCcnNziY6OJjU1FTMLdjmtnnOOHTt2kJubS1pa2nHtQ8M4RURERETkhJWVlZGQkKCg10jMjISEhBPqKVXYExERERGRRqGg17hO9PNU2BMRERERkVZvx44dDB8+nOHDh5OUlET37t0PPC4vL2/QPq6//npWr15db5vHH3+c5557rjFKbnKasyciIiIiIq1eQkICixYtAuDee++lY8eO3HnnnYe0cc7hnCMkpPY+r6effvqor3PbbbedeLHNRD17IiLSqNYXlvKPudk454JdihyjT9ZtZ9bSvGCXISLSqNatW0d6ejq33HILI0aMIC8vj5tvvplRo0YxePBgfvGLXxxoe+aZZ7Jo0SIqKyuJjY3lrrvuYtiwYYwZM4Zt27YBcM899/DII48caH/XXXeRmZlJ//79+fTTTwHYs2cPl112GcOGDWPatGmMGjXqQBBtTgp7IiJywjYUlvKn99cy8ZGPOff3H/HLN1ewvrA02GXJMXpqbjYPvlv/8CURkdZoxYoV3HjjjXz55Zd0796dBx54gPnz57N48WJmz57NihUrjthm9+7dnHXWWSxevJgxY8bw1FNP1bpv5xzz5s3jwQcfPBAcH3vsMZKSkli8eDF33XUXX375ZZO+v7poGKeIiByXDYWlzFyax1tL81mZVwzAqF5x/PzCQUxKTyapU2SQK5RjlZEWz39XbWN76X4SO0YEuxwRacXu+89yVmwtbtR9DuoWw88vHHxc2/bp04eMjIwDj1944QX+8Y9/UFlZydatW1mxYgWDBg06ZJuoqCgmTZoEwMiRI5kzZ06t+54yZcqBNjk5OQDMnTuXH/3oRwAMGzaMwYOPr+4TpbAnIiINlr19jxfwluSxwg94I3vF8bMLBjFpSBLJnaKCXKGciIzUeADm5xQxMT05yNWIiDSeDh06HLi/du1aHn30UebNm0dsbCxXX311rZc3aNeu3YH7oaGhVFZW1rrviIiII9q0lKkMCnsiIlKvnO17eKuWgPfT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\n",
      "text/plain": [
       "<Figure size 1080x360 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Run this cell to plot accuracy vs epoch and loss vs epoch\n",
    "\n",
    "plt.figure(figsize=(15,5))\n",
    "plt.subplot(121)\n",
    "plt.plot(history_dict['sparse_categorical_accuracy'])\n",
    "plt.plot(history_dict['val_sparse_categorical_accuracy'])\n",
    "plt.title('Accuracy vs. epochs')\n",
    "plt.ylabel('Accuracy')\n",
    "plt.xlabel('Epoch')\n",
    "plt.xticks(np.arange(len(history_dict['sparse_categorical_accuracy'])))\n",
    "ax = plt.gca()\n",
    "ax.set_xticklabels(1 + np.arange(len(history_dict['sparse_categorical_accuracy'])))\n",
    "plt.legend(['Training', 'Validation'], loc='lower right')\n",
    "\n",
    "plt.subplot(122)\n",
    "plt.plot(history_dict['loss'])\n",
    "plt.plot(history_dict['val_loss'])\n",
    "plt.title('Loss vs. epochs')\n",
    "plt.ylabel('Loss')\n",
    "plt.xlabel('Epoch')\n",
    "plt.xticks(np.arange(len(history_dict['sparse_categorical_accuracy'])))\n",
    "ax = plt.gca()\n",
    "ax.set_xticklabels(1 + np.arange(len(history_dict['sparse_categorical_accuracy'])))\n",
    "plt.legend(['Training', 'Validation'], loc='upper right')\n",
    "plt.show() "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Write a text generation algorithm\n",
    "\n",
    "You can now use the model to generate text! In order to generate a single text sequence, the model needs to be rebuilt with a batch size of 1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<tensorflow.python.training.tracking.util.CheckpointLoadStatus at 0x7fd2806fc780>"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Re-build the model and load the saved weights\n",
    "\n",
    "model = get_model(len(tokenizer.word_index) + 1, batch_size=1)\n",
    "model.load_weights(tf.train.latest_checkpoint('./models/'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An algorithm to generate text is as follows:\n",
    "\n",
    "1. Specify a seed string (e.g. `'ROMEO:'`) to get the network started, and a define number of characters for the model to generate, `num_generation_steps`.\n",
    "2. Tokenize this sentence to obtain a list containing one list of the integer tokens.\n",
    "3. Reset the initial state of the network. \n",
    "4. Convert the token list into a Tensor (or numpy array) and pass it to your model as a batch of size one.\n",
    "5. Get the model prediction (logits) for the last time step and extract the state of the recurrent layer.\n",
    "6. Use the logits to construct a categorical distribution and sample a token from it.\n",
    "7. Repeat the following for `num_generation_steps - 1` steps:\n",
    "\n",
    "    1. Use the saved state of the recurrent layer and the last sampled token to get new logit predictions\n",
    "    2. Use the logits to construct a new categorical distribution and sample a token from it.\n",
    "    3. Save the updated state of the recurrent layer.    \n",
    "\n",
    "8. Take the final list of tokens and convert to text using the Tokenizer.\n",
    "\n",
    "Note that the internal state of the recurrent layer can be accessed using the `states` property. For the GRU layer, it is a list of one variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<tf.Variable 'gru_2/Variable:0' shape=(1, 1024) dtype=float32, numpy=array([[0., 0., 0., ..., 0., 0., 0.]], dtype=float32)>]"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Inspect the model's current recurrent state\n",
    "\n",
    "model.layers[1].states"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will break the algorithm down into two steps. First, you should now complete the following function that takes a sequence of tokens of any length and returns the model's prediction (the logits) for the last time step. The specification is as follows:\n",
    "\n",
    "* The token sequence will be a python list, containing one list of integer tokens, e.g. `[[1, 2, 3, 4]]`\n",
    "* The function should convert the list into a 2D Tensor or numpy array\n",
    "* If the function argument `initial_state` is `None`, then the function should reset the state of the recurrent layer to zeros.\n",
    "* Otherwise, if the function argument `initial_state` is a 2D Tensor or numpy array, assign the value of the internal state of the GRU layer to this argument.\n",
    "* Get the model's prediction (logits) for the last time step only.\n",
    "\n",
    "The function should then return the logits as a 2D numpy array, where the first dimension is equal to 1 (batch size).\n",
    "\n",
    "**Hint:** the internal state of the recurrent can be reset to zeros using the `reset_states` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### GRADED CELL ####\n",
    "\n",
    "# Complete the following function.\n",
    "# Make sure not to change the function name or arguments.\n",
    "\n",
    "def get_logits(model, token_sequence, initial_state=None):\n",
    "    \"\"\"\n",
    "    This function takes a model object, a token sequence and an optional initial\n",
    "    state for the recurrent layer. The function should return the logits prediction\n",
    "    for the final time step as a 2D numpy array.\n",
    "    \"\"\"\n",
    "    if initial_state is None:\n",
    "        model.layers[1].reset_states()  \n",
    "    else:\n",
    "        model.layers[1].reset_states(states=initial_state)\n",
    "        \n",
    "    token_sequence = np.array(token_sequence)\n",
    "    predicted = model.predict(token_sequence)\n",
    "    pred = np.expand_dims(predicted[0,-1,:], 0)\n",
    "    return pred\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[-5.5030842e+00,  2.7852604e+00,  4.1625154e-01,  1.1739857e+00,\n",
       "         2.6079831e+00, -1.6840035e+00, -6.4771647e+00,  1.9564222e+00,\n",
       "         6.8197017e+00,  3.0098407e+00,  1.6945518e+00, -2.0724077e+00,\n",
       "         4.4291401e+00,  5.3356355e-01,  3.7881653e+00,  5.4115481e+00,\n",
       "        -2.2214081e+00,  4.8713516e-03,  3.3308899e+00, -1.4188163e+00,\n",
       "         2.3700118e+00, -1.1000808e+00, -9.2806072e+00, -1.8756826e+00,\n",
       "         2.3442855e+00, -1.1188732e+00, -6.4741540e+00, -9.9722821e-01,\n",
       "        -3.7023365e-01, -2.7786245e+00,  9.2955768e-01, -4.9290538e+00,\n",
       "        -6.7325797e+00, -1.4649526e+00, -9.4752610e-01, -4.7038226e+00,\n",
       "        -4.8711162e+00, -5.0390987e+00, -3.9376287e+00, -2.3612757e+00,\n",
       "        -5.5157099e+00, -6.5754771e+00, -3.9520969e+00, -2.5631268e+00,\n",
       "        -4.7984452e+00, -3.8626778e+00, -2.0918584e+00, -6.4679489e+00,\n",
       "        -1.1409212e+00, -6.1186061e+00, -4.2934284e+00, -4.4882441e+00,\n",
       "        -5.2059445e+00, -7.1577392e+00, -5.4597602e+00, -1.5909446e+00,\n",
       "        -3.8694695e-01, -8.8553768e-01, -6.3541350e+00, -5.3146415e+00,\n",
       "        -2.3401237e+00, -2.6295075e+00, -4.8507013e+00, -4.9036646e+00,\n",
       "        -3.7588274e+00]], dtype=float32)"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Test the get_logits function by passing a dummy token sequence\n",
    "\n",
    "dummy_initial_state = tf.random.normal(model.layers[1].states[0].shape)\n",
    "get_logits(model, [[1, 2, 3, 4]], initial_state=dummy_initial_state)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should now write a function that takes a logits prediction similar to the above, uses it to create a categorical distribution, and samples a token from this distribution. The following function takes a 2D numpy array `logits` as an argument, and should return a single integer prediction that is sampled from the categorical distribution. \n",
    "\n",
    "**Hint:** you might find the `tf.random.categorical` function useful for this; see the documentation [here](https://www.tensorflow.org/api_docs/python/tf/random/categorical)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [],
   "source": [
    "#### GRADED CELL ####\n",
    "\n",
    "# Complete the following function.\n",
    "# Make sure not to change the function name or arguments.\n",
    "\n",
    "def sample_token(logits):\n",
    "    \"\"\"\n",
    "    This function takes a 2D numpy array as an input, and constructs a \n",
    "    categorical distribution using it. It should then sample from this\n",
    "    distribution and return the sample as a single integer.\n",
    "    \"\"\"\n",
    "    return int(tf.random.categorical(logits, 1))\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "18"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Test the sample_token function by passing dummy logits\n",
    "\n",
    "dummy_initial_state = tf.random.normal(model.layers[1].states[0].shape)\n",
    "dummy_logits = get_logits(model, [[1, 2, 3, 4]], initial_state=dummy_initial_state)\n",
    "sample_token(dummy_logits)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "38 25\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "logits_size = dummy_logits.shape[1]\n",
    "dummy_logits = -np.inf*np.ones((1, logits_size))\n",
    "dummy_logits[0, 20] = 0\n",
    "sample_token(dummy_logits)\n",
    "random_inx = np.random.choice(logits_size, 2, replace=False)\n",
    "random_inx1, random_inx2 = random_inx[0], random_inx[1]\n",
    "print(random_inx1, random_inx2)\n",
    "dummy_logits = -np.inf*np.ones((1, logits_size))\n",
    "dummy_logits[0, random_inx1] = 0\n",
    "dummy_logits[0, random_inx2] = 0\n",
    "sampled_token = []\n",
    "for _ in range(100):\n",
    "    sampled_token.append(sample_token(dummy_logits))\n",
    "    \n",
    "l_tokens, l_counts = np.unique(np.array(sampled_token), return_counts=True)\n",
    "len(l_tokens) == 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Generate text from the model\n",
    "\n",
    "You are now ready to generate text from the model!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a seed string and number of generation steps\n",
    "\n",
    "init_string = 'ROMEO:'\n",
    "num_generation_steps = 1000"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ROMEO:\n",
      "She is church,\n",
      "His fearful man that is leans to mo?\n",
      "\n",
      "ANTONIO:\n",
      "O think, that, good be all, goose; but only speak all\n",
      "Vilwingly the crown, and as you, put them,\n",
      "feelding the appeation of the voice, and\n",
      "Jool houses except that when it seems, his eye\n",
      "I'll not better no hate, my followers to\n",
      "that you think your majesty's hands\n",
      "That it is rude particulaus young dates,\n",
      "Watch, my sister! bear this papience\n",
      "That aren affices to at his patience:\n",
      "Let's their counsel doth fish on my leave,\n",
      "In one succise Put out thy stretch-a face,\n",
      "Like to fierce and curses up--O, herely pardon\n",
      "For all thy birds, hither and play--\n",
      "Nurse; and the monstress hours life,\n",
      "And with accheapory; for fravourable pale,\n",
      "Till would have a genslaughter him, and away\n",
      "That his speed-bace can deit my made,\n",
      "Out of any old teirs there in every time,\n",
      "That you sway by me, but begin it on't?\n",
      "\n",
      "BUCKINGHAM:\n",
      "And, in the airy did gentlemen, soldier,\n",
      "And that's tempery in all hainty cause\n",
      "that it been cause, man is this, that daughter shal\n"
     ]
    }
   ],
   "source": [
    "# Use the model to generate a token sequence\n",
    "\n",
    "token_sequence = tokenizer.texts_to_sequences([init_string])\n",
    "initial_state = None\n",
    "input_sequence = token_sequence\n",
    "\n",
    "for _ in range(num_generation_steps):\n",
    "    logits = get_logits(model, input_sequence, initial_state=initial_state)\n",
    "    sampled_token = sample_token(logits)\n",
    "    token_sequence[0].append(sampled_token)\n",
    "    input_sequence = [[sampled_token]]\n",
    "    initial_state = model.layers[1].states[0].numpy()\n",
    "    \n",
    "print(tokenizer.sequences_to_texts(token_sequence)[0][::2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Congratulations for completing this programming assignment! In the next week of the course we will see how to build customised models and layers, and make custom training loops."
   ]
  }
 ],
 "metadata": {
  "coursera": {
   "course_slug": "tensor-flow-2-2",
   "graded_item_id": "4eYSM",
   "launcher_item_id": "HEV6h"
  },
  "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.7.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}