From 7dbf9c6e9ff5eee32a7b05792285ecc0932b1195 Mon Sep 17 00:00:00 2001 From: mhjensen Date: Mon, 5 Oct 2020 22:28:56 +0200 Subject: [PATCH] update week41 --- doc/pub/week41/html/._week41-bs000.html | 187 +- doc/pub/week41/html/._week41-bs001.html | 225 +- doc/pub/week41/html/._week41-bs002.html | 210 +- doc/pub/week41/html/._week41-bs003.html | 273 ++- doc/pub/week41/html/._week41-bs004.html | 230 +- doc/pub/week41/html/._week41-bs005.html | 248 +- doc/pub/week41/html/._week41-bs006.html | 238 +- doc/pub/week41/html/._week41-bs007.html | 211 +- doc/pub/week41/html/._week41-bs008.html | 205 +- doc/pub/week41/html/._week41-bs009.html | 282 ++- doc/pub/week41/html/._week41-bs010.html | 238 +- doc/pub/week41/html/._week41-bs011.html | 239 +- doc/pub/week41/html/._week41-bs012.html | 235 +- doc/pub/week41/html/._week41-bs013.html | 250 ++- doc/pub/week41/html/._week41-bs014.html | 220 +- doc/pub/week41/html/._week41-bs015.html | 385 ++-- doc/pub/week41/html/._week41-bs016.html | 239 +- doc/pub/week41/html/._week41-bs017.html | 245 +- doc/pub/week41/html/._week41-bs018.html | 251 ++- doc/pub/week41/html/._week41-bs019.html | 315 ++- doc/pub/week41/html/._week41-bs020.html | 234 +- doc/pub/week41/html/._week41-bs021.html | 307 ++- doc/pub/week41/html/week41-bs.html | 187 +- doc/pub/week41/html/week41-reveal.html | 2041 ++++++++++++++++- doc/pub/week41/html/week41-solarized.html | 2044 ++++++++++++++++- doc/pub/week41/html/week41.html | 2044 ++++++++++++++++- doc/pub/week41/ipynb/ipynb-week41-src.tar.gz | Bin 87181 -> 87344 bytes doc/pub/week41/ipynb/week41.ipynb | 2122 +++++++++++++++++- doc/src/week41/week41.do.txt | 1668 ++++++++++++++ 29 files changed, 13902 insertions(+), 1671 deletions(-) diff --git a/doc/pub/week41/html/._week41-bs000.html b/doc/pub/week41/html/._week41-bs000.html index 2d605a454..112def37d 100644 --- a/doc/pub/week41/html/._week41-bs000.html +++ b/doc/pub/week41/html/._week41-bs000.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -167,7 +264,7 @@ MathJax.Hub.Config({
    [2] Department of Physics and Astronomy and National Superconducting Cyclotron Laboratory, Michigan State University

    -

    Sep 16, 2020

    +

    Oct 5, 2020


    @@ -191,7 +288,7 @@ MathJax.Hub.Config({

  • 9
  • 10
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs001.html b/doc/pub/week41/html/._week41-bs001.html index ebfb1bdde..14450926f 100644 --- a/doc/pub/week41/html/._week41-bs001.html +++ b/doc/pub/week41/html/._week41-bs001.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,41 +245,15 @@ MathJax.Hub.Config({ -

    Convolutional Neural Networks (recognizing images)

    +

    Plan for week 40

    -

    -Convolutional neural networks (CNNs) were developed during the last -decade of the previous century, with a focus on character recognition -tasks. Nowadays, CNNs are a central element in the spectacular success -of dee learning methods. The success in for example image -classifications have made them a central tool for most machine -learning practitioners. +

    -

    -CNNs are very similar to ordinary Neural Networks. -They are made up of neurons that have learnable weights and -biases. Each neuron receives some inputs, performs a dot product and -optionally follows it with a non-linearity. The whole network still -expresses a single differentiable score function: from the raw image -pixels on one end to class scores at the other. And they still have a -loss function (for example Softmax) on the last (fully-connected) layer -and all the tips/tricks we developed for learning regular Neural -Networks still apply (back propagation, gradient descent etc etc). - -

    -What is the difference? CNN architectures make the explicit assumption that -the inputs are images, which allows us to encode certain properties -into the architecture. These then make the forward function more -efficient to implement and vastly reduce the amount of parameters in -the network. - -

    -Here we provide only a superficial overview, for the more interested, we recommend highly the course -IN5400 – Machine Learning for Image Analysis -and the slides of CS231. - -

    -Another good read is the article here https://arxiv.org/pdf/1603.07285.pdf. +Reading suggestions for both days: Aurelien Geron's chapters 10-11 and Hastie et al chapter 11.

    @@ -201,7 +272,7 @@ Another good read is the article here 10

  • 11
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs002.html b/doc/pub/week41/html/._week41-bs002.html index 9cd64b985..77353ed99 100644 --- a/doc/pub/week41/html/._week41-bs002.html +++ b/doc/pub/week41/html/._week41-bs002.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,30 +245,11 @@ MathJax.Hub.Config({ -

    Regular NNs don’t scale well to full images

    +

    Overview video for week 41

    -As an example, consider -an image of size \( 32\times 32\times 3 \) (32 wide, 32 high, 3 color channels), so a -single fully-connected neuron in a first hidden layer of a regular -Neural Network would have \( 32\times 32\times 3 = 3072 \) weights. This amount still -seems manageable, but clearly this fully-connected structure does not -scale to larger images. For example, an image of more respectable -size, say \( 200\times 200\times 3 \), would lead to neurons that have -\( 200\times 200\times 3 = 120,000 \) weights. - -

    -We could have -several such neurons, and the parameters would add up quickly! Clearly, -this full connectivity is wasteful and the huge number of parameters -would quickly lead to possible overfitting. - -

    -

    -
    -

    Figure 1: A regular 3-layer Neural Network.

    -

    -
    +"Overview Video, from Stochastic Gradient methods to Neural Networks":"https://www.uio.no/studier/emner/matnat/fys/FYS-STK3155/h20\ +/forelesningsvideoer/OverviewWeek41.mp4?vrtx=view-as-webpage"

    @@ -191,7 +269,7 @@ would quickly lead to possible overfitting.

  • 11
  • 12
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs003.html b/doc/pub/week41/html/._week41-bs003.html index c7d1e2c90..2950424d8 100644 --- a/doc/pub/week41/html/._week41-bs003.html +++ b/doc/pub/week41/html/._week41-bs003.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,42 +245,78 @@ MathJax.Hub.Config({ -

    3D volumes of neurons

    +

    Setting up the Back propagation algorithm

    -Convolutional Neural Networks take advantage of the fact that the -input consists of images and they constrain the architecture in a more -sensible way. +The four equations provide us with a way of computing the gradient of the cost function. Let us write this out in the form of an algorithm.

    -In particular, unlike a regular Neural Network, the -layers of a CNN have neurons arranged in 3 dimensions: width, -height, depth. (Note that the word depth here refers to the third -dimension of an activation volume, not to the depth of a full Neural -Network, which can refer to the total number of layers in a network.) +

    +
    +

    +First, we set up the input data \( \hat{x} \) and the activations +\( \hat{z}_1 \) of the input layer and compute the activation function and +the pertinent outputs \( \hat{a}^1 \). +

    +
    +

    -To understand it better, the above example of an image -with an input volume of -activations has dimensions \( 32\times 32\times 3 \) (width, height, -depth respectively). +

    +
    +

    +Secondly, we perform then the feed forward till we reach the output +layer and compute all \( \hat{z}_l \) of the input layer and compute the +activation function and the pertinent outputs \( \hat{a}^l \) for +\( l=2,3,\dots,L \). +

    +
    +

    -The neurons in a layer will -only be connected to a small region of the layer before it, instead of -all of the neurons in a fully-connected manner. Moreover, the final -output layer could for this specific image have dimensions \( 1\times 1 \times 10 \), -because by the -end of the CNN architecture we will reduce the full image into a -single vector of class scores, arranged along the depth -dimension. +

    +
    +

    +Thereafter we compute the ouput error \( \hat{\delta}^L \) by computing all +$$ +\delta_j^L = f'(z_j^L)\frac{\partial {\cal C}}{\partial (a_j^L)}. +$$ +

    +
    +

    -

    -
    -

    Figure 2: A CNN arranges its neurons in three dimensions (width, height, depth), as visualized in one of the layers. Every layer of a CNN transforms the 3D input volume to a 3D output volume of neuron activations. In this example, the red input layer holds the image, so its width and height would be the dimensions of the image, and the depth would be 3 (Red, Green, Blue channels).

    -

    -
    +
    +
    +

    +Then we compute the back propagate error for each \( l=L-1,L-2,\dots,2 \) as +$$ +\delta_j^l = \sum_k \delta_k^{l+1}w_{kj}^{l+1}f'(z_j^l). +$$ +

    +
    + + +

    +

    +
    +

    +Finally, we update the weights and the biases using gradient descent for each \( l=L-1,L-2,\dots,2 \) and update the weights and biases according to the rules +$$ +w_{jk}^l\leftarrow = w_{jk}^l- \eta \delta_j^la_k^{l-1}, +$$ + + +$$ +b_j^l \leftarrow b_j^l-\eta \frac{\partial {\cal C}}{\partial b_j^l}=b_j^l-\eta \delta_j^l, +$$ +

    +
    + + +

    +The parameter \( \eta \) is the learning parameter discussed in connection with the gradient descent methods. +Here it is convenient to use stochastic gradient descent (see the examples below) with mini-batches with an outer loop that steps through multiple epochs of training.

    @@ -204,7 +337,7 @@ dimension.

  • 12
  • 13
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs004.html b/doc/pub/week41/html/._week41-bs004.html index 701a7a0e4..be4e3edca 100644 --- a/doc/pub/week41/html/._week41-bs004.html +++ b/doc/pub/week41/html/._week41-bs004.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,27 +245,42 @@ MathJax.Hub.Config({ -

    Layers used to build CNNs

    +

    Setting up a Multi-layer perceptron model for classification

    -A simple CNN is a sequence of layers, and every layer of a CNN -transforms one volume of activations to another through a -differentiable function. We use three main types of layers to build -CNN architectures: Convolutional Layer, Pooling Layer, and -Fully-Connected Layer (exactly as seen in regular Neural Networks). We -will stack these layers to form a full CNN architecture. +We are now gong to develop an example based on the MNIST data +base. This is a classification problem and we need to use our +cross-entropy function we discussed in connection with logistic +regression. The cross-entropy defines our cost function for the +classificaton problems with neural networks.

    -A simple CNN for image classification could have the architecture: +In binary classification with two classes \( (0, 1) \) we define the +logistic/sigmoid function as the probability that a particular input +is in class \( 0 \) or \( 1 \). This is possible because the logistic +function takes any input from the real numbers and inputs a number +between 0 and 1, and can therefore be interpreted as a probability. It +also has other nice properties, such as a derivative that is simple to +calculate. -

    +

    +For an input \( \boldsymbol{a} \) from the hidden layer, the probability that the input \( \boldsymbol{x} \) +is in class 0 or 1 is just. We let \( \theta \) represent the unknown weights and biases to be adjusted by our equations). The variable \( x \) +represents our activation values \( z \). We have +$$ +P(y = 0 \mid \hat{x}, \hat{\theta}) = \frac{1}{1 + \exp{(- \hat{x}})} , +$$ +and +$$ +P(y = 1 \mid \hat{x}, \hat{\theta}) = 1 - P(y = 0 \mid \hat{x}, \hat{\theta}) , +$$ + +

    +where \( y \in \{0, 1\} \) and \( \hat{\theta} \) represents the weights and biases +of our network. + +

    diff --git a/doc/pub/week41/html/._week41-bs005.html b/doc/pub/week41/html/._week41-bs005.html index 8ee02e01b..07d12bec2 100644 --- a/doc/pub/week41/html/._week41-bs005.html +++ b/doc/pub/week41/html/._week41-bs005.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,21 +245,62 @@ MathJax.Hub.Config({ -

    Transforming images

    +

    Defining the cost function

    -CNNs transform the original image layer by layer from the original -pixel values to the final class scores. +Our cost function is given as (see the Logistic regression lectures) +$$ +\mathcal{C}(\hat{\theta}) = - \ln P(\mathcal{D} \mid \hat{\theta}) = - \sum_{i=1}^n +y_i \ln[P(y_i = 0)] + (1 - y_i) \ln [1 - P(y_i = 0)] = \sum_{i=1}^n \mathcal{L}_i(\hat{\theta}) . +$$

    -Observe that some layers contain -parameters and other don’t. In particular, the CNN layers perform -transformations that are a function of not only the activations in the -input volume, but also of the parameters (the weights and biases of -the neurons). On the other hand, the RELU/POOL layers will implement a -fixed function. The parameters in the CONV/FC layers will be trained -with gradient descent so that the class scores that the CNN computes -are consistent with the labels in the training set for each image. +This last equality means that we can interpret our cost function as a sum over the loss function +for each point in the dataset \( \mathcal{L}_i(\hat{\theta}) \). +The negative sign is just so that we can think about our algorithm as minimizing a positive number, rather +than maximizing a negative number. + +

    +In multiclass classification it is common to treat each integer label as a so called one-hot vector: + +

    +\( y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) , \) and + +

    +\( y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) , \) + +

    +i.e. a binary bit string of length \( C \), where \( C = 10 \) is the number of classes in the MNIST dataset (numbers from \( 0 \) to \( 9 \)).. + +

    +If \( \hat{x}_i \) is the \( i \)-th input (image), \( y_{ic} \) refers to the \( c \)-th component of the \( i \)-th +output vector \( \hat{y}_i \). +The probability of \( \hat{x}_i \) being in class \( c \) will be given by the softmax function: + +$$ +P(y_{ic} = 1 \mid \hat{x}_i, \hat{\theta}) = \frac{\exp{((\hat{a}_i^{hidden})^T \hat{w}_c)}} +{\sum_{c'=0}^{C-1} \exp{((\hat{a}_i^{hidden})^T \hat{w}_{c'})}} , +$$ + +

    +which reduces to the logistic function in the binary case. +The likelihood of this \( C \)-class classifier +is now given as: + +$$ +P(\mathcal{D} \mid \hat{\theta}) = \prod_{i=1}^n \prod_{c=0}^{C-1} [P(y_{ic} = 1)]^{y_{ic}} . +$$ + +Again we take the negative log-likelihood to define our cost function: + +$$ +\mathcal{C}(\hat{\theta}) = - \log{P(\mathcal{D} \mid \hat{\theta})}. +$$ + +See the logistic regression lectures for a full definition of the cost function. + +

    +The back propagation equations need now only a small change, namely the definition of a new cost function. We are thus ready to use the same equations as before!

    @@ -185,7 +323,7 @@ are consistent with the labels in the training set for each image.

  • 14
  • 15
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs006.html b/doc/pub/week41/html/._week41-bs006.html index 041a03b41..ec4443f11 100644 --- a/doc/pub/week41/html/._week41-bs006.html +++ b/doc/pub/week41/html/._week41-bs006.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,23 +245,50 @@ MathJax.Hub.Config({ -

    CNNs in brief

    +

    Example: binary classification problem

    -In summary: +As an example of the above, relevant for project 2 as well, let us consider a binary class. As discussed in our logistic regression lectures, we defined a cost function in terms of the parameters \( \beta \) as +$$ +\mathcal{C}(\hat{\beta}) = - \sum_{i=1}^n \left(y_i\log{p(y_i \vert x_i,\hat{\beta})}+(1-y_i)\log{1-p(y_i \vert x_i,\hat{\beta})}\right), +$$ -

    +where we had defined the logistic (sigmoid) function +$$ +p(y_i =1\vert x_i,\hat{\beta})=\frac{\exp{(\beta_0+\beta_1 x_i)}}{1+\exp{(\beta_0+\beta_1 x_i)}}, +$$ -For more material on convolutional networks, we strongly recommend -the course -IN5400 – Machine Learning for Image Analysis -and the slides of CS231 which is taught at Stanford University (consistently ranked as one of the top computer science programs in the world). Michael Nielsen's book is a must read, in particular chapter 6 which deals with CNNs. +and +$$ +p(y_i =0\vert x_i,\hat{\beta})=1-p(y_i =1\vert x_i,\hat{\beta}). +$$ + +The parameters \( \hat{\beta} \) were defined using a minimization method like gradient descent or Newton-Raphson's method. + +

    +Now we replace \( x_i \) with the activation \( z_i^l \) for a given layer \( l \) and the outputs as \( y_i=a_i^l=f(z_i^l) \), with \( z_i^l \) now being a function of the weights \( w_{ij}^l \) and biases \( b_i^l \). +We have then +$$ +a_i^l = y_i = \frac{\exp{(z_i^l)}}{1+\exp{(z_i^l)}}, +$$ + +with +$$ +z_i^l = \sum_{j}w_{ij}^l a_j^{l-1}+b_i^l, +$$ + +where the superscript \( l-1 \) indicates that these are the outputs from layer \( l-1 \). +Our cost function at the final layer \( l=L \) is now +$$ +\mathcal{C}(\hat{W}) = - \sum_{i=1}^n \left(t_i\log{a_i^L}+(1-t_i)\log{(1-a_i^L)}\right), +$$ + +where we have defined the targets \( t_i \). The derivatives of the cost function with respect to the output \( a_i^L \) are then easily calculated and we get +$$ +\frac{\partial \mathcal{C}(\hat{W})}{\partial a_i^L} = \frac{a_i^L-t_i}{a_i^L(1-a_i^L)}. +$$ + +In case we use another activation function than the logistic one, we need to evaluate other derivatives.

    @@ -188,7 +312,7 @@ and the slides of 15

  • 16
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs007.html b/doc/pub/week41/html/._week41-bs007.html index 528796d71..400b02552 100644 --- a/doc/pub/week41/html/._week41-bs007.html +++ b/doc/pub/week41/html/._week41-bs007.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,18 +245,24 @@ MathJax.Hub.Config({ -

    CNNs in more detail, building convolutional neural networks in Tensorflow and Keras

    +

    The Softmax function

    +In case we employ the more general case given by the Softmax equation, we need to evaluate the derivative of the activation function with respect to the activation \( z_i^l \), that is we need +$$ +\frac{\partial f(z_i^l)}{\partial w_{jk}^l} = +\frac{\partial f(z_i^l)}{\partial z_j^l} \frac{\partial z_j^l}{\partial w_{jk}^l}= \frac{\partial f(z_i^l)}{\partial z_j^l}a_k^{l-1}. +$$ -

    -As discussed above, CNNs are neural networks built from the assumption that the inputs -to the network are 2D images. This is important because the number of features or pixels in images -grows very fast with the image size, and an enormous number of weights and biases are needed in order to build an accurate network. +For the Softmax function we have +$$ +f(z_i^l) = \frac{\exp{(z_i^l)}}{\sum_{m=1}^K\exp{(z_m^l)}}. +$$ -

    -As before, we still have our input, a hidden layer and an output. What's novel about convolutional networks -are the convolutional and pooling layers stacked in pairs between the input and the hidden layer. -In addition, the data is no longer represented as a 2D feature matrix, instead each input is a number of 2D -matrices, typically 1 for each color dimension (Red, Green, Blue). +Its derivative with respect to \( z_j^l \) gives +$$ +\frac{\partial f(z_i^l)}{\partial z_j^l}= f(z_i^l)\left(\delta_{ij}-f(z_j^l)\right), +$$ + +which in case of the simply binary model reduces to having \( i=j \).

    @@ -184,7 +287,7 @@ matrices, typically 1 for each color dimension (Red, Green, Blue).

  • 16
  • 17
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs008.html b/doc/pub/week41/html/._week41-bs008.html index 41a92332c..5bb82204f 100644 --- a/doc/pub/week41/html/._week41-bs008.html +++ b/doc/pub/week41/html/._week41-bs008.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -146,18 +243,22 @@ MathJax.Hub.Config({

     

     

     

    - + -

    Setting it up

    +

    Developing a code for doing neural networks with back propagation

    -It means that to represent the entire -dataset of images, we require a 4D matrix or tensor. This tensor has the dimensions: -$$ -(n_{inputs},\, n_{pixels, width},\, n_{pixels, height},\, depth) . -$$ +One can identify a set of key steps when using neural networks to solve supervised learning problems: + +

      +
    1. Collect and pre-process data
      2. +
    2. Define model and architecture
      3. +
    3. Choose cost function and optimizer
      4. +
    4. Train the model
      5. +
    5. Evaluate model performance on test data
      6. +
    6. Adjust hyperparameters (if necessary, network architecture)
      7. +
    -

    diff --git a/doc/pub/week41/html/._week41-bs009.html b/doc/pub/week41/html/._week41-bs009.html index 79edd608d..f5b1c1062 100644 --- a/doc/pub/week41/html/._week41-bs009.html +++ b/doc/pub/week41/html/._week41-bs009.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,21 +245,98 @@ MathJax.Hub.Config({ -

    The MNIST dataset again

    +

    Collect and pre-process data

    -The MNIST dataset consists of grayscale images with a pixel size of -\( 28\times 28 \), meaning we require \( 28 \times 28 = 724 \) weights to each -neuron in the first hidden layer. +Here we will be using the MNIST dataset, which is readily available through the scikit-learn +package. You may also find it for example here. +The MNIST (Modified National Institute of Standards and Technology) database is a large database +of handwritten digits that is commonly used for training various image processing systems. +The MNIST dataset consists of 70 000 images of size \( 28\times 28 \) pixels, each labeled from 0 to 9. +The scikit-learn dataset we will use consists of a selection of 1797 images of size \( 8\times 8 \) collected and processed from this database.

    -If we were to analyze images of size \( 128\times 128 \) we would require -\( 128 \times 128 = 16384 \) weights to each neuron. Even worse if we were -dealing with color images, as most images are, we have an image matrix -of size \( 128\times 128 \) for each color dimension (Red, Green, Blue), -meaning 3 times the number of weights \( = 49152 \) are required for every -single neuron in the first hidden layer. +To feed data into a feed-forward neural network we need to represent +the inputs as a design/feature matrix \( X = (n_{inputs}, n_{features}) \). Each +row represents an input, in this case a handwritten digit, and +each column represents a feature, in this case a pixel. The +correct answers, also known as labels or targets are +represented as a 1D array of integers +\( Y = (n_{inputs}) = (5, 3, 1, 8,...) \). +

    +As an example, say we want to build a neural network using supervised learning to predict Body-Mass Index (BMI) from +measurements of height (in m) +and weight (in kg). If we have measurements of 5 people the design/feature matrix could be for example: + +$$ X = \begin{bmatrix} +1.85 & 81\\ +1.71 & 65\\ +1.95 & 103\\ +1.55 & 42\\ +1.63 & 56 +\end{bmatrix} ,$$ + +

    +and the targets would be: + +$$ Y = (23.7, 22.2, 27.1, 17.5, 21.1) $$ + +

    +Since each input image is a 2D matrix, we need to flatten the image +(i.e. "unravel" the 2D matrix into a 1D array) to turn the data into a +design/feature matrix. This means we lose all spatial information in the +image, such as locality and translational invariance. More complicated +architectures such as Convolutional Neural Networks can take advantage +of such information, and are most commonly applied when analyzing +images. + +

    + + +

    # import necessary packages
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn import datasets
+
+
+# ensure the same random numbers appear every time
+np.random.seed(0)
+
+# display images in notebook
+%matplotlib inline
+plt.rcParams['figure.figsize'] = (12,12)
+
+
+# download MNIST dataset
+digits = datasets.load_digits()
+
+# define inputs and labels
+inputs = digits.images
+labels = digits.target
+
+print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
+
+
+# flatten the image
+# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64
+n_inputs = len(inputs)
+inputs = inputs.reshape(n_inputs, -1)
+print("X = (n_inputs, n_features) = " + str(inputs.shape))
+
+
+# choose some random images to display
+indices = np.arange(n_inputs)
+random_indices = np.random.choice(indices, size=5)
+
+for i, image in enumerate(digits.images[random_indices]):
+    plt.subplot(1, 5, i+1)
+    plt.axis('off')
+    plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')
+    plt.title("Label: %d" % digits.target[random_indices[i]])
+plt.show()
+

    @@ -188,7 +362,7 @@ single neuron in the first hidden layer.

  • 18
  • 19
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs010.html b/doc/pub/week41/html/._week41-bs010.html index 527c6f64f..a2c31fe99 100644 --- a/doc/pub/week41/html/._week41-bs010.html +++ b/doc/pub/week41/html/._week41-bs010.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -148,19 +245,52 @@ MathJax.Hub.Config({ -

    Strong correlations

    -Images typically have strong local correlations, meaning that a small -part of the image varies little from its neighboring regions. If for -example we have an image of a blue car, we can roughly assume that a -small blue part of the image is surrounded by other blue regions. +

    Train and test datasets

    -Therefore, instead of connecting every single pixel to a neuron in the -first hidden layer, as we have previously done with deep neural -networks, we can instead connect each neuron to a small part of the -image (in all 3 RGB depth dimensions). The size of each small area is -fixed, and known as a receptive. +Performing analysis before partitioning the dataset is a major error, that can lead to incorrect conclusions. +

    +We will reserve \( 80 \% \) of our dataset for training and \( 20 \% \) for testing. + +

    +It is important that the train and test datasets are drawn randomly from our dataset, to ensure +no bias in the sampling. +Say you are taking measurements of weather data to predict the weather in the coming 5 days. +You don't want to train your model on measurements taken from the hours 00.00 to 12.00, and then test it on data +collected from 12.00 to 24.00. + +

    + + +

    from sklearn.model_selection import train_test_split
+
+# one-liner from scikit-learn library
+train_size = 0.8
+test_size = 1 - train_size
+X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,
+                                                    test_size=test_size)
+
+# equivalently in numpy
+def train_test_split_numpy(inputs, labels, train_size, test_size):
+    n_inputs = len(inputs)
+    inputs_shuffled = inputs.copy()
+    labels_shuffled = labels.copy()
+    
+    np.random.shuffle(inputs_shuffled)
+    np.random.shuffle(labels_shuffled)
+    
+    train_end = int(n_inputs*train_size)
+    X_train, X_test = inputs_shuffled[:train_end], inputs_shuffled[train_end:]
+    Y_train, Y_test = labels_shuffled[:train_end], labels_shuffled[train_end:]
+    
+    return X_train, X_test, Y_train, Y_test
+
+#X_train, X_test, Y_train, Y_test = train_test_split_numpy(inputs, labels, train_size, test_size)
+
+print("Number of training images: " + str(len(X_train)))
+print("Number of test images: " + str(len(X_test)))
+

    @@ -187,7 +317,7 @@ fixed, and known as a 19

  • 20
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs011.html b/doc/pub/week41/html/._week41-bs011.html index dad56be77..d26119227 100644 --- a/doc/pub/week41/html/._week41-bs011.html +++ b/doc/pub/week41/html/._week41-bs011.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -146,26 +243,50 @@ MathJax.Hub.Config({

     

     

     

    - + -

    Layers of a CNN

    -The layers of a convolutional neural network arrange neurons in 3D: width, height and depth. -The input image is typically a square matrix of depth 3. +

    Define model and architecture

    -A convolution is performed on the image which outputs -a 3D volume of neurons. The weights to the input are arranged in a number of 2D matrices, known as filters. +Our simple feed-forward neural network will consist of an input layer, a single hidden layer and an output layer. The activation \( y \) of each neuron is a weighted sum of inputs, passed through an activation function. In case of the simple perceptron model we have + +$$ z = \sum_{i=1}^n w_i a_i ,$$ + +$$ y = f(z) ,$$

    -Each filter slides along the input image, taking the dot product -between each small part of the image and the filter, in all depth -dimensions. This is then passed through a non-linear function, -typically the Rectified Linear (ReLu) function, which serves as the -activation of the neurons in the first convolutional layer. This is -further passed through a pooling layer, which reduces the size of the -convolutional layer, e.g. by taking the maximum or average across some -small regions, and this serves as input to the next convolutional -layer. +where \( f \) is the activation function, \( a_i \) represents input from neuron \( i \) in the preceding layer +and \( w_i \) is the weight to input \( i \). +The activation of the neurons in the input layer is just the features (e.g. a pixel value). + +

    +The simplest activation function for a neuron is the Heaviside function: + +$$ f(z) = +\begin{cases} +1, & z > 0\\ +0, & \text{otherwise} +\end{cases} +$$ + +

    +A feed-forward neural network with this activation is known as a perceptron. +For a binary classifier (i.e. two classes, 0 or 1, dog or not-dog) we can also use this in our output layer. +This activation can be generalized to \( k \) classes (using e.g. the one-against-all strategy), +and we call these architectures multiclass perceptrons. + +

    +However, it is now common to use the terms Single Layer Perceptron (SLP) (1 hidden layer) and +Multilayer Perceptron (MLP) (2 or more hidden layers) to refer to feed-forward neural networks with any activation function. + +

    +Typical choices for activation functions include the sigmoid function, hyperbolic tangent, and Rectified Linear Unit (ReLU). +We will be using the sigmoid function \( \sigma(x) \): + +$$ f(x) = \sigma(x) = \frac{1}{1 + e^{-x}} ,$$ + +

    +which is inspired by probability theory (see logistic regression) and was most commonly used until about 2011. See the discussion below concerning other activation functions.

    @@ -193,7 +314,7 @@ layer.

  • 20
  • 21
  • ...
    • -
  • 22
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs012.html b/doc/pub/week41/html/._week41-bs012.html index 1f1d5303c..8c94d2216 100644 --- a/doc/pub/week41/html/._week41-bs012.html +++ b/doc/pub/week41/html/._week41-bs012.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -146,19 +243,49 @@ MathJax.Hub.Config({

     

     

     

    - + -

    Systematic reduction

    +

    Layers

    + + + +Since each input image has 8x8 = 64 pixels or features, we have an input layer of 64 neurons. + + + +We will use 50 neurons in the hidden layer receiving input from the neurons in the input layer. +Since each neuron in the hidden layer is connected to the 64 inputs we have 64x50 = 3200 weights to the hidden layer. + + + +If we were building a binary classifier, it would be sufficient with a single neuron in the output layer, +which could output 0 or 1 according to the Heaviside function. This would be an example of a hard classifier, meaning it outputs the class of the input directly. However, if we are dealing with noisy data it is often beneficial to use a soft classifier, which outputs the probability of being in class 0 or 1.

    -By systematically reducing the size of the input volume, through -convolution and pooling, the network should create representations of -small parts of the input, and then from them assemble representations -of larger areas. The final pooling layer is flattened to serve as -input to a hidden layer, such that each neuron in the final pooling -layer is connected to every single neuron in the hidden layer. This -then serves as input to the output layer, e.g. a softmax output for -classification. +For a soft binary classifier, we could use a single neuron and interpret the output as either being the probability of being in class 0 or the probability of being in class 1. Alternatively we could use 2 neurons, and interpret each neuron as the probability of being in each class. + +

    +Since we are doing multiclass classification, with 10 categories, it is natural to use 10 neurons in the output layer. We number the neurons \( j = 0,1,...,9 \). The activation of each output neuron \( j \) will be according to the softmax function: + +$$ P(\text{class \( j \)} \mid \text{input \( \hat{a} \)}) = \frac{\exp{(\hat{a}^T \hat{w}_j)}} +{\sum_{c=0}^{9} \exp{(\hat{a}^T \hat{w}_c)}} ,$$ + +

    +i.e. each neuron \( j \) outputs the probability of being in class \( j \) given an input from the hidden layer \( \hat{a} \), with \( \hat{w}_j \) the weights of neuron \( j \) to the inputs. +The denominator is a normalization factor to ensure the outputs (probabilities) sum up to 1. +The exponent is just the weighted sum of inputs as before: + +$$ z_j = \sum_{i=1}^n w_ {ij} a_i+b_j.$$ + +

    +Since each neuron in the output layer is connected to the 50 inputs from the hidden layer we have 50x10 = 500 +weights to the output layer.

    @@ -185,6 +312,8 @@ classification.

  • 20
  • 21
  • 22
    • +
  • ...
    • +
  • 61
  • »
    • diff --git a/doc/pub/week41/html/._week41-bs013.html b/doc/pub/week41/html/._week41-bs013.html index 33119da27..0182956eb 100644 --- a/doc/pub/week41/html/._week41-bs013.html +++ b/doc/pub/week41/html/._week41-bs013.html @@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source @@ -112,27 +170,66 @@ MathJax.Hub.Config({
  • Contents
    • @@ -146,52 +243,40 @@ MathJax.Hub.Config({

     

     

     

    - + -

    Prerequisites: Collect and pre-process data

    +

    Weights and biases

    + +

    +Typically weights are initialized with small values distributed around zero, drawn from a uniform +or normal distribution. Setting all weights to zero means all neurons give the same output, making the network useless. + +

    +Adding a bias value to the weighted sum of inputs allows the neural network to represent a greater range +of values. Without it, any input with the value 0 will be mapped to zero (before being passed through the activation). The bias unit has an output of 1, and a weight to each neuron \( j \), \( b_j \): + +$$ z_j = \sum_{i=1}^n w_ {ij} a_i + b_j.$$ + +

    +The bias weights \( \hat{b} \) are often initialized to zero, but a small value like \( 0.01 \) ensures all neurons have some output which can be backpropagated in the first training cycle.

    -

    # import necessary packages
-import numpy as np
-import matplotlib.pyplot as plt
-from sklearn import datasets
+
    # building our neural network
 
+n_inputs, n_features = X_train.shape
+n_hidden_neurons = 50
+n_categories = 10
 
-# ensure the same random numbers appear every time
-np.random.seed(0)
+# we make the weights normally distributed using numpy.random.randn
 
-# display images in notebook
-%matplotlib inline
-plt.rcParams['figure.figsize'] = (12,12)
+# weights and bias in the hidden layer
+hidden_weights = np.random.randn(n_features, n_hidden_neurons)
+hidden_bias = np.zeros(n_hidden_neurons) + 0.01
 
-
-# download MNIST dataset
-digits = datasets.load_digits()
-
-# define inputs and labels
-inputs = digits.images
-labels = digits.target
-
-# RGB images have a depth of 3
-# our images are grayscale so they should have a depth of 1
-inputs = inputs[:,:,:,np.newaxis]
-
-print("inputs = (n_inputs, pixel_width, pixel_height, depth) = " + str(inputs.shape))
-print("labels = (n_inputs) = " + str(labels.shape))
-
-
-# choose some random images to display
-n_inputs = len(inputs)
-indices = np.arange(n_inputs)
-random_indices = np.random.choice(indices, size=5)
-
-for i, image in enumerate(digits.images[random_indices]):
-    plt.subplot(1, 5, i+1)
-    plt.axis('off')
-    plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')
-    plt.title("Label: %d" % digits.target[random_indices[i]])
-plt.show()
+# weights and bias in the output layer
+output_weights = np.random.randn(n_hidden_neurons, n_categories)
+output_bias = np.zeros(n_categories) + 0.01
 
    
 
    
 
    
@@ -217,6 +302,9 @@ plt.show()
   
  • 20
    • 
   
  • 21
    • 
   
  • 22
    • 
+  
  • 23
    • 
+  
  • ...
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/._week41-bs014.html b/doc/pub/week41/html/._week41-bs014.html
index 6968789cc..a53280081 100644
--- a/doc/pub/week41/html/._week41-bs014.html
+++ b/doc/pub/week41/html/._week41-bs014.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -148,23 +245,30 @@ MathJax.Hub.Config({
 
 
 
-
    Importing Keras and Tensorflow 
    
+
    Feed-forward pass 
    
+
 
    
+Denote \( F \) the number of features, \( H \) the number of hidden neurons and \( C \) the number of categories.  
+For each input image we calculate a weighted sum of input features (pixel values) to each neuron \( j \) in the hidden layer \( l \):  
 
-
-
    from keras.utils import to_categorical
-from sklearn.model_selection import train_test_split
+$$ z_{j}^{l} = \sum_{i=1}^{F} w_{ij}^{l} x_i + b_{j}^{l},$$
 
-# representation of labels
-labels = to_categorical(labels)
+
    
+this is then passed through our activation function  
+
+$$ a_{j}^{l} = f(z_{j}^{l}) .$$
+
+
    
+We calculate a weighted sum of inputs (activations in the hidden layer) to each neuron \( j \) in the output layer:  
+
+$$ z_{j}^{L} = \sum_{i=1}^{H} w_{ij}^{L} a_{i}^{l} + b_{j}^{L}.$$
+
+
    
+Finally we calculate the output of neuron \( j \) in the output layer using the softmax function:  
+
+$$ a_{j}^{L} = \frac{\exp{(z_j^{L})}}
+{\sum_{c=0}^{C-1} \exp{(z_c^{L})}} .$$
 
-# split into train and test data
-# one-liner from scikit-learn library
-train_size = 0.8
-test_size = 1 - train_size
-X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,
-                                                    test_size=test_size)
-
    
 
    
 
    
 
@@ -188,6 +292,10 @@ X_train, X_test, Y_train, Y_test = train_tes
   
  • 20
    • 
   
  • 21
    • 
   
  • 22
    • 
+  
  • 23
    • 
+  
  • 24
    • 
+  
  • ...
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/._week41-bs015.html b/doc/pub/week41/html/._week41-bs015.html
index e27b7bcf0..c4be49193 100644
--- a/doc/pub/week41/html/._week41-bs015.html
+++ b/doc/pub/week41/html/._week41-bs015.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -146,152 +243,79 @@ MathJax.Hub.Config({
 
     
     
     
     
 
 
-
+
 
-
    Using TensorFlow backend 
    
+
    Matrix multiplications 
    
 
 
    
-We need to define model and architecture and choose cost function and optmizer.
+Since our data has the dimensions \( X = (n_{inputs}, n_{features}) \) and our weights to the hidden
+layer have the dimensions  
+\( W_{hidden} = (n_{features}, n_{hidden}) \),
+we can easily feed the network all our training data in one go by taking the matrix product  
+
+$$ X W^{h} = (n_{inputs}, n_{hidden}),$$
+
+
    
+and obtain a matrix that holds the weighted sum of inputs to the hidden layer
+for each input image and each hidden neuron.    
+We also add the bias to obtain a matrix of weighted sums to the hidden layer \( Z^{h} \):  
+
+$$ \hat{z}^{l} = \hat{X} \hat{W}^{l} + \hat{b}^{l} ,$$
+
+
    
+meaning the same bias (1D array with size equal number of hidden neurons) is added to each input image.  
+This is then passed through the activation:  
+
+$$ \hat{a}^{l} = f(\hat{z}^l) .$$
+
+
    
+This is fed to the output layer:  
+
+$$ \hat{z}^{L} = \hat{a}^{L} \hat{W}^{L} + \hat{b}^{L} .$$
+
+
    
+Finally we receive our output values for each image and each category by passing it through the softmax function:  
+
+$$ output = softmax (\hat{z}^{L}) = (n_{inputs}, n_{categories}) .$$
+
 
    
 
-
-
    import tensorflow as tf
+
+
    # setup the feed-forward pass, subscript h = hidden layer
 
-class ConvolutionalNeuralNetworkTensorflow:
-    def __init__(
-            self,
-            X_train,
-            Y_train,
-            X_test,
-            Y_test,
-            n_filters=10,
-            n_neurons_connected=50,
-            n_categories=10,
-            receptive_field=3,
-            stride=1,
-            padding=1,
-            epochs=10,
-            batch_size=100,
-            eta=0.1,
-            lmbd=0.0):
-        
-        self.global_step = tf.Variable(0, dtype=tf.int32, trainable=False, name='global_step')
-        
-        self.X_train = X_train
-        self.Y_train = Y_train
-        self.X_test = X_test
-        self.Y_test = Y_test
-        
-        self.n_inputs, self.input_width, self.input_height, self.depth = X_train.shape
-        
-        self.n_filters = n_filters
-        self.n_downsampled = int(self.input_width*self.input_height*n_filters / 4)
-        self.n_neurons_connected = n_neurons_connected
-        self.n_categories = n_categories
-        
-        self.receptive_field = receptive_field
-        self.stride = stride
-        self.strides = [stride, stride, stride, stride]
-        self.padding = padding
-        
-        self.epochs = epochs
-        self.batch_size = batch_size
-        self.iterations = self.n_inputs // self.batch_size
-        self.eta = eta
-        self.lmbd = lmbd
-        
-        self.create_placeholders()
-        self.create_CNN()
-        self.create_loss()
-        self.create_optimiser()
-        self.create_accuracy()
-    
-    def create_placeholders(self):
-        with tf.name_scope('data'):
-            self.X = tf.placeholder(tf.float32, shape=(None, self.input_width, self.input_height, self.depth), name='X_data')
-            self.Y = tf.placeholder(tf.float32, shape=(None, self.n_categories), name='Y_data')
-    
-    def create_CNN(self):
-        with tf.name_scope('CNN'):
-            
-            # Convolutional layer
-            self.W_conv = self.weight_variable([self.receptive_field, self.receptive_field, self.depth, self.n_filters], name='conv', dtype=tf.float32)
-            b_conv = self.weight_variable([self.n_filters], name='conv', dtype=tf.float32)
-            z_conv = tf.nn.conv2d(self.X, self.W_conv, self.strides, padding='SAME', name='conv') + b_conv
-            a_conv = tf.nn.relu(z_conv)
-            
-            # 2x2 max pooling
-            a_pool = tf.nn.max_pool(a_conv, [1, 2, 2, 1], [1, 2, 2, 1], padding='SAME', name='pool')
-            
-            # Fully connected layer
-            a_pool_flat = tf.reshape(a_pool, [-1, self.n_downsampled])
-            self.W_fc = self.weight_variable([self.n_downsampled, self.n_neurons_connected], name='fc', dtype=tf.float32)
-            b_fc = self.bias_variable([self.n_neurons_connected], name='fc', dtype=tf.float32)
-            a_fc = tf.nn.relu(tf.matmul(a_pool_flat, self.W_fc) + b_fc)
-            
-            # Output layer
-            self.W_out = self.weight_variable([self.n_neurons_connected, self.n_categories], name='out', dtype=tf.float32)
-            b_out = self.bias_variable([self.n_categories], name='out', dtype=tf.float32)
-            self.z_out = tf.matmul(a_fc, self.W_out) + b_out
-    
-    def create_loss(self):
-        with tf.name_scope('loss'):
-            softmax_loss = tf.reduce_mean(tf.nn.softmax_cross_entropy_with_logits_v2(labels=self.Y, logits=self.z_out))
-            
-            regularizer_loss_conv = tf.nn.l2_loss(self.W_conv)
-            regularizer_loss_fc = tf.nn.l2_loss(self.W_fc)
-            regularizer_loss_out = tf.nn.l2_loss(self.W_out)
-            regularizer_loss = self.lmbd*(regularizer_loss_conv + regularizer_loss_fc + regularizer_loss_out)
-            
-            self.loss = softmax_loss + regularizer_loss
+def sigmoid(x):
+    return 1/(1 + np.exp(-x))
 
-    def create_accuracy(self):
-        with tf.name_scope('accuracy'):
-            probabilities = tf.nn.softmax(self.z_out)
-            predictions = tf.argmax(probabilities, 1)
-            labels = tf.argmax(self.Y, 1)
-            
-            correct_predictions = tf.equal(predictions, labels)
-            correct_predictions = tf.cast(correct_predictions, tf.float32)
-            self.accuracy = tf.reduce_mean(correct_predictions)
+def feed_forward(X):
+    # weighted sum of inputs to the hidden layer
+    z_h = np.matmul(X, hidden_weights) + hidden_bias
+    # activation in the hidden layer
+    a_h = sigmoid(z_h)
     
-    def create_optimiser(self):
-        with tf.name_scope('optimizer'):
-            self.optimizer = tf.train.GradientDescentOptimizer(learning_rate=self.eta).minimize(self.loss, global_step=self.global_step)
-            
-    def weight_variable(self, shape, name='', dtype=tf.float32):
-        initial = tf.truncated_normal(shape, stddev=0.1)
-        return tf.Variable(initial, name=name, dtype=dtype)
+    # weighted sum of inputs to the output layer
+    z_o = np.matmul(a_h, output_weights) + output_bias
+    # softmax output
+    # axis 0 holds each input and axis 1 the probabilities of each category
+    exp_term = np.exp(z_o)
+    probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
     
-    def bias_variable(self, shape, name='', dtype=tf.float32):
-        initial = tf.constant(0.1, shape=shape)
-        return tf.Variable(initial, name=name, dtype=dtype)
+    return probabilities
 
-    def fit(self):
-        data_indices = np.arange(self.n_inputs)
+probabilities = feed_forward(X_train)
+print("probabilities = (n_inputs, n_categories) = " + str(probabilities.shape))
+print("probability that image 0 is in category 0,1,2,...,9 = \n" + str(probabilities[0]))
+print("probabilities sum up to: " + str(probabilities[0].sum()))
+print()
 
-        with tf.Session() as sess:
-            sess.run(tf.global_variables_initializer())
-            for i in range(self.epochs):
-                for j in range(self.iterations):
-                    chosen_datapoints = np.random.choice(data_indices, size=self.batch_size, replace=False)
-                    batch_X, batch_Y = self.X_train[chosen_datapoints], self.Y_train[chosen_datapoints]
-            
-                    sess.run([CNN.loss, CNN.optimizer],
-                        feed_dict={CNN.X: batch_X,
-                                   CNN.Y: batch_Y})
-                    accuracy = sess.run(CNN.accuracy,
-                        feed_dict={CNN.X: batch_X,
-                                   CNN.Y: batch_Y})
-                    step = sess.run(CNN.global_step)
-    
-            self.train_loss, self.train_accuracy = sess.run([CNN.loss, CNN.accuracy],
-                feed_dict={CNN.X: self.X_train,
-                           CNN.Y: self.Y_train})
-        
-            self.test_loss, self.test_accuracy = sess.run([CNN.loss, CNN.accuracy],
-                feed_dict={CNN.X: self.X_test,
-                           CNN.Y: self.Y_test})
+# we obtain a prediction by taking the class with the highest likelihood
+def predict(X):
+    probabilities = feed_forward(X)
+    return np.argmax(probabilities, axis=1)
+
+predictions = predict(X_train)
+print("predictions = (n_inputs) = " + str(predictions.shape))
+print("prediction for image 0: " + str(predictions[0]))
+print("correct label for image 0: " + str(Y_train[0]))
 
    
 
    
 
    
@@ -315,6 +339,11 @@ class ConvolutionalNeuralNetworkTensorflow:
   
  • 20
    • 
   
  • 21
    • 
   
  • 22
    • 
+  
  • 23
    • 
+  
  • 24
    • 
+  
  • 25
    • 
+  
  • ...
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/._week41-bs016.html b/doc/pub/week41/html/._week41-bs016.html
index c6486199d..9914319d8 100644
--- a/doc/pub/week41/html/._week41-bs016.html
+++ b/doc/pub/week41/html/._week41-bs016.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -148,38 +245,34 @@ MathJax.Hub.Config({
 
 
 
-
    Train the model 
    
+
    Choose cost function and optimizer 
    
 
 
    
-We need now to train the model, evaluate it and test its performance on test data, and eventually include hyperparameters.
+To measure how well our neural network is doing we need to introduce a cost function.  
+We will call the function that gives the error of a single sample output the loss function, and the function
+that gives the total error of our network across all samples the cost function.
+A typical choice for multiclass classification is the cross-entropy loss, also known as the negative log likelihood.
+
 
    
+In multiclass classification it is common to treat each integer label as a so called one-hot vector:  
 
-
-
    epochs = 100
-batch_size = 100
-n_filters = 10
-n_neurons_connected = 50
-n_categories = 10
+$$ y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) ,$$  
+
+$$ y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) ,$$
+
+
    
+i.e. a binary bit string of length \( C \), where \( C = 10 \) is the number of classes in the MNIST dataset.
+
+
    
+Let \( y_{ic} \) denote the \( c \)-th component of the \( i \)-th one-hot vector.  
+We define the cost function \( \mathcal{C} \) as a sum over the cross-entropy loss for each point \( \hat{x}_i \) in the dataset.
+
+
    
+In the one-hot representation only one of the terms in the loss function is non-zero, namely the
+probability of the correct category \( c' \)  
+(i.e. the category \( c' \) such that \( y_{ic'} = 1 \)). This means that the cross entropy loss only punishes you for how wrong
+you got the correct label. The probability of category \( c \) is given by the softmax function. The vector \( \hat{\theta} \) represents the parameters of our network, i.e. all the weights and biases.
 
-eta_vals = np.logspace(-5, 1, 7)
-lmbd_vals = np.logspace(-5, 1, 7)
-CNN_tf = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
-        
-for i, eta in enumerate(eta_vals):
-    for j, lmbd in enumerate(lmbd_vals):
-        CNN = ConvolutionalNeuralNetworkTensorflow(X_train, Y_train, X_test, Y_test,
-                                      n_filters=n_filters, n_neurons_connected=n_neurons_connected,
-                                      n_categories=n_categories, epochs=epochs, batch_size=batch_size,
-                                      eta=eta, lmbd=lmbd)
-        CNN.fit()
-        
-        print("Learning rate = ", eta)
-        print("Lambda = ", lmbd)
-        print("Test accuracy: %.3f" % CNN.test_accuracy)
-        print()
-            
-        CNN_tf[i][j] = CNN
-
    
 
    
 
    
 
@@ -201,6 +294,12 @@ CNN_tf = np.20
   
  • 21
    • 
   
  • 22
    • 
+  
  • 23
    • 
+  
  • 24
    • 
+  
  • 25
    • 
+  
  • 26
    • 
+  
  • ...
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/._week41-bs017.html b/doc/pub/week41/html/._week41-bs017.html
index 2667dae4b..44acb9c33 100644
--- a/doc/pub/week41/html/._week41-bs017.html
+++ b/doc/pub/week41/html/._week41-bs017.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -148,42 +245,43 @@ MathJax.Hub.Config({
 
 
 
-
    Visualizing the results 
    
+
    Optimizing the cost function 
    
 
 
    
+The network is trained by finding the weights and biases that minimize the cost function. One of the most widely used classes of methods is gradient descent and its generalizations. The idea behind gradient descent
+is simply to adjust the weights in the direction where the gradient of the cost function is large and negative. This ensures we flow toward a local minimum of the cost function.  
+Each parameter \( \theta \) is iteratively adjusted according to the rule  
 
-
-
    # visual representation of grid search
-# uses seaborn heatmap, could probably do this in matplotlib
-import seaborn as sns
+$$ \theta_{i+1} = \theta_i - \eta \nabla \mathcal{C}(\theta_i) ,$$
 
-sns.set()
+
    
+where \( \eta \) is known as the learning rate, which controls how big a step we take towards the minimum.  
+This update can be repeated for any number of iterations, or until we are satisfied with the result.
 
-train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
-test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
    
+A simple and effective improvement is a variant called Batch Gradient Descent.  
+Instead of calculating the gradient on the whole dataset, we calculate an approximation of the gradient
+on a subset of the data called a minibatch.  
+If there are \( N \) data points and we have a minibatch size of \( M \), the total number of batches
+is \( N/M \).  
+We denote each minibatch \( B_k \), with \( k = 1, 2,...,N/M \). The gradient then becomes:  
 
-for i in range(len(eta_vals)):
-    for j in range(len(lmbd_vals)):
-        CNN = CNN_tf[i][j]
+$$ \nabla \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \nabla \mathcal{L}_i(\theta) \quad \rightarrow \quad
+\frac{1}{M} \sum_{i \in B_k} \nabla \mathcal{L}_i(\theta) ,$$
 
-        train_accuracy[i][j] = CNN.train_accuracy
-        test_accuracy[i][j] = CNN.test_accuracy
+
    
+i.e. instead of averaging the loss over the entire dataset, we average over a minibatch.
 
-        
-fig, ax = plt.subplots(figsize = (10, 10))
-sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
-ax.set_title("Training Accuracy")
-ax.set_ylabel("$\eta$")
-ax.set_xlabel("$\lambda$")
-plt.show()
+
    
+This has two important benefits:  
+
+
      
+
    1.  Introducing stochasticity decreases the chance that the algorithm becomes stuck in a local minima.
      2.   
+
    2.  It significantly speeds up the calculation, since we do not have to use the entire dataset to calculate the gradient.
      3.   
+
    
+
+The various optmization  methods, with codes and algorithms,  are discussed in our lectures on Gradient descent approaches.
 
-fig, ax = plt.subplots(figsize = (10, 10))
-sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
-ax.set_title("Test Accuracy")
-ax.set_ylabel("$\eta$")
-ax.set_xlabel("$\lambda$")
-plt.show()
-
    
 
    
 
    
 
@@ -204,6 +302,13 @@ plt.show()
   
  • 20
    • 
   
  • 21
    • 
   
  • 22
    • 
+  
  • 23
    • 
+  
  • 24
    • 
+  
  • 25
    • 
+  
  • 26
    • 
+  
  • 27
    • 
+  
  • ...
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/._week41-bs018.html b/doc/pub/week41/html/._week41-bs018.html
index cc2172079..5dd5012fe 100644
--- a/doc/pub/week41/html/._week41-bs018.html
+++ b/doc/pub/week41/html/._week41-bs018.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -146,48 +243,38 @@ MathJax.Hub.Config({
 
     
     
     
     
 
 
-
+
 
-
    Running with Keras 
    
+
    Regularization 
    
 
 
    
+It is common to add an extra term to the cost function, proportional
+to the size of the weights.  This is equivalent to constraining the
+size of the weights, so that they do not grow out of control.
+Constraining the size of the weights means that the weights cannot
+grow arbitrarily large to fit the training data, and in this way
+reduces overfitting.
 
-
-
    from keras.models import Sequential
-from keras.layers.convolutional import Conv2D
-from keras.layers.convolutional import MaxPooling2D
-from keras.layers import Flatten
-from keras.layers import Dense
-from keras.regularizers import l2
-from keras.optimizers import SGD
+
    
+We will measure the size of the weights using the so called L2-norm, meaning our cost function becomes:  
 
-def create_convolutional_neural_network_keras(input_shape, receptive_field,
-                                              n_filters, n_neurons_connected, n_categories,
-                                              eta, lmbd):
-    model = Sequential()
-    model.add(Conv2D(n_filters, (receptive_field, receptive_field), input_shape=input_shape, padding='same',
-              activation='relu', kernel_regularizer=l2(lmbd)))
-    model.add(MaxPooling2D(pool_size=(2, 2)))
-    model.add(Flatten())
-    model.add(Dense(n_neurons_connected, activation='relu', kernel_regularizer=l2(lmbd)))
-    model.add(Dense(n_categories, activation='softmax', kernel_regularizer=l2(lmbd)))
-    
-    sgd = SGD(lr=eta)
-    model.compile(loss='categorical_crossentropy', optimizer=sgd, metrics=['accuracy'])
-    
-    return model
+$$  \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \mathcal{L}_i(\theta) \quad \rightarrow \quad
+\frac{1}{N} \sum_{i=1}^N  \mathcal{L}_i(\theta) + \lambda \lvert \lvert \hat{w} \rvert \rvert_2^2 
+= \frac{1}{N} \sum_{i=1}^N  \mathcal{L}(\theta) + \lambda \sum_{ij} w_{ij}^2,$$
 
-epochs = 100
-batch_size = 100
-input_shape = X_train.shape[1:4]
-receptive_field = 3
-n_filters = 10
-n_neurons_connected = 50
-n_categories = 10
+
    
+i.e. we sum up all the weights squared. The factor \( \lambda \) is known as a regularization parameter.
+
+
    
+In order to train the model, we need to calculate the derivative of
+the cost function with respect to every bias and weight in the
+network.  In total our network has \( (64 + 1)\times 50=3250 \) weights in
+the hidden layer and \( (50 + 1)\times 10=510 \) weights to the output
+layer (\( +1 \) for the bias), and the gradient must be calculated for
+every parameter.  We use the backpropagation algorithm discussed
+above. This is a clever use of the chain rule that allows us to
+calculate the gradient efficently.
 
-eta_vals = np.logspace(-5, 1, 7)
-lmbd_vals = np.logspace(-5, 1, 7)
-
    
 
    
 
    
 
@@ -207,6 +294,14 @@ lmbd_vals = np.
   
  • 20
    • 
   
  • 21
    • 
   
  • 22
    • 
+  
  • 23
    • 
+  
  • 24
    • 
+  
  • 25
    • 
+  
  • 26
    • 
+  
  • 27
    • 
+  
  • 28
    • 
+  
  • ...
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/._week41-bs019.html b/doc/pub/week41/html/._week41-bs019.html
index f78036ff1..b900c854b 100644
--- a/doc/pub/week41/html/._week41-bs019.html
+++ b/doc/pub/week41/html/._week41-bs019.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -148,27 +245,116 @@ MathJax.Hub.Config({
 
 
 
-
    Final part 
    
+
    Matrix  multiplication 
    
+
+
    
+To more efficently train our network these equations are implemented using matrix operations.  
+The error in the output layer is calculated simply as, with \( \hat{t} \) being our targets,  
+
+$$ \delta_L = \hat{t} - \hat{y} = (n_{inputs}, n_{categories}) .$$
+
+
    
+The gradient for the output weights is calculated as  
+
+$$ \nabla W_{L} = \hat{a}^T \delta_L   = (n_{hidden}, n_{categories}) ,$$
+
+
    
+where \( \hat{a} = (n_{inputs}, n_{hidden}) \). This simply means that we are summing up the gradients for each input.  
+Since we are going backwards we have to transpose the activation matrix.
+
+
    
+The gradient with respect to the output bias is then  
+
+$$ \nabla \hat{b}_{L} = \sum_{i=1}^{n_{inputs}} \delta_L = (n_{categories}) .$$
+
+
    
+The error in the hidden layer is  
+
+$$ \Delta_h = \delta_L W_{L}^T \circ f'(z_{h}) = \delta_L W_{L}^T \circ a_{h} \circ (1 - a_{h}) = (n_{inputs}, n_{hidden}) ,$$
+
+
    
+where \( f'(a_{h}) \) is the derivative of the activation in the hidden layer. The matrix products mean
+that we are summing up the products for each neuron in the output layer. The symbol \( \circ \) denotes
+the Hadamard product, meaning element-wise multiplication.
+
+
    
+This again gives us the gradients in the hidden layer:  
+
+$$ \nabla W_{h} = X^T \delta_h = (n_{features}, n_{hidden}) ,$$  
+
+$$ \nabla b_{h} = \sum_{i=1}^{n_{inputs}} \delta_h = (n_{hidden}) .$$
 
 
    
 
 
-
    CNN_keras = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
-        
-for i, eta in enumerate(eta_vals):
-    for j, lmbd in enumerate(lmbd_vals):
-        CNN = create_convolutional_neural_network_keras(input_shape, receptive_field,
-                                              n_filters, n_neurons_connected, n_categories,
-                                              eta, lmbd)
-        CNN.fit(X_train, Y_train, epochs=epochs, batch_size=batch_size, verbose=0)
-        scores = CNN.evaluate(X_test, Y_test)
-        
-        CNN_keras[i][j] = CNN
-        
-        print("Learning rate = ", eta)
-        print("Lambda = ", lmbd)
-        print("Test accuracy: %.3f" % scores[1])
-        print()
+
    # to categorical turns our integer vector into a onehot representation
+from sklearn.metrics import accuracy_score
+
+# one-hot in numpy
+def to_categorical_numpy(integer_vector):
+    n_inputs = len(integer_vector)
+    n_categories = np.max(integer_vector) + 1
+    onehot_vector = np.zeros((n_inputs, n_categories))
+    onehot_vector[range(n_inputs), integer_vector] = 1
+    
+    return onehot_vector
+
+#Y_train_onehot, Y_test_onehot = to_categorical(Y_train), to_categorical(Y_test)
+Y_train_onehot, Y_test_onehot = to_categorical_numpy(Y_train), to_categorical_numpy(Y_test)
+
+def feed_forward_train(X):
+    # weighted sum of inputs to the hidden layer
+    z_h = np.matmul(X, hidden_weights) + hidden_bias
+    # activation in the hidden layer
+    a_h = sigmoid(z_h)
+    
+    # weighted sum of inputs to the output layer
+    z_o = np.matmul(a_h, output_weights) + output_bias
+    # softmax output
+    # axis 0 holds each input and axis 1 the probabilities of each category
+    exp_term = np.exp(z_o)
+    probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+    
+    # for backpropagation need activations in hidden and output layers
+    return a_h, probabilities
+
+def backpropagation(X, Y):
+    a_h, probabilities = feed_forward_train(X)
+    
+    # error in the output layer
+    error_output = probabilities - Y
+    # error in the hidden layer
+    error_hidden = np.matmul(error_output, output_weights.T) * a_h * (1 - a_h)
+    
+    # gradients for the output layer
+    output_weights_gradient = np.matmul(a_h.T, error_output)
+    output_bias_gradient = np.sum(error_output, axis=0)
+    
+    # gradient for the hidden layer
+    hidden_weights_gradient = np.matmul(X.T, error_hidden)
+    hidden_bias_gradient = np.sum(error_hidden, axis=0)
+
+    return output_weights_gradient, output_bias_gradient, hidden_weights_gradient, hidden_bias_gradient
+
+print("Old accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train)))
+
+eta = 0.01
+lmbd = 0.01
+for i in range(1000):
+    # calculate gradients
+    dWo, dBo, dWh, dBh = backpropagation(X_train, Y_train_onehot)
+    
+    # regularization term gradients
+    dWo += lmbd * output_weights
+    dWh += lmbd * hidden_weights
+    
+    # update weights and biases
+    output_weights -= eta * dWo
+    output_bias -= eta * dBo
+    hidden_weights -= eta * dWh
+    hidden_bias -= eta * dBh
+
+print("New accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train)))
 
    
 
    
 
    
@@ -188,6 +374,15 @@ MathJax.Hub.Config({
   
  • 20
    • 
   
  • 21
    • 
   
  • 22
    • 
+  
  • 23
    • 
+  
  • 24
    • 
+  
  • 25
    • 
+  
  • 26
    • 
+  
  • 27
    • 
+  
  • 28
    • 
+  
  • 29
    • 
+  
  • ...
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/._week41-bs020.html b/doc/pub/week41/html/._week41-bs020.html
index dd7b06487..409b5e319 100644
--- a/doc/pub/week41/html/._week41-bs020.html
+++ b/doc/pub/week41/html/._week41-bs020.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -148,42 +245,23 @@ MathJax.Hub.Config({
 
 
 
-
    Final visualization 
    
+
    Improving performance 
    
 
 
    
+As we can see the network does not seem to be learning at all. It seems to be just guessing the label for each image.  
+In order to obtain a network that does something useful, we will have to do a bit more work.
 
-
-
    # visual representation of grid search
-# uses seaborn heatmap, could probably do this in matplotlib
-import seaborn as sns
+
    
+The choice of hyperparameters such as learning rate and regularization parameter is hugely influential for the performance of the network. Typically a grid-search is performed, wherein we test different hyperparameters separated by orders of magnitude. For example we could test the learning rates \( \eta = 10^{-6}, 10^{-5},...,10^{-1} \) with different regularization parameters \( \lambda = 10^{-6},...,10^{-0} \).
 
-sns.set()
+
    
+Next, we haven't implemented minibatching yet, which introduces stochasticity and is though to act as an important regularizer on the weights. We call a feed-forward + backward pass with a minibatch an iteration, and a full training period
+going through the entire dataset (\( n/M \) batches) an epoch.
 
-train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
-test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
    
+If this does not improve network performance, you may want to consider altering the network architecture, adding more neurons or hidden layers.  
+Andrew Ng goes through some of these considerations in this video. You can find a summary of the video here.
 
-for i in range(len(eta_vals)):
-    for j in range(len(lmbd_vals)):
-        CNN = CNN_keras[i][j]
-
-        train_accuracy[i][j] = CNN.evaluate(X_train, Y_train)[1]
-        test_accuracy[i][j] = CNN.evaluate(X_test, Y_test)[1]
-
-        
-fig, ax = plt.subplots(figsize = (10, 10))
-sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
-ax.set_title("Training Accuracy")
-ax.set_ylabel("$\eta$")
-ax.set_xlabel("$\lambda$")
-plt.show()
-
-fig, ax = plt.subplots(figsize = (10, 10))
-sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
-ax.set_title("Test Accuracy")
-ax.set_ylabel("$\eta$")
-ax.set_xlabel("$\lambda$")
-plt.show()
-
    
 
    
 
    
 
@@ -201,6 +279,16 @@ plt.show()
   
  • 20
    • 
   
  • 21
    • 
   
  • 22
    • 
+  
  • 23
    • 
+  
  • 24
    • 
+  
  • 25
    • 
+  
  • 26
    • 
+  
  • 27
    • 
+  
  • 28
    • 
+  
  • 29
    • 
+  
  • 30
    • 
+  
  • ...
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/._week41-bs021.html b/doc/pub/week41/html/._week41-bs021.html
index 275cd4af3..5a0156ca8 100644
--- a/doc/pub/week41/html/._week41-bs021.html
+++ b/doc/pub/week41/html/._week41-bs021.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -148,14 +245,116 @@ MathJax.Hub.Config({
 
 
 
-
    Fun links 
    
+
    Full object-oriented implementation 
    
 
-
      
-
    1.  Self-Driving cars using a convolutional neural network
      2. 
-
    2.  Abstract art using convolutional neural networks
      3. 
-
    
+
    
+It is very natural to think of the network as an object, with specific instances of the network
+being realizations of this object with different hyperparameters. An implementation using Python classes provides a clean structure and interface, and the full implementation of our neural network is given below.
 
+
    
 
+
+
    class NeuralNetwork:
+    def __init__(
+            self,
+            X_data,
+            Y_data,
+            n_hidden_neurons=50,
+            n_categories=10,
+            epochs=10,
+            batch_size=100,
+            eta=0.1,
+            lmbd=0.0):
+
+        self.X_data_full = X_data
+        self.Y_data_full = Y_data
+
+        self.n_inputs = X_data.shape[0]
+        self.n_features = X_data.shape[1]
+        self.n_hidden_neurons = n_hidden_neurons
+        self.n_categories = n_categories
+
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self.iterations = self.n_inputs // self.batch_size
+        self.eta = eta
+        self.lmbd = lmbd
+
+        self.create_biases_and_weights()
+
+    def create_biases_and_weights(self):
+        self.hidden_weights = np.random.randn(self.n_features, self.n_hidden_neurons)
+        self.hidden_bias = np.zeros(self.n_hidden_neurons) + 0.01
+
+        self.output_weights = np.random.randn(self.n_hidden_neurons, self.n_categories)
+        self.output_bias = np.zeros(self.n_categories) + 0.01
+
+    def feed_forward(self):
+        # feed-forward for training
+        self.z_h = np.matmul(self.X_data, self.hidden_weights) + self.hidden_bias
+        self.a_h = sigmoid(self.z_h)
+
+        self.z_o = np.matmul(self.a_h, self.output_weights) + self.output_bias
+
+        exp_term = np.exp(self.z_o)
+        self.probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+
+    def feed_forward_out(self, X):
+        # feed-forward for output
+        z_h = np.matmul(X, self.hidden_weights) + self.hidden_bias
+        a_h = sigmoid(z_h)
+
+        z_o = np.matmul(a_h, self.output_weights) + self.output_bias
+        
+        exp_term = np.exp(z_o)
+        probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+        return probabilities
+
+    def backpropagation(self):
+        error_output = self.probabilities - self.Y_data
+        error_hidden = np.matmul(error_output, self.output_weights.T) * self.a_h * (1 - self.a_h)
+
+        self.output_weights_gradient = np.matmul(self.a_h.T, error_output)
+        self.output_bias_gradient = np.sum(error_output, axis=0)
+
+        self.hidden_weights_gradient = np.matmul(self.X_data.T, error_hidden)
+        self.hidden_bias_gradient = np.sum(error_hidden, axis=0)
+
+        if self.lmbd > 0.0:
+            self.output_weights_gradient += self.lmbd * self.output_weights
+            self.hidden_weights_gradient += self.lmbd * self.hidden_weights
+
+        self.output_weights -= self.eta * self.output_weights_gradient
+        self.output_bias -= self.eta * self.output_bias_gradient
+        self.hidden_weights -= self.eta * self.hidden_weights_gradient
+        self.hidden_bias -= self.eta * self.hidden_bias_gradient
+
+    def predict(self, X):
+        probabilities = self.feed_forward_out(X)
+        return np.argmax(probabilities, axis=1)
+
+    def predict_probabilities(self, X):
+        probabilities = self.feed_forward_out(X)
+        return probabilities
+
+    def train(self):
+        data_indices = np.arange(self.n_inputs)
+
+        for i in range(self.epochs):
+            for j in range(self.iterations):
+                # pick datapoints with replacement
+                chosen_datapoints = np.random.choice(
+                    data_indices, size=self.batch_size, replace=False
+                )
+
+                # minibatch training data
+                self.X_data = self.X_data_full[chosen_datapoints]
+                self.Y_data = self.Y_data_full[chosen_datapoints]
+
+                self.feed_forward()
+                self.backpropagation()
+
    
+
    
 
    
 
 
    
 
 
diff --git a/doc/pub/week41/html/week41-bs.html b/doc/pub/week41/html/week41-bs.html
index 2d605a454..112def37d 100644
--- a/doc/pub/week41/html/week41-bs.html
+++ b/doc/pub/week41/html/week41-bs.html
@@ -41,40 +41,98 @@ Automatically generated HTML file from DocOnce source
 
 
 
 
@@ -112,27 +170,66 @@ MathJax.Hub.Config({
       
  • 
         Contents 
         
       
    • 
@@ -167,7 +264,7 @@ MathJax.Hub.Config({
 
    [2] Department of Physics and Astronomy and National Superconducting Cyclotron Laboratory, Michigan State University
    
 
    
 
    
-
    Sep 16, 2020
     
+
    Oct 5, 2020
     
 
    
 
    
 
@@ -191,7 +288,7 @@ MathJax.Hub.Config({
   
  • 9
    • 
   
  • 10
    • 
   
  • ...
    • 
-  
  • 22
    • 
+  
  • 61
    • 
   
  • »
    • 
 
 
diff --git a/doc/pub/week41/html/week41-reveal.html b/doc/pub/week41/html/week41-reveal.html
index 755f227a9..8f9ad9417 100644
--- a/doc/pub/week41/html/week41-reveal.html
+++ b/doc/pub/week41/html/week41-reveal.html
@@ -148,7 +148,7 @@ MathJax.Hub.Config({
 
    [2] Department of Physics and Astronomy and National Superconducting Cyclotron Laboratory, Michigan State University
    
 
    
 
     
    
-
    Sep 16, 2020
     
+
    Oct 5, 2020
     
 
    
 
    
 
@@ -159,7 +159,1980 @@ MathJax.Hub.Config({
 
 
 
    
-
    Convolutional Neural Networks (recognizing images) 
    
+
    Plan for week 40 
    
+
+
      
+
    •  Thursday: Building our own Feed-forward Neural Network
      • 
+
    •  Friday: Playing around with our own Feed-forward Neural Network and introduction to TensorFlow. Start convolutional Neural Networks.
      • 
+
    
+
    
+
+Reading suggestions for both days: Aurelien Geron's chapters 10-11 and Hastie et al chapter 11.
+
    
+
+
+
    
+
    Overview video for week 41 
    
+
+
    
+"Overview Video, from Stochastic Gradient methods to Neural Networks":"https://www.uio.no/studier/emner/matnat/fys/FYS-STK3155/h20\
+/forelesningsvideoer/OverviewWeek41.mp4?vrtx=view-as-webpage"
+
    
+
+
+
    
+
    Setting up the Back propagation algorithm 
    
+
+
    
+The four equations  provide us with a way of computing the gradient of the cost function. Let us write this out in the form of an algorithm.
+
+
    
+
    
+
+
    
+First, we set up the input data \( \hat{x} \) and the activations
+\( \hat{z}_1 \) of the input layer and compute the activation function and
+the pertinent outputs \( \hat{a}^1 \).
+
    
+
+
    
+
    
+
+
    
+Secondly, we perform then the feed forward till we reach the output
+layer and compute all \( \hat{z}_l \) of the input layer and compute the
+activation function and the pertinent outputs \( \hat{a}^l \) for
+\( l=2,3,\dots,L \).
+
    
+
+
    
+
    
+
+
    
+Thereafter we compute the ouput error \( \hat{\delta}^L \) by computing all
+
     
    
+$$
+\delta_j^L = f'(z_j^L)\frac{\partial {\cal C}}{\partial (a_j^L)}.
+$$
+
     
    
+
    
+
+
    
+
    
+
+
    
+Then we compute the back propagate error for each \( l=L-1,L-2,\dots,2 \) as
+
     
    
+$$
+\delta_j^l = \sum_k \delta_k^{l+1}w_{kj}^{l+1}f'(z_j^l).
+$$
+
     
    
+
    
+
+
    
+
    
+
+
    
+Finally, we update the weights and the biases using gradient descent for each \( l=L-1,L-2,\dots,2 \) and update the weights and biases according to the rules
+
     
    
+$$
+w_{jk}^l\leftarrow  = w_{jk}^l- \eta \delta_j^la_k^{l-1},
+$$
+
     
    
+
+
     
    
+$$
+b_j^l \leftarrow b_j^l-\eta \frac{\partial {\cal C}}{\partial b_j^l}=b_j^l-\eta \delta_j^l,
+$$
+
     
    
+
    
+
+
    
+The parameter \( \eta \) is the learning parameter discussed in connection with the gradient descent methods.
+Here it is convenient to use stochastic gradient descent (see the examples below) with mini-batches with an outer loop that steps through multiple epochs of training.
+
    
+
+
+
    
+
    Setting up a Multi-layer perceptron model for classification  
    
+
+
    
+We are now gong to develop an example based on the MNIST data
+base. This is a classification problem and we need to use our
+cross-entropy function we discussed in connection with logistic
+regression. The cross-entropy defines our cost function for the
+classificaton problems with neural networks.
+
+
    
+In binary classification with two classes \( (0, 1) \) we define the
+logistic/sigmoid function as the probability that a particular input
+is in class \( 0 \) or \( 1 \).  This is possible because the logistic
+function takes any input from the real numbers and inputs a number
+between 0 and 1, and can therefore be interpreted as a probability. It
+also has other nice properties, such as a derivative that is simple to
+calculate.
+
+
    
+For an input \( \boldsymbol{a} \) from the hidden layer, the probability that the input \( \boldsymbol{x} \)
+is in class 0 or 1 is just. We let \( \theta \) represent the unknown weights and biases to be adjusted by our equations). The variable \( x \)
+represents our activation values \( z \). We have
+
     
    
+$$
+P(y = 0 \mid \hat{x}, \hat{\theta}) = \frac{1}{1 + \exp{(- \hat{x}})} ,
+$$
+
     
    
+
+and
+
     
    
+$$
+P(y = 1 \mid \hat{x}, \hat{\theta}) = 1 - P(y = 0 \mid \hat{x}, \hat{\theta}) ,
+$$
+
     
    
+
+
    
+where \( y \in \{0, 1\} \)  and \( \hat{\theta} \) represents the weights and biases
+of our network.
+
    
+
+
+
    
+
    Defining the cost function 
    
+
+
    
+Our cost function is given as (see the Logistic regression lectures)
+
     
    
+$$
+\mathcal{C}(\hat{\theta}) = - \ln P(\mathcal{D} \mid \hat{\theta}) = - \sum_{i=1}^n
+y_i \ln[P(y_i = 0)] + (1 - y_i) \ln [1 - P(y_i = 0)] = \sum_{i=1}^n \mathcal{L}_i(\hat{\theta}) .
+$$
+
     
    
+
+
    
+This last equality means that we can interpret our cost function as a sum over the loss function
+for each point in the dataset \( \mathcal{L}_i(\hat{\theta}) \).  
+The negative sign is just so that we can think about our algorithm as minimizing a positive number, rather
+than maximizing a negative number.
+
+
    
+In multiclass classification it is common to treat each integer label as a so called one-hot vector:
+
+
    
+\( y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) , \) and
+
+
    
+\( y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) , \)
+
+
    
+i.e. a binary bit string of length \( C \), where \( C = 10 \) is the number of classes in the MNIST dataset (numbers from \( 0 \) to \( 9 \))..
+
+
    
+If \( \hat{x}_i \) is the \( i \)-th input (image), \( y_{ic} \) refers to the \( c \)-th component of the \( i \)-th
+output vector \( \hat{y}_i \).  
+The probability of \( \hat{x}_i \) being in class \( c \) will be given by the softmax function:
+
+
     
    
+$$
+P(y_{ic} = 1 \mid \hat{x}_i, \hat{\theta}) = \frac{\exp{((\hat{a}_i^{hidden})^T \hat{w}_c)}}
+{\sum_{c'=0}^{C-1} \exp{((\hat{a}_i^{hidden})^T \hat{w}_{c'})}} ,
+$$
+
     
    
+
+
    
+which reduces to the logistic function in the binary case.  
+The likelihood of this \( C \)-class classifier
+is now given as:
+
+
     
    
+$$
+P(\mathcal{D} \mid \hat{\theta}) = \prod_{i=1}^n \prod_{c=0}^{C-1} [P(y_{ic} = 1)]^{y_{ic}} .
+$$
+
     
    
+
+Again we take the negative log-likelihood to define our cost function:
+
+
     
    
+$$
+\mathcal{C}(\hat{\theta}) = - \log{P(\mathcal{D} \mid \hat{\theta})}.
+$$
+
     
    
+
+See the logistic regression lectures for a full definition of the cost function.
+
+
    
+The back propagation equations need now only a small change, namely the definition of a new cost function. We are thus ready to use the same equations as before!
+
    
+
+
+
    
+
    Example: binary classification problem 
    
+
+
    
+As an example of the above, relevant for project 2 as well, let us consider a binary class. As discussed in our logistic regression lectures, we defined a cost function in terms of the parameters \( \beta \) as
+
     
    
+$$
+\mathcal{C}(\hat{\beta}) = - \sum_{i=1}^n \left(y_i\log{p(y_i \vert x_i,\hat{\beta})}+(1-y_i)\log{1-p(y_i \vert x_i,\hat{\beta})}\right),
+$$
+
     
    
+
+where we had defined the logistic (sigmoid) function
+
     
    
+$$
+p(y_i =1\vert x_i,\hat{\beta})=\frac{\exp{(\beta_0+\beta_1 x_i)}}{1+\exp{(\beta_0+\beta_1 x_i)}},
+$$
+
     
    
+
+and
+
     
    
+$$
+p(y_i =0\vert x_i,\hat{\beta})=1-p(y_i =1\vert x_i,\hat{\beta}).
+$$
+
     
    
+
+The parameters \( \hat{\beta} \) were defined using a minimization method like gradient descent or Newton-Raphson's method.
+
+
    
+Now we replace \( x_i \) with the activation \( z_i^l \) for a given layer \( l \) and the outputs as \( y_i=a_i^l=f(z_i^l) \), with \( z_i^l \) now being a function of the weights \( w_{ij}^l \) and biases \( b_i^l \). 
+We have then
+
     
    
+$$
+a_i^l = y_i = \frac{\exp{(z_i^l)}}{1+\exp{(z_i^l)}},
+$$
+
     
    
+
+with 
+
     
    
+$$
+z_i^l = \sum_{j}w_{ij}^l a_j^{l-1}+b_i^l,
+$$
+
     
    
+
+where the superscript \( l-1 \) indicates that these are the outputs from layer \( l-1 \).
+Our cost function at the final layer \( l=L \) is now
+
     
    
+$$
+\mathcal{C}(\hat{W}) = - \sum_{i=1}^n \left(t_i\log{a_i^L}+(1-t_i)\log{(1-a_i^L)}\right),
+$$
+
     
    
+
+where we have defined the targets \( t_i \). The derivatives of the cost function with respect to the output \( a_i^L \) are then easily calculated and we get
+
     
    
+$$
+\frac{\partial \mathcal{C}(\hat{W})}{\partial a_i^L} = \frac{a_i^L-t_i}{a_i^L(1-a_i^L)}. 
+$$
+
     
    
+
+In case we use another activation function than the logistic one, we need to evaluate other derivatives.
+
    
+
+
+
    
+
    The Softmax function 
    
+In case we employ the more general case given by the Softmax equation, we need to evaluate the derivative of the activation function with respect to the activation \( z_i^l \), that is we need
+
     
    
+$$
+\frac{\partial f(z_i^l)}{\partial w_{jk}^l} =
+\frac{\partial f(z_i^l)}{\partial z_j^l} \frac{\partial z_j^l}{\partial w_{jk}^l}= \frac{\partial f(z_i^l)}{\partial z_j^l}a_k^{l-1}.
+$$
+
     
    
+
+For the Softmax function we have
+
     
    
+$$
+f(z_i^l) = \frac{\exp{(z_i^l)}}{\sum_{m=1}^K\exp{(z_m^l)}}.
+$$
+
     
    
+
+Its derivative with respect to \( z_j^l \) gives 
+
     
    
+$$
+\frac{\partial f(z_i^l)}{\partial z_j^l}= f(z_i^l)\left(\delta_{ij}-f(z_j^l)\right), 
+$$
+
     
    
+
+which in case of the simply binary model reduces to  having \( i=j \).
+
    
+
+
+
    
+
    Developing a code for doing neural networks with back propagation 
    
+
+
    
+One can identify a set of key steps when using neural networks to solve supervised learning problems:  
+
+
      
+
    1.  Collect and pre-process data
      2. 
+
+
    2.  Define model and architecture
      3. 
+
+
    3.  Choose cost function and optimizer
      4. 
+
+
    4.  Train the model
      5. 
+
+
    5.  Evaluate model performance on test data
      6. 
+
+
    6.  Adjust hyperparameters (if necessary, network architecture)
      7. 
+
    
+
    
+
+
+
    
+
    Collect and pre-process data 
    
+
+
    
+Here we will be using the MNIST dataset, which is readily available through the scikit-learn
+package. You may also find it for example here.  
+The MNIST (Modified National Institute of Standards and Technology) database is a large database
+of handwritten digits that is commonly used for training various image processing systems.  
+The MNIST dataset consists of 70 000 images of size \( 28\times 28 \) pixels, each labeled from 0 to 9.  
+The scikit-learn dataset we will use consists of a selection of 1797 images of size \( 8\times 8 \) collected and processed from this database.
+
+
    
+To feed data into a feed-forward neural network we need to represent
+the inputs as a design/feature matrix \( X = (n_{inputs}, n_{features}) \).  Each
+row represents an input, in this case a handwritten digit, and
+each column represents a feature, in this case a pixel.  The
+correct answers, also known as labels or targets are
+represented as a 1D array of integers 
+\( Y = (n_{inputs}) = (5, 3, 1, 8,...) \).
+
+
    
+As an example, say we want to build a neural network using supervised learning to predict Body-Mass Index (BMI) from
+measurements of height (in m)  
+and weight (in kg). If we have measurements of 5 people the design/feature matrix could be for example:
+
+
     
    
+$$ X = \begin{bmatrix}
+1.85 & 81\\
+1.71 & 65\\
+1.95 & 103\\
+1.55 & 42\\
+1.63 & 56
+\end{bmatrix} ,$$
+
     
    
+
+
    
+and the targets would be:
+
+
     
    
+$$ Y = (23.7, 22.2, 27.1, 17.5, 21.1) $$
+
     
    
+
+
    
+Since each input image is a 2D matrix, we need to flatten the image
+(i.e. "unravel" the 2D matrix into a 1D array) to turn the data into a
+design/feature matrix. This means we lose all spatial information in the
+image, such as locality and translational invariance. More complicated
+architectures such as Convolutional Neural Networks can take advantage
+of such information, and are most commonly applied when analyzing
+images.
+
+
    
+
+
+
    # import necessary packages
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn import datasets
+
+
+# ensure the same random numbers appear every time
+np.random.seed(0)
+
+# display images in notebook
+%matplotlib inline
+plt.rcParams['figure.figsize'] = (12,12)
+
+
+# download MNIST dataset
+digits = datasets.load_digits()
+
+# define inputs and labels
+inputs = digits.images
+labels = digits.target
+
+print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
+
+
+# flatten the image
+# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64
+n_inputs = len(inputs)
+inputs = inputs.reshape(n_inputs, -1)
+print("X = (n_inputs, n_features) = " + str(inputs.shape))
+
+
+# choose some random images to display
+indices = np.arange(n_inputs)
+random_indices = np.random.choice(indices, size=5)
+
+for i, image in enumerate(digits.images[random_indices]):
+    plt.subplot(1, 5, i+1)
+    plt.axis('off')
+    plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')
+    plt.title("Label: %d" % digits.target[random_indices[i]])
+plt.show()
+
    
+
    
+
+
+
    
+
    Train and test datasets 
    
+
+
    
+Performing analysis before partitioning the dataset is a major error, that can lead to incorrect conclusions.
+
+
    
+We will reserve \( 80 \% \) of our dataset for training and \( 20 \% \) for testing.
+
+
    
+It is important that the train and test datasets are drawn randomly from our dataset, to ensure
+no bias in the sampling.  
+Say you are taking measurements of weather data to predict the weather in the coming 5 days.
+You don't want to train your model on measurements taken from the hours 00.00 to 12.00, and then test it on data
+collected from 12.00 to 24.00.
+
+
    
+
+
+
    from sklearn.model_selection import train_test_split
+
+# one-liner from scikit-learn library
+train_size = 0.8
+test_size = 1 - train_size
+X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,
+                                                    test_size=test_size)
+
+# equivalently in numpy
+def train_test_split_numpy(inputs, labels, train_size, test_size):
+    n_inputs = len(inputs)
+    inputs_shuffled = inputs.copy()
+    labels_shuffled = labels.copy()
+    
+    np.random.shuffle(inputs_shuffled)
+    np.random.shuffle(labels_shuffled)
+    
+    train_end = int(n_inputs*train_size)
+    X_train, X_test = inputs_shuffled[:train_end], inputs_shuffled[train_end:]
+    Y_train, Y_test = labels_shuffled[:train_end], labels_shuffled[train_end:]
+    
+    return X_train, X_test, Y_train, Y_test
+
+#X_train, X_test, Y_train, Y_test = train_test_split_numpy(inputs, labels, train_size, test_size)
+
+print("Number of training images: " + str(len(X_train)))
+print("Number of test images: " + str(len(X_test)))
+
    
+
    
+
+
+
    
+
    Define model and architecture 
    
+
+
    
+Our simple feed-forward neural network will consist of an input layer, a single hidden layer and an output layer. The activation \( y \) of each neuron is a weighted sum of inputs, passed through an activation function. In case of the simple perceptron model we have
+
+
     
    
+$$ z = \sum_{i=1}^n w_i a_i ,$$
+
     
    
+
+
     
    
+$$ y = f(z) ,$$
+
     
    
+
+
    
+where \( f \) is the activation function, \( a_i \) represents input from neuron \( i \) in the preceding layer
+and \( w_i \) is the weight to input \( i \).  
+The activation of the neurons in the input layer is just the features (e.g. a pixel value).
+
+
    
+The simplest activation function for a neuron is the Heaviside function:
+
+
     
    
+$$ f(z) = 
+\begin{cases}
+1,  &  z > 0\\
+0,  & \text{otherwise}
+\end{cases}
+$$
+
     
    
+
+
    
+A feed-forward neural network with this activation is known as a perceptron.  
+For a binary classifier (i.e. two classes, 0 or 1, dog or not-dog) we can also use this in our output layer.  
+This activation can be generalized to \( k \) classes (using e.g. the one-against-all strategy), 
+and we call these architectures multiclass perceptrons.
+
+
    
+However, it is now common to use the terms Single Layer Perceptron (SLP) (1 hidden layer) and  
+Multilayer Perceptron (MLP) (2 or more hidden layers) to refer to feed-forward neural networks with any activation function.
+
+
    
+Typical choices for activation functions include the sigmoid function, hyperbolic tangent, and Rectified Linear Unit (ReLU).  
+We will be using the sigmoid function \( \sigma(x) \):
+
+
     
    
+$$ f(x) = \sigma(x) = \frac{1}{1 + e^{-x}} ,$$
+
     
    
+
+
    
+which is inspired by probability theory (see logistic regression) and was most commonly used until about 2011. See the discussion below concerning other activation functions.
+
    
+
+
+
    
+
    Layers 
    
+
+
      
+
    •  Input
      •  
+
    
+
    
+
+Since each input image has 8x8 = 64 pixels or features, we have an input layer of 64 neurons.  
+
+
      
+
    •  Hidden layer
      • 
+
    
+
    
+
+We will use 50 neurons in the hidden layer receiving input from the neurons in the input layer.  
+Since each neuron in the hidden layer is connected to the 64 inputs we have 64x50 = 3200 weights to the hidden layer.  
+
+
      
+
    •  Output
      • 
+
    
+
    
+
+If we were building a binary classifier, it would be sufficient with a single neuron in the output layer,
+which could output 0 or 1 according to the Heaviside function. This would be an example of a hard classifier, meaning it outputs the class of the input directly. However, if we are dealing with noisy data it is often beneficial to use a soft classifier, which outputs the probability of being in class 0 or 1.
+
+
    
+For a soft binary classifier, we could use a single neuron and interpret the output as either being the probability of being in class 0 or the probability of being in class 1. Alternatively we could use 2 neurons, and interpret each neuron as the probability of being in each class.
+
+
    
+Since we are doing multiclass classification, with 10 categories, it is natural to use 10 neurons in the output layer. We number the neurons \( j = 0,1,...,9 \). The activation of each output neuron \( j \) will be according to the softmax function:
+
+
     
    
+$$ P(\text{class \( j \)} \mid \text{input \( \hat{a} \)}) = \frac{\exp{(\hat{a}^T \hat{w}_j)}}
+{\sum_{c=0}^{9} \exp{(\hat{a}^T \hat{w}_c)}} ,$$
+
     
    
+
+
    
+i.e. each neuron \( j \) outputs the probability of being in class \( j \) given an input from the hidden layer \( \hat{a} \), with \( \hat{w}_j \) the weights of neuron \( j \) to the inputs.  
+The denominator is a normalization factor to ensure the outputs (probabilities) sum up to 1.  
+The exponent is just the weighted sum of inputs as before:
+
+
     
    
+$$ z_j = \sum_{i=1}^n w_ {ij} a_i+b_j.$$
+
     
    
+
+
    
+Since each neuron in the output layer is connected to the 50 inputs from the hidden layer we have 50x10 = 500
+weights to the output layer.
+
    
+
+
+
    
+
    Weights and biases 
    
+
+
    
+Typically weights are initialized with small values distributed around zero, drawn from a uniform
+or normal distribution. Setting all weights to zero means all neurons give the same output, making the network useless.
+
+
    
+Adding a bias value to the weighted sum of inputs allows the neural network to represent a greater range
+of values. Without it, any input with the value 0 will be mapped to zero (before being passed through the activation). The bias unit has an output of 1, and a weight to each neuron \( j \), \( b_j \):
+
+
     
    
+$$ z_j = \sum_{i=1}^n w_ {ij} a_i + b_j.$$
+
     
    
+
+
    
+The bias weights \( \hat{b} \) are often initialized to zero, but a small value like \( 0.01 \) ensures all neurons have some output which can be backpropagated in the first training cycle.
+
    
+
+
+
    # building our neural network
+
+n_inputs, n_features = X_train.shape
+n_hidden_neurons = 50
+n_categories = 10
+
+# we make the weights normally distributed using numpy.random.randn
+
+# weights and bias in the hidden layer
+hidden_weights = np.random.randn(n_features, n_hidden_neurons)
+hidden_bias = np.zeros(n_hidden_neurons) + 0.01
+
+# weights and bias in the output layer
+output_weights = np.random.randn(n_hidden_neurons, n_categories)
+output_bias = np.zeros(n_categories) + 0.01
+
    
+
    
+
+
+
    
+
    Feed-forward pass 
    
+
+
    
+Denote \( F \) the number of features, \( H \) the number of hidden neurons and \( C \) the number of categories.  
+For each input image we calculate a weighted sum of input features (pixel values) to each neuron \( j \) in the hidden layer \( l \):
+
+
     
    
+$$ z_{j}^{l} = \sum_{i=1}^{F} w_{ij}^{l} x_i + b_{j}^{l},$$
+
     
    
+
+
    
+this is then passed through our activation function
+
+
     
    
+$$ a_{j}^{l} = f(z_{j}^{l}) .$$
+
     
    
+
+
    
+We calculate a weighted sum of inputs (activations in the hidden layer) to each neuron \( j \) in the output layer:
+
+
     
    
+$$ z_{j}^{L} = \sum_{i=1}^{H} w_{ij}^{L} a_{i}^{l} + b_{j}^{L}.$$
+
     
    
+
+
    
+Finally we calculate the output of neuron \( j \) in the output layer using the softmax function:
+
+
     
    
+$$ a_{j}^{L} = \frac{\exp{(z_j^{L})}}
+{\sum_{c=0}^{C-1} \exp{(z_c^{L})}} .$$
+
     
    
+
    
+
+
+
    
+
    Matrix multiplications 
    
+
+
    
+Since our data has the dimensions \( X = (n_{inputs}, n_{features}) \) and our weights to the hidden
+layer have the dimensions  
+\( W_{hidden} = (n_{features}, n_{hidden}) \),
+we can easily feed the network all our training data in one go by taking the matrix product
+
+
     
    
+$$ X W^{h} = (n_{inputs}, n_{hidden}),$$
+
     
    
+
+
    
+and obtain a matrix that holds the weighted sum of inputs to the hidden layer
+for each input image and each hidden neuron.    
+We also add the bias to obtain a matrix of weighted sums to the hidden layer \( Z^{h} \):
+
+
     
    
+$$ \hat{z}^{l} = \hat{X} \hat{W}^{l} + \hat{b}^{l} ,$$
+
     
    
+
+
    
+meaning the same bias (1D array with size equal number of hidden neurons) is added to each input image.  
+This is then passed through the activation:
+
+
     
    
+$$ \hat{a}^{l} = f(\hat{z}^l) .$$
+
     
    
+
+
    
+This is fed to the output layer:
+
+
     
    
+$$ \hat{z}^{L} = \hat{a}^{L} \hat{W}^{L} + \hat{b}^{L} .$$
+
     
    
+
+
    
+Finally we receive our output values for each image and each category by passing it through the softmax function:
+
+
     
    
+$$ output = softmax (\hat{z}^{L}) = (n_{inputs}, n_{categories}) .$$
+
     
    
+
+
    
+
+
+
    # setup the feed-forward pass, subscript h = hidden layer
+
+def sigmoid(x):
+    return 1/(1 + np.exp(-x))
+
+def feed_forward(X):
+    # weighted sum of inputs to the hidden layer
+    z_h = np.matmul(X, hidden_weights) + hidden_bias
+    # activation in the hidden layer
+    a_h = sigmoid(z_h)
+    
+    # weighted sum of inputs to the output layer
+    z_o = np.matmul(a_h, output_weights) + output_bias
+    # softmax output
+    # axis 0 holds each input and axis 1 the probabilities of each category
+    exp_term = np.exp(z_o)
+    probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+    
+    return probabilities
+
+probabilities = feed_forward(X_train)
+print("probabilities = (n_inputs, n_categories) = " + str(probabilities.shape))
+print("probability that image 0 is in category 0,1,2,...,9 = \n" + str(probabilities[0]))
+print("probabilities sum up to: " + str(probabilities[0].sum()))
+print()
+
+# we obtain a prediction by taking the class with the highest likelihood
+def predict(X):
+    probabilities = feed_forward(X)
+    return np.argmax(probabilities, axis=1)
+
+predictions = predict(X_train)
+print("predictions = (n_inputs) = " + str(predictions.shape))
+print("prediction for image 0: " + str(predictions[0]))
+print("correct label for image 0: " + str(Y_train[0]))
+
    
+
    
+
+
+
    
+
    Choose cost function and optimizer 
    
+
+
    
+To measure how well our neural network is doing we need to introduce a cost function.  
+We will call the function that gives the error of a single sample output the loss function, and the function
+that gives the total error of our network across all samples the cost function.
+A typical choice for multiclass classification is the cross-entropy loss, also known as the negative log likelihood.
+
+
    
+In multiclass classification it is common to treat each integer label as a so called one-hot vector:
+
+
     
    
+$$ y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) ,$$
+
     
    
+
+
     
    
+$$ y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) ,$$
+
     
    
+
+
    
+i.e. a binary bit string of length \( C \), where \( C = 10 \) is the number of classes in the MNIST dataset.
+
+
    
+Let \( y_{ic} \) denote the \( c \)-th component of the \( i \)-th one-hot vector.  
+We define the cost function \( \mathcal{C} \) as a sum over the cross-entropy loss for each point \( \hat{x}_i \) in the dataset.
+
+
    
+In the one-hot representation only one of the terms in the loss function is non-zero, namely the
+probability of the correct category \( c' \)  
+(i.e. the category \( c' \) such that \( y_{ic'} = 1 \)). This means that the cross entropy loss only punishes you for how wrong
+you got the correct label. The probability of category \( c \) is given by the softmax function. The vector \( \hat{\theta} \) represents the parameters of our network, i.e. all the weights and biases.
+
    
+
+
+
    
+
    Optimizing the cost function 
    
+
+
    
+The network is trained by finding the weights and biases that minimize the cost function. One of the most widely used classes of methods is gradient descent and its generalizations. The idea behind gradient descent
+is simply to adjust the weights in the direction where the gradient of the cost function is large and negative. This ensures we flow toward a local minimum of the cost function.  
+Each parameter \( \theta \) is iteratively adjusted according to the rule
+
+
     
    
+$$ \theta_{i+1} = \theta_i - \eta \nabla \mathcal{C}(\theta_i) ,$$
+
     
    
+
+
    
+where \( \eta \) is known as the learning rate, which controls how big a step we take towards the minimum.  
+This update can be repeated for any number of iterations, or until we are satisfied with the result.
+
+
    
+A simple and effective improvement is a variant called Batch Gradient Descent.  
+Instead of calculating the gradient on the whole dataset, we calculate an approximation of the gradient
+on a subset of the data called a minibatch.  
+If there are \( N \) data points and we have a minibatch size of \( M \), the total number of batches
+is \( N/M \).  
+We denote each minibatch \( B_k \), with \( k = 1, 2,...,N/M \). The gradient then becomes:
+
+
     
    
+$$ \nabla \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \nabla \mathcal{L}_i(\theta) \quad \rightarrow \quad
+\frac{1}{M} \sum_{i \in B_k} \nabla \mathcal{L}_i(\theta) ,$$
+
     
    
+
+
    
+i.e. instead of averaging the loss over the entire dataset, we average over a minibatch.
+
+
    
+This has two important benefits:  
+
+
      
+
    1.  Introducing stochasticity decreases the chance that the algorithm becomes stuck in a local minima.
      2. 
+
+
    2.  It significantly speeds up the calculation, since we do not have to use the entire dataset to calculate the gradient.
      3.   
+
    
+
    
+
+The various optmization  methods, with codes and algorithms,  are discussed in our lectures on Gradient descent approaches.
+
    
+
+
+
    
+
    Regularization 
    
+
+
    
+It is common to add an extra term to the cost function, proportional
+to the size of the weights.  This is equivalent to constraining the
+size of the weights, so that they do not grow out of control.
+Constraining the size of the weights means that the weights cannot
+grow arbitrarily large to fit the training data, and in this way
+reduces overfitting.
+
+
    
+We will measure the size of the weights using the so called L2-norm, meaning our cost function becomes:
+
+
     
    
+$$  \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \mathcal{L}_i(\theta) \quad \rightarrow \quad
+\frac{1}{N} \sum_{i=1}^N  \mathcal{L}_i(\theta) + \lambda \lvert \lvert \hat{w} \rvert \rvert_2^2 
+= \frac{1}{N} \sum_{i=1}^N  \mathcal{L}(\theta) + \lambda \sum_{ij} w_{ij}^2,$$
+
     
    
+
+
    
+i.e. we sum up all the weights squared. The factor \( \lambda \) is known as a regularization parameter.
+
+
    
+In order to train the model, we need to calculate the derivative of
+the cost function with respect to every bias and weight in the
+network.  In total our network has \( (64 + 1)\times 50=3250 \) weights in
+the hidden layer and \( (50 + 1)\times 10=510 \) weights to the output
+layer (\( +1 \) for the bias), and the gradient must be calculated for
+every parameter.  We use the backpropagation algorithm discussed
+above. This is a clever use of the chain rule that allows us to
+calculate the gradient efficently.
+
    
+
+
+
    
+
    Matrix  multiplication 
    
+
+
    
+To more efficently train our network these equations are implemented using matrix operations.  
+The error in the output layer is calculated simply as, with \( \hat{t} \) being our targets,
+
+
     
    
+$$ \delta_L = \hat{t} - \hat{y} = (n_{inputs}, n_{categories}) .$$
+
     
    
+
+
    
+The gradient for the output weights is calculated as
+
+
     
    
+$$ \nabla W_{L} = \hat{a}^T \delta_L   = (n_{hidden}, n_{categories}) ,$$
+
     
    
+
+
    
+where \( \hat{a} = (n_{inputs}, n_{hidden}) \). This simply means that we are summing up the gradients for each input.  
+Since we are going backwards we have to transpose the activation matrix.
+
+
    
+The gradient with respect to the output bias is then
+
+
     
    
+$$ \nabla \hat{b}_{L} = \sum_{i=1}^{n_{inputs}} \delta_L = (n_{categories}) .$$
+
     
    
+
+
    
+The error in the hidden layer is
+
+
     
    
+$$ \Delta_h = \delta_L W_{L}^T \circ f'(z_{h}) = \delta_L W_{L}^T \circ a_{h} \circ (1 - a_{h}) = (n_{inputs}, n_{hidden}) ,$$
+
     
    
+
+
    
+where \( f'(a_{h}) \) is the derivative of the activation in the hidden layer. The matrix products mean
+that we are summing up the products for each neuron in the output layer. The symbol \( \circ \) denotes
+the Hadamard product, meaning element-wise multiplication.
+
+
    
+This again gives us the gradients in the hidden layer:
+
+
     
    
+$$ \nabla W_{h} = X^T \delta_h = (n_{features}, n_{hidden}) ,$$
+
     
    
+
+
     
    
+$$ \nabla b_{h} = \sum_{i=1}^{n_{inputs}} \delta_h = (n_{hidden}) .$$
+
     
    
+
+
    
+
+
+
    # to categorical turns our integer vector into a onehot representation
+from sklearn.metrics import accuracy_score
+
+# one-hot in numpy
+def to_categorical_numpy(integer_vector):
+    n_inputs = len(integer_vector)
+    n_categories = np.max(integer_vector) + 1
+    onehot_vector = np.zeros((n_inputs, n_categories))
+    onehot_vector[range(n_inputs), integer_vector] = 1
+    
+    return onehot_vector
+
+#Y_train_onehot, Y_test_onehot = to_categorical(Y_train), to_categorical(Y_test)
+Y_train_onehot, Y_test_onehot = to_categorical_numpy(Y_train), to_categorical_numpy(Y_test)
+
+def feed_forward_train(X):
+    # weighted sum of inputs to the hidden layer
+    z_h = np.matmul(X, hidden_weights) + hidden_bias
+    # activation in the hidden layer
+    a_h = sigmoid(z_h)
+    
+    # weighted sum of inputs to the output layer
+    z_o = np.matmul(a_h, output_weights) + output_bias
+    # softmax output
+    # axis 0 holds each input and axis 1 the probabilities of each category
+    exp_term = np.exp(z_o)
+    probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+    
+    # for backpropagation need activations in hidden and output layers
+    return a_h, probabilities
+
+def backpropagation(X, Y):
+    a_h, probabilities = feed_forward_train(X)
+    
+    # error in the output layer
+    error_output = probabilities - Y
+    # error in the hidden layer
+    error_hidden = np.matmul(error_output, output_weights.T) * a_h * (1 - a_h)
+    
+    # gradients for the output layer
+    output_weights_gradient = np.matmul(a_h.T, error_output)
+    output_bias_gradient = np.sum(error_output, axis=0)
+    
+    # gradient for the hidden layer
+    hidden_weights_gradient = np.matmul(X.T, error_hidden)
+    hidden_bias_gradient = np.sum(error_hidden, axis=0)
+
+    return output_weights_gradient, output_bias_gradient, hidden_weights_gradient, hidden_bias_gradient
+
+print("Old accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train)))
+
+eta = 0.01
+lmbd = 0.01
+for i in range(1000):
+    # calculate gradients
+    dWo, dBo, dWh, dBh = backpropagation(X_train, Y_train_onehot)
+    
+    # regularization term gradients
+    dWo += lmbd * output_weights
+    dWh += lmbd * hidden_weights
+    
+    # update weights and biases
+    output_weights -= eta * dWo
+    output_bias -= eta * dBo
+    hidden_weights -= eta * dWh
+    hidden_bias -= eta * dBh
+
+print("New accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train)))
+
    
+
    
+
+
+
    
+
    Improving performance 
    
+
+
    
+As we can see the network does not seem to be learning at all. It seems to be just guessing the label for each image.  
+In order to obtain a network that does something useful, we will have to do a bit more work.
+
+
    
+The choice of hyperparameters such as learning rate and regularization parameter is hugely influential for the performance of the network. Typically a grid-search is performed, wherein we test different hyperparameters separated by orders of magnitude. For example we could test the learning rates \( \eta = 10^{-6}, 10^{-5},...,10^{-1} \) with different regularization parameters \( \lambda = 10^{-6},...,10^{-0} \).
+
+
    
+Next, we haven't implemented minibatching yet, which introduces stochasticity and is though to act as an important regularizer on the weights. We call a feed-forward + backward pass with a minibatch an iteration, and a full training period
+going through the entire dataset (\( n/M \) batches) an epoch.
+
+
    
+If this does not improve network performance, you may want to consider altering the network architecture, adding more neurons or hidden layers.  
+Andrew Ng goes through some of these considerations in this video. You can find a summary of the video here.
+
    
+
+
+
    
+
    Full object-oriented implementation 
    
+
+
    
+It is very natural to think of the network as an object, with specific instances of the network
+being realizations of this object with different hyperparameters. An implementation using Python classes provides a clean structure and interface, and the full implementation of our neural network is given below.
+
+
    
+
+
+
    class NeuralNetwork:
+    def __init__(
+            self,
+            X_data,
+            Y_data,
+            n_hidden_neurons=50,
+            n_categories=10,
+            epochs=10,
+            batch_size=100,
+            eta=0.1,
+            lmbd=0.0):
+
+        self.X_data_full = X_data
+        self.Y_data_full = Y_data
+
+        self.n_inputs = X_data.shape[0]
+        self.n_features = X_data.shape[1]
+        self.n_hidden_neurons = n_hidden_neurons
+        self.n_categories = n_categories
+
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self.iterations = self.n_inputs // self.batch_size
+        self.eta = eta
+        self.lmbd = lmbd
+
+        self.create_biases_and_weights()
+
+    def create_biases_and_weights(self):
+        self.hidden_weights = np.random.randn(self.n_features, self.n_hidden_neurons)
+        self.hidden_bias = np.zeros(self.n_hidden_neurons) + 0.01
+
+        self.output_weights = np.random.randn(self.n_hidden_neurons, self.n_categories)
+        self.output_bias = np.zeros(self.n_categories) + 0.01
+
+    def feed_forward(self):
+        # feed-forward for training
+        self.z_h = np.matmul(self.X_data, self.hidden_weights) + self.hidden_bias
+        self.a_h = sigmoid(self.z_h)
+
+        self.z_o = np.matmul(self.a_h, self.output_weights) + self.output_bias
+
+        exp_term = np.exp(self.z_o)
+        self.probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+
+    def feed_forward_out(self, X):
+        # feed-forward for output
+        z_h = np.matmul(X, self.hidden_weights) + self.hidden_bias
+        a_h = sigmoid(z_h)
+
+        z_o = np.matmul(a_h, self.output_weights) + self.output_bias
+        
+        exp_term = np.exp(z_o)
+        probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+        return probabilities
+
+    def backpropagation(self):
+        error_output = self.probabilities - self.Y_data
+        error_hidden = np.matmul(error_output, self.output_weights.T) * self.a_h * (1 - self.a_h)
+
+        self.output_weights_gradient = np.matmul(self.a_h.T, error_output)
+        self.output_bias_gradient = np.sum(error_output, axis=0)
+
+        self.hidden_weights_gradient = np.matmul(self.X_data.T, error_hidden)
+        self.hidden_bias_gradient = np.sum(error_hidden, axis=0)
+
+        if self.lmbd > 0.0:
+            self.output_weights_gradient += self.lmbd * self.output_weights
+            self.hidden_weights_gradient += self.lmbd * self.hidden_weights
+
+        self.output_weights -= self.eta * self.output_weights_gradient
+        self.output_bias -= self.eta * self.output_bias_gradient
+        self.hidden_weights -= self.eta * self.hidden_weights_gradient
+        self.hidden_bias -= self.eta * self.hidden_bias_gradient
+
+    def predict(self, X):
+        probabilities = self.feed_forward_out(X)
+        return np.argmax(probabilities, axis=1)
+
+    def predict_probabilities(self, X):
+        probabilities = self.feed_forward_out(X)
+        return probabilities
+
+    def train(self):
+        data_indices = np.arange(self.n_inputs)
+
+        for i in range(self.epochs):
+            for j in range(self.iterations):
+                # pick datapoints with replacement
+                chosen_datapoints = np.random.choice(
+                    data_indices, size=self.batch_size, replace=False
+                )
+
+                # minibatch training data
+                self.X_data = self.X_data_full[chosen_datapoints]
+                self.Y_data = self.Y_data_full[chosen_datapoints]
+
+                self.feed_forward()
+                self.backpropagation()
+
    
+
    
+
+
+
    
+
    Evaluate model performance on test data 
    
+
+
    
+To measure the performance of our network we evaluate how well it does it data it has never seen before, i.e. the test data.  
+We measure the performance of the network using the accuracy score.  
+The accuracy is as you would expect just the number of images correctly labeled divided by the total number of images. A perfect classifier will have an accuracy score of \( 1 \).
+
+
     
    
+$$ \text{Accuracy} = \frac{\sum_{i=1}^n I(\hat{y}_i = y_i)}{n} ,$$
+
     
    
+
+
    
+where \( I \) is the indicator function, \( 1 \) if \( \hat{y}_i = y_i \) and \( 0 \) otherwise.
+
+
    
+
+
+
    epochs = 100
+batch_size = 100
+
+dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size,
+                    n_hidden_neurons=n_hidden_neurons, n_categories=n_categories)
+dnn.train()
+test_predict = dnn.predict(X_test)
+
+# accuracy score from scikit library
+print("Accuracy score on test set: ", accuracy_score(Y_test, test_predict))
+
+# equivalent in numpy
+def accuracy_score_numpy(Y_test, Y_pred):
+    return np.sum(Y_test == Y_pred) / len(Y_test)
+
+#print("Accuracy score on test set: ", accuracy_score_numpy(Y_test, test_predict))
+
    
+
    
+
+
+
    
+
    Adjust hyperparameters 
    
+
+
    
+We now perform a grid search to find the optimal hyperparameters for the network.  
+Note that we are only using 1 layer with 50 neurons, and human performance is estimated to be around \( 98\% \) (\( 2\% \) error rate).
+
+
    
+
+
+
    eta_vals = np.logspace(-5, 1, 7)
+lmbd_vals = np.logspace(-5, 1, 7)
+# store the models for later use
+DNN_numpy = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+
+# grid search
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size,
+                            n_hidden_neurons=n_hidden_neurons, n_categories=n_categories)
+        dnn.train()
+        
+        DNN_numpy[i][j] = dnn
+        
+        test_predict = dnn.predict(X_test)
+        
+        print("Learning rate  = ", eta)
+        print("Lambda = ", lmbd)
+        print("Accuracy score on test set: ", accuracy_score(Y_test, test_predict))
+        print()
+
    
+
    
+
+
+
    
+
    Visualization 
    
+
+
    
+
+
+
    # visual representation of grid search
+# uses seaborn heatmap, you can also do this with matplotlib imshow
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        dnn = DNN_numpy[i][j]
+        
+        train_pred = dnn.predict(X_train) 
+        test_pred = dnn.predict(X_test)
+
+        train_accuracy[i][j] = accuracy_score(Y_train, train_pred)
+        test_accuracy[i][j] = accuracy_score(Y_test, test_pred)
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
    
+
    
+
+
+
    
+
    scikit-learn implementation 
    
+
+
    
+scikit-learn focuses more
+on traditional machine learning methods, such as regression,
+clustering, decision trees, etc. As such, it has only two types of
+neural networks: Multi Layer Perceptron outputting continuous values,
+MPLRegressor, and Multi Layer Perceptron outputting labels,
+MLPClassifier. We will see how simple it is to use these classes.
+
+
    
+scikit-learn implements a few improvements from our neural network,
+such as early stopping, a varying learning rate, different
+optimization methods, etc. We would therefore expect a better
+performance overall.
+
+
    
+
+
+
    from sklearn.neural_network import MLPClassifier
+# store models for later use
+DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        dnn = MLPClassifier(hidden_layer_sizes=(n_hidden_neurons), activation='logistic',
+                            alpha=lmbd, learning_rate_init=eta, max_iter=epochs)
+        dnn.fit(X_train, Y_train)
+        
+        DNN_scikit[i][j] = dnn
+        
+        print("Learning rate  = ", eta)
+        print("Lambda = ", lmbd)
+        print("Accuracy score on test set: ", dnn.score(X_test, Y_test))
+        print()
+
    
+
    
+
+
+
    
+
    Visualization 
    
+
    
+
+
+
    # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        dnn = DNN_scikit[i][j]
+        
+        train_pred = dnn.predict(X_train) 
+        test_pred = dnn.predict(X_test)
+
+        train_accuracy[i][j] = accuracy_score(Y_train, train_pred)
+        test_accuracy[i][j] = accuracy_score(Y_test, test_pred)
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
    
+
    
+
+
+
    
+
    Building neural networks in Tensorflow and Keras 
    
+
+
    
+Now we want  to build on the experience gained from our neural network implementation in NumPy and scikit-learn
+and use it to construct a neural network in Tensorflow. Once we have constructed a neural network in NumPy
+and Tensorflow, building one in Keras is really quite trivial, though the performance may suffer.
+
+
    
+In our previous example we used only one hidden layer, and in this we will use two. From this it should be quite
+clear how to build one using an arbitrary number of hidden layers, using data structures such as Python lists or
+NumPy arrays.
+
    
+
+
+
    
+
    Tensorflow 
    
+
+
    
+Tensorflow is an open source library machine learning library
+developed by the Google Brain team for internal use. It was released
+under the Apache 2.0 open source license in November 9, 2015.
+
+
    
+Tensorflow is a computational framework that allows you to construct
+machine learning models at different levels of abstraction, from
+high-level, object-oriented APIs like Keras, down to the C++ kernels
+that Tensorflow is built upon. The higher levels of abstraction are
+simpler to use, but less flexible, and our choice of implementation
+should reflect the problems we are trying to solve.
+
+
    
+Tensorflow uses so-called graphs to represent your computation
+in terms of the dependencies between individual operations, such that you first build a Tensorflow graph
+to represent your model, and then create a Tensorflow session to run the graph.
+
+
    
+In this guide we will analyze the same data as we did in our NumPy and
+scikit-learn tutorial, gathered from the MNIST database of images. We
+will give an introduction to the lower level Python Application
+Program Interfaces (APIs), and see how we use them to build our graph.
+Then we will build (effectively) the same graph in Keras, to see just
+how simple solving a machine learning problem can be.
+
+
    
+To install tensorflow on Unix/Linux systems, use pip as
+
    
+
+
+
    pip3 install tensorflow
+
    
+
    
+and/or if you use anaconda, just write (or install from the graphical user interface)
+
    
+
+
+
    conda install tensorflow
+
    
+
    
+
+
+
    
+
    Collect and pre-process data 
    
+
+
    
+
+
+
    # import necessary packages
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn import datasets
+
+
+# ensure the same random numbers appear every time
+np.random.seed(0)
+
+# display images in notebook
+%matplotlib inline
+plt.rcParams['figure.figsize'] = (12,12)
+
+
+# download MNIST dataset
+digits = datasets.load_digits()
+
+# define inputs and labels
+inputs = digits.images
+labels = digits.target
+
+print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
+
+
+# flatten the image
+# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64
+n_inputs = len(inputs)
+inputs = inputs.reshape(n_inputs, -1)
+print("X = (n_inputs, n_features) = " + str(inputs.shape))
+
+
+# choose some random images to display
+indices = np.arange(n_inputs)
+random_indices = np.random.choice(indices, size=5)
+
+for i, image in enumerate(digits.images[random_indices]):
+    plt.subplot(1, 5, i+1)
+    plt.axis('off')
+    plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')
+    plt.title("Label: %d" % digits.target[random_indices[i]])
+plt.show()
+
    
+
    
+
+
+
    from keras.utils import to_categorical
+from sklearn.model_selection import train_test_split
+
+# one-hot representation of labels
+labels = to_categorical(labels)
+
+# split into train and test data
+train_size = 0.8
+test_size = 1 - train_size
+X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,
+                                                    test_size=test_size)
+
    
+
    
+
+
+
    
+
    Using TensorFlow backend 
    
+
+
      
+
    1.  Define model and architecture
      2. 
+
    2.  Choose cost function and optimizer
      3. 
+
    
+
    
+
+
+
    import tensorflow as tf
+
+class NeuralNetworkTensorflow:
+    def __init__(
+            self,
+            X_train,
+            Y_train,
+            X_test,
+            Y_test,
+            n_neurons_layer1=100,
+            n_neurons_layer2=50,
+            n_categories=2,
+            epochs=10,
+            batch_size=100,
+            eta=0.1,
+            lmbd=0.0):
+        
+        # keep track of number of steps
+        self.global_step = tf.Variable(0, dtype=tf.int32, trainable=False, name='global_step')
+        
+        self.X_train = X_train
+        self.Y_train = Y_train
+        self.X_test = X_test
+        self.Y_test = Y_test
+        
+        self.n_inputs = X_train.shape[0]
+        self.n_features = X_train.shape[1]
+        self.n_neurons_layer1 = n_neurons_layer1
+        self.n_neurons_layer2 = n_neurons_layer2
+        self.n_categories = n_categories
+        
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self.iterations = self.n_inputs // self.batch_size
+        self.eta = eta
+        self.lmbd = lmbd
+        
+        # build network piece by piece
+        # name scopes (with) are used to enforce creation of new variables
+        # https://www.tensorflow.org/guide/variables
+        self.create_placeholders()
+        self.create_DNN()
+        self.create_loss()
+        self.create_optimiser()
+        self.create_accuracy()
+    
+    def create_placeholders(self):
+        # placeholders are fine here, but "Datasets" are the preferred method
+        # of streaming data into a model
+        with tf.name_scope('data'):
+            self.X = tf.placeholder(tf.float32, shape=(None, self.n_features), name='X_data')
+            self.Y = tf.placeholder(tf.float32, shape=(None, self.n_categories), name='Y_data')
+    
+    def create_DNN(self):
+        with tf.name_scope('DNN'):
+            # the weights are stored to calculate regularization loss later
+            
+            # Fully connected layer 1
+            self.W_fc1 = self.weight_variable([self.n_features, self.n_neurons_layer1], name='fc1', dtype=tf.float32)
+            b_fc1 = self.bias_variable([self.n_neurons_layer1], name='fc1', dtype=tf.float32)
+            a_fc1 = tf.nn.sigmoid(tf.matmul(self.X, self.W_fc1) + b_fc1)
+            
+            # Fully connected layer 2
+            self.W_fc2 = self.weight_variable([self.n_neurons_layer1, self.n_neurons_layer2], name='fc2', dtype=tf.float32)
+            b_fc2 = self.bias_variable([self.n_neurons_layer2], name='fc2', dtype=tf.float32)
+            a_fc2 = tf.nn.sigmoid(tf.matmul(a_fc1, self.W_fc2) + b_fc2)
+            
+            # Output layer
+            self.W_out = self.weight_variable([self.n_neurons_layer2, self.n_categories], name='out', dtype=tf.float32)
+            b_out = self.bias_variable([self.n_categories], name='out', dtype=tf.float32)
+            self.z_out = tf.matmul(a_fc2, self.W_out) + b_out
+    
+    def create_loss(self):
+        with tf.name_scope('loss'):
+            softmax_loss = tf.reduce_mean(tf.nn.softmax_cross_entropy_with_logits_v2(labels=self.Y, logits=self.z_out))
+            
+            regularizer_loss_fc1 = tf.nn.l2_loss(self.W_fc1)
+            regularizer_loss_fc2 = tf.nn.l2_loss(self.W_fc2)
+            regularizer_loss_out = tf.nn.l2_loss(self.W_out)
+            regularizer_loss = self.lmbd*(regularizer_loss_fc1 + regularizer_loss_fc2 + regularizer_loss_out)
+            
+            self.loss = softmax_loss + regularizer_loss
+
+    def create_accuracy(self):
+        with tf.name_scope('accuracy'):
+            probabilities = tf.nn.softmax(self.z_out)
+            predictions = tf.argmax(probabilities, axis=1)
+            labels = tf.argmax(self.Y, axis=1)
+            
+            correct_predictions = tf.equal(predictions, labels)
+            correct_predictions = tf.cast(correct_predictions, tf.float32)
+            self.accuracy = tf.reduce_mean(correct_predictions)
+    
+    def create_optimiser(self):
+        with tf.name_scope('optimizer'):
+            self.optimizer = tf.train.GradientDescentOptimizer(learning_rate=self.eta).minimize(self.loss, global_step=self.global_step)
+            
+    def weight_variable(self, shape, name='', dtype=tf.float32):
+        initial = tf.truncated_normal(shape, stddev=0.1)
+        return tf.Variable(initial, name=name, dtype=dtype)
+    
+    def bias_variable(self, shape, name='', dtype=tf.float32):
+        initial = tf.constant(0.1, shape=shape)
+        return tf.Variable(initial, name=name, dtype=dtype)
+    
+    def fit(self):
+        data_indices = np.arange(self.n_inputs)
+
+        with tf.Session() as sess:
+            sess.run(tf.global_variables_initializer())
+            for i in range(self.epochs):
+                for j in range(self.iterations):
+                    chosen_datapoints = np.random.choice(data_indices, size=self.batch_size, replace=False)
+                    batch_X, batch_Y = self.X_train[chosen_datapoints], self.Y_train[chosen_datapoints]
+            
+                    sess.run([DNN.loss, DNN.optimizer],
+                        feed_dict={DNN.X: batch_X,
+                                   DNN.Y: batch_Y})
+                    accuracy = sess.run(DNN.accuracy,
+                        feed_dict={DNN.X: batch_X,
+                                   DNN.Y: batch_Y})
+                    step = sess.run(DNN.global_step)
+    
+            self.train_loss, self.train_accuracy = sess.run([DNN.loss, DNN.accuracy],
+                feed_dict={DNN.X: self.X_train,
+                           DNN.Y: self.Y_train})
+        
+            self.test_loss, self.test_accuracy = sess.run([DNN.loss, DNN.accuracy],
+                feed_dict={DNN.X: self.X_test,
+                           DNN.Y: self.Y_test})
+
    
+
    
+
+
+
    
+
    Optimizing and using gradient descent 
    
+
+
    
+
+
+
    epochs = 100
+batch_size = 100
+n_neurons_layer1 = 100
+n_neurons_layer2 = 50
+n_categories = 10
+eta_vals = np.logspace(-5, 1, 7)
+lmbd_vals = np.logspace(-5, 1, 7)
+
    
+
    
+
+
+
    DNN_tf = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+        
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        DNN = NeuralNetworkTensorflow(X_train, Y_train, X_test, Y_test,
+                                      n_neurons_layer1, n_neurons_layer2, n_categories,
+                                      epochs=epochs, batch_size=batch_size, eta=eta, lmbd=lmbd)
+        DNN.fit()
+        
+        DNN_tf[i][j] = DNN
+        
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % DNN.test_accuracy)
+        print()
+
    
+
    
+
+
+
    # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        DNN = DNN_tf[i][j]
+
+        train_accuracy[i][j] = DNN.train_accuracy
+        test_accuracy[i][j] = DNN.test_accuracy
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
    
+
    
+
+
+
    # optional
+# we can use log files to visualize our graph in Tensorboard
+writer = tf.summary.FileWriter('logs/')
+writer.add_graph(tf.get_default_graph())
+
    
+
    
+
+
+
    
+
    Using Keras 
    
+
+
    
+Keras is a high level neural network
+that supports Tensorflow, CTNK and Theano as backends.  
+If you have Tensorflow installed Keras is available through the tf.keras module.  
+If you have Anaconda installed you may run the following command
+
    
+
+
+
    conda install keras
+
    
+
    
+Alternatively, if you have Tensorflow or one of the other supported backends install you may use the pip package manager:
+
+
    
+
+
+
    pip3 install keras
+
    
+
    
+or look up the instructions here.
+
+
    
+
+
+
    from keras.models import Sequential
+from keras.layers import Dense
+from keras.regularizers import l2
+from keras.optimizers import SGD
+
+def create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories, eta, lmbd):
+    model = Sequential()
+    model.add(Dense(n_neurons_layer1, activation='sigmoid', kernel_regularizer=l2(lmbd)))
+    model.add(Dense(n_neurons_layer2, activation='sigmoid', kernel_regularizer=l2(lmbd)))
+    model.add(Dense(n_categories, activation='softmax'))
+    
+    sgd = SGD(lr=eta)
+    model.compile(loss='categorical_crossentropy', optimizer=sgd, metrics=['accuracy'])
+    
+    return model
+
    
+
    
+
+
+
    DNN_keras = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+        
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        DNN = create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories,
+                                         eta=eta, lmbd=lmbd)
+        DNN.fit(X_train, Y_train, epochs=epochs, batch_size=batch_size, verbose=0)
+        scores = DNN.evaluate(X_test, Y_test)
+        
+        DNN_keras[i][j] = DNN
+        
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % scores[1])
+        print()
+
    
+
    
+
+
+
    # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        DNN = DNN_keras[i][j]
+
+        train_accuracy[i][j] = DNN.evaluate(X_train, Y_train)[1]
+        test_accuracy[i][j] = DNN.evaluate(X_test, Y_test)[1]
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
    
+
    
+
+
+
    
+
    Which activation function should I use? 
    
+
+
    
+The Back propagation algorithm we derived above works by going from
+the output layer to the input layer, propagating the error gradient on
+the way. Once the algorithm has computed the gradient of the cost
+function with regards to each parameter in the network, it uses these
+gradients to update each parameter with a Gradient Descent (GD) step.
+
+
    
+Unfortunately for us, the gradients often get smaller and smaller as the
+algorithm progresses down to the first hidden layers. As a result, the
+GD update leaves the lower layer connection weights
+virtually unchanged, and training never converges to a good
+solution. This is known in the literature as 
+the vanishing gradients problem.
+
+
    
+In other cases, the opposite can happen, namely the the gradients can grow bigger and
+bigger. The result is that many of the layers get large updates of the 
+weights the
+algorithm diverges. This is the exploding gradients problem, which is
+mostly encountered in recurrent neural networks. More generally, deep
+neural networks suffer from unstable gradients, different layers may
+learn at widely different speeds
+
    
+
+
+
    
+
    Is the Logistic activation function (Sigmoid)  our choice? 
    
+
+
    
+Although this unfortunate behavior has been empirically observed for
+quite a while (it was one of the reasons why deep neural networks were
+mostly abandoned for a long time), it is only around 2010 that
+significant progress was made in understanding it.
+
+
    
+A paper titled Understanding the Difficulty of Training Deep
+Feedforward Neural Networks by Xavier Glorot and Yoshua Bengio found that
+the problems with the popular logistic
+sigmoid activation function and the weight initialization technique
+that was most popular at the time, namely random initialization using
+a normal distribution with a mean of 0 and a standard deviation of
+1.
+
+
    
+They showed that with this activation function and this
+initialization scheme, the variance of the outputs of each layer is
+much greater than the variance of its inputs. Going forward in the
+network, the variance keeps increasing after each layer until the
+activation function saturates at the top layers. This is actually made
+worse by the fact that the logistic function has a mean of 0.5, not 0
+(the hyperbolic tangent function has a mean of 0 and behaves slightly
+better than the logistic function in deep networks).
+
    
+
+
+
    
+
    The derivative of the Logistic funtion 
    
+
+
    
+Looking at the logistic activation function, when inputs become large
+(negative or positive), the function saturates at 0 or 1, with a
+derivative extremely close to 0. Thus when backpropagation kicks in,
+it has virtually no gradient to propagate back through the network,
+and what little gradient exists keeps getting diluted as
+backpropagation progresses down through the top layers, so there is
+really nothing left for the lower layers.
+
+
    
+In their paper, Glorot and Bengio propose a way to significantly
+alleviate this problem. We need the signal to flow properly in both
+directions: in the forward direction when making predictions, and in
+the reverse direction when backpropagating gradients. We don’t want
+the signal to die out, nor do we want it to explode and saturate. For
+the signal to flow properly, the authors argue that we need the
+variance of the outputs of each layer to be equal to the variance of
+its inputs, and we also need the gradients to have equal variance
+before and after flowing through a layer in the reverse direction.
+
+
    
+One of the insights in the 2010 paper by Glorot and Bengio was that
+the vanishing/exploding gradients problems were in part due to a poor
+choice of activation function. Until then most people had assumed that
+if Nature had chosen to use roughly sigmoid activation functions in
+biological neurons, they must be an excellent choice. But it turns out
+that other activation functions behave much better in deep neural
+networks, in particular the ReLU activation function, mostly because
+it does not saturate for positive values (and also because it is quite
+fast to compute).
+
    
+
+
+
    
+
    The RELU function family 
    
+
+
    
+The ReLU activation function suffers from a problem known as the dying
+ReLUs: during training, some neurons effectively die, meaning they
+stop outputting anything other than 0.
+
+
    
+In some cases, you may find that half of your network’s neurons are
+dead, especially if you used a large learning rate. During training,
+if a neuron’s weights get updated such that the weighted sum of the
+neuron’s inputs is negative, it will start outputting 0. When this
+happen, the neuron is unlikely to come back to life since the gradient
+of the ReLU function is 0 when its input is negative.
+
+
    
+To solve this problem, nowadays practitioners use a  variant of the ReLU
+function, such as the leaky ReLU discussed above or the so-called
+exponential linear unit (ELU) function
+
+
     
    
+$$
+ELU(z) = \left\{\begin{array}{cc} \alpha\left( \exp{(z)}-1\right) & z < 0,\\  z & z \ge 0.\end{array}\right. 
+$$
+
     
    
+
    
+
+
+
    
+
    Which activation function should we use? 
    
+
+
    
+In general it seems that the ELU activation function is better than
+the leaky ReLU function (and its variants), which is better than
+ReLU. ReLU performs better than \( \tanh \) which in turn performs better
+than the logistic function.
+
+
    
+If runtime
+performance is an issue, then you may opt for the  leaky ReLU function  over the 
+ELU function If you don’t
+want to tweak yet another hyperparameter, you may just use the default
+\( \alpha \) of \( 0.01 \) for the leaky ReLU, and \( 1 \) for ELU. If you have
+spare time and computing power, you can use cross-validation or
+bootstrap to evaluate other activation functions.
+
    
+
+
+
    
+
    A top-down perspective on Neural networks 
    
+
+
    
+The first thing we would like to do is divide the data into two or three
+parts. A training set, a validation or dev (development) set, and a
+test set. The test set is the data on which we want to make
+predictions. The dev set is a subset of the training data we use to
+check how well we are doing out-of-sample, after training the model on
+the training dataset. We use the validation error as a proxy for the
+test error in order to make tweaks to our model. It is crucial that we
+do not use any of the test data to train the algorithm. This is a
+cardinal sin in ML. Then:
+
+
      
+
    •  Estimate optimal error rate
      • 
+
    •  Minimize underfitting (bias) on training data set.
      • 
+
    •  Make sure you are not overfitting.
      • 
+
    
+
    
+
+If the validation and test sets are drawn from the same distributions,
+then a good performance on the validation set should lead to similarly
+good performance on the test set.
+
+
    
+However, sometimes
+the training data and test data differ in subtle ways because, for
+example, they are collected using slightly different methods, or
+because it is cheaper to collect data in one way versus another. In
+this case, there can be a mismatch between the training and test
+data. This can lead to the neural network overfitting these small
+differences between the test and training sets, and a poor performance
+on the test set despite having a good performance on the validation
+set. To rectify this, Andrew Ng suggests making two validation or dev
+sets, one constructed from the training data and one constructed from
+the test data. The difference between the performance of the algorithm
+on these two validation sets quantifies the train-test mismatch. This
+can serve as another important diagnostic when using DNNs for
+supervised learning.
+
    
+
+
+
    
+
    Limitations of supervised learning with deep networks 
    
+
+
    
+Like all statistical methods, supervised learning using neural
+networks has important limitations. This is especially important when
+one seeks to apply these methods, especially to physics problems. Like
+all tools, DNNs are not a universal solution. Often, the same or
+better performance on a task can be achieved by using a few
+hand-engineered features (or even a collection of random
+features).
+
+
    
+Here we list some of the important limitations of supervised neural network based models. 
+
+
      
+
    •  Need labeled data. All supervised learning methods, DNNs for supervised learning require labeled data. Often, labeled data is harder to acquire than unlabeled data (e.g. one must pay for human experts to label images).
      • 
+
    •  Supervised neural networks are extremely data intensive. DNNs are data hungry. They perform best when data is plentiful. This is doubly so for supervised methods where the data must also be labeled. The utility of DNNs is extremely limited if data is hard to acquire or the datasets are small (hundreds to a few thousand samples). In this case, the performance of other methods that utilize hand-engineered features can exceed that of DNNs.
      • 
+
    •  Homogeneous data. Almost all DNNs deal with homogeneous data of one type. It is very hard to design architectures that mix and match data types (i.e. some continuous variables, some discrete variables, some time series). In applications beyond images, video, and language, this is often what is required. In contrast, ensemble models like random forests or gradient-boosted trees have no difficulty handling mixed data types.
      • 
+
    •  Many problems are not about prediction. In natural science we are often interested in learning something about the underlying distribution that generates the data. In this case, it is often difficult to cast these ideas in a supervised learning setting. While the problems are related, it is possible to make good predictions with a wrong model. The model might or might not be useful for understanding the underlying science.
      • 
+
    
+
    
+
+Some of these remarks are particular to DNNs, others are shared by all supervised learning methods. This motivates the use of unsupervised methods which in part circumvent these problems.
+
    
+
+
+
    
+
    Convolutional Neural Networks (recognizing images) 
    
 
 
    
 Convolutional neural networks (CNNs) were developed during the last
@@ -198,7 +2171,7 @@ Another good read is the article here Regular NNs don’t scale well to full images 
+
    Regular NNs don’t scale well to full images 
    
 
 
    
 As an example, consider
@@ -226,7 +2199,7 @@ would quickly lead to possible overfitting.
 
 
 
    
-
    3D volumes of neurons 
    
+
    3D volumes of neurons 
    
 
 
    
 Convolutional Neural Networks take advantage of the fact that the
@@ -266,7 +2239,7 @@ dimension.
 
 
 
    
-
    Layers used to build CNNs 
    
+
    Layers used to build CNNs 
    
 
 
    
 A simple CNN is a sequence of layers, and every layer of a CNN
@@ -290,7 +2263,7 @@ A simple CNN for image classification could have the architecture:
 
 
 
    
-
    Transforming images 
    
+
    Transforming images 
    
 
 
    
 CNNs transform the original image layer by layer from the original
@@ -309,7 +2282,7 @@ are consistent with the labels in the training set for each image.
 
 
 
    
-
    CNNs in brief 
    
+
    CNNs in brief 
    
 
 
    
 In summary:
@@ -331,7 +2304,7 @@ and the slides of 
-
    CNNs in more detail, building convolutional neural networks in Tensorflow and Keras 
    
+
    CNNs in more detail, building convolutional neural networks in Tensorflow and Keras 
    
 
 
    
 As discussed above, CNNs are neural networks built from the assumption that the inputs
@@ -347,7 +2320,7 @@ matrices, typically 1 for each color dimension (Red, Green, Blue).
 
 
 
    
-
    Setting it up 
    
+
    Setting it up 
    
 
 
    
 It means that to represent the entire
@@ -362,7 +2335,7 @@ $$
 
 
 
    
-
    The MNIST dataset again 
    
+
    The MNIST dataset again 
    
 
 
    
 The MNIST dataset consists of grayscale images with a pixel size of
@@ -380,7 +2353,7 @@ single neuron in the first hidden layer.
 
 
 
    
-
    Strong correlations 
    
+
    Strong correlations 
    
 Images typically have strong local correlations, meaning that a small
 part of the image varies little from its neighboring regions. If for
 example we have an image of a blue car, we can roughly assume that a
@@ -396,7 +2369,7 @@ fixed, and known as a     
-
    Layers of a CNN 
    
+
    Layers of a CNN 
    
 The layers of a convolutional neural network arrange neurons in 3D: width, height and depth.  
 The input image is typically a square matrix of depth 3.
 
@@ -418,7 +2391,7 @@ layer.
 
 
 
    
-
    Systematic reduction 
    
+
    Systematic reduction 
    
 
 
    
 By systematically reducing the size of the input volume, through
@@ -433,7 +2406,7 @@ classification.
 
 
 
    
-
    Prerequisites: Collect and pre-process data 
    
+
    Prerequisites: Collect and pre-process data 
    
 
    
 
 
@@ -462,8 +2435,8 @@ labels = digits.target
 # our images are grayscale so they should have a depth of 1
 inputs = inputs[:,:,:,np.newaxis]
 
-print("inputs = (n_inputs, pixel_width, pixel_height, depth) = " + str(inputs.shape))
-print("labels = (n_inputs) = " + str(labels.shape))
+print("inputs = (n_inputs, pixel_width, pixel_height, depth) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
 
 
 # choose some random images to display
@@ -482,7 +2455,7 @@ plt.show()
 
 
 
    
-
    Importing Keras and Tensorflow 
    
+
    Importing Keras and Tensorflow 
    
 
    
 
 
@@ -503,7 +2476,7 @@ X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=t
 
 
 
    
-
    Using TensorFlow backend 
    
+
    Using TensorFlow backend 
    
 
 
    
 We need to define model and architecture and choose cost function and optmizer.
@@ -652,7 +2625,7 @@ class ConvolutionalNeuralNetworkTensorflow:
 
 
 
    
-
    Train the model 
    
+
    Train the model 
    
 
 
    
 We need now to train the model, evaluate it and test its performance on test data, and eventually include hyperparameters.
@@ -677,10 +2650,10 @@ CNN_tf = np.zeros((len(eta_vals), print("Learning rate = ", eta)
-        print("Lambda = ", lmbd)
-        print("Test accuracy: %.3f" % CNN.test_accuracy)
-        print()
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % CNN.test_accuracy)
+        print()
             
         CNN_tf[i][j] = CNN
 
    
@@ -688,7 +2661,7 @@ CNN_tf = np.zeros((len(eta_vals), 
-
    Visualizing the results 
    
+
    Visualizing the results 
    
 
 
    
 
@@ -711,14 +2684,14 @@ test_accuracy = np.zeros((len(eta_vals), 10, 10))
-sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
 ax.set_title("Training Accuracy")
 ax.set_ylabel("$\eta$")
 ax.set_xlabel("$\lambda$")
 plt.show()
 
 fig, ax = plt.subplots(figsize = (10, 10))
-sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
 ax.set_title("Test Accuracy")
 ax.set_ylabel("$\eta$")
 ax.set_xlabel("$\lambda$")
@@ -728,7 +2701,7 @@ plt.show()
 
 
 
    
-
    Running with Keras 
    
+
    Running with Keras 
    
 
 
    
 
@@ -772,7 +2745,7 @@ lmbd_vals = np.logspace(-5, Final part 
+
    Final part 
    
 
 
    
 
@@ -789,16 +2762,16 @@ lmbd_vals = np.logspace(-5, print("Learning rate = ", eta)
-        print("Lambda = ", lmbd)
-        print("Test accuracy: %.3f" % scores[1])
-        print()
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % scores[1])
+        print()
 
    
 
 
 
 
    
-
    Final visualization 
    
+
    Final visualization 
    
 
 
    
 
@@ -838,7 +2811,7 @@ plt.show()
 
 
 
    
-
    Fun links 
    
+
    Fun links 
    
 
 
      
 
    1.  Self-Driving cars using a convolutional neural network
      2. 
diff --git a/doc/pub/week41/html/week41-solarized.html b/doc/pub/week41/html/week41-solarized.html
index 1a169875d..164fa7351 100644
--- a/doc/pub/week41/html/week41-solarized.html
+++ b/doc/pub/week41/html/week41-solarized.html
@@ -26,6 +26,32 @@ pre {
   border: 0pt solid #93a1a1;
   box-shadow: none;
 }
+.alert-text-small   { font-size: 80%;  }
+.alert-text-large   { font-size: 130%; }
+.alert-text-normal  { font-size: 90%;  }
+.alert {
+  padding:8px 35px 8px 14px; margin-bottom:18px;
+  text-shadow:0 1px 0 rgba(255,255,255,0.5);
+  border:1px solid #93a1a1;
+  border-radius: 4px;
+  -webkit-border-radius: 4px;
+  -moz-border-radius: 4px;
+  color: #555;
+  background-color: #eee8d5;
+  background-position: 10px 5px;
+  background-repeat: no-repeat;
+  background-size: 38px;
+  padding-left: 55px;
+  width: 75%;
+ }
+.alert-block {padding-top:14px; padding-bottom:14px}
+.alert-block > p, .alert-block > ul {margin-bottom:1em}
+.alert li {margin-top: 1em}
+.alert-block p+p {margin-top:5px}
+.alert-notice { background-image: url(https://cdn.rawgit.com/hplgit/doconce/master/bundled/html_images/small_yellow_notice.png); }
+.alert-summary  { background-image:url(https://cdn.rawgit.com/hplgit/doconce/master/bundled/html_images/small_yellow_summary.png); }
+.alert-warning { background-image: url(https://cdn.rawgit.com/hplgit/doconce/master/bundled/html_images/small_yellow_warning.png); }
+.alert-question {background-image:url(https://cdn.rawgit.com/hplgit/doconce/master/bundled/html_images/small_yellow_question.png); }
 
 div { text-align: justify; text-justify: inter-word; }
 
@@ -35,40 +61,98 @@ div { text-align: justify; text-justify: inter-word; }
 
 
 
 
@@ -110,12 +194,1860 @@ MathJax.Hub.Config({
 
      [2] Department of Physics and Astronomy and National Superconducting Cyclotron Laboratory, Michigan State University
      
 
      
 
      
-
      Sep 16, 2020
       
+
      Oct 5, 2020
       
 
      
 
      
 









      
 
-
      Convolutional Neural Networks (recognizing images) 
      
+
      Plan for week 40 
      
+
+
        
+
      •  Thursday: Building our own Feed-forward Neural Network
        • 
+
      •  Friday: Playing around with our own Feed-forward Neural Network and introduction to TensorFlow. Start convolutional Neural Networks.
        • 
+
      
+
+Reading suggestions for both days: Aurelien Geron's chapters 10-11 and Hastie et al chapter 11.
+
+
      
+









      
+
+
      Overview video for week 41 
      
+
+
      
+"Overview Video, from Stochastic Gradient methods to Neural Networks":"https://www.uio.no/studier/emner/matnat/fys/FYS-STK3155/h20\
+/forelesningsvideoer/OverviewWeek41.mp4?vrtx=view-as-webpage"
+
+
      
+









      
+
+
      Setting up the Back propagation algorithm 
      
+
+
      
+The four equations  provide us with a way of computing the gradient of the cost function. Let us write this out in the form of an algorithm.
+
+
      
+
      
+
+
      
+First, we set up the input data \( \hat{x} \) and the activations
+\( \hat{z}_1 \) of the input layer and compute the activation function and
+the pertinent outputs \( \hat{a}^1 \).
+
      
+
+
+
      
+
      
+
+
      
+Secondly, we perform then the feed forward till we reach the output
+layer and compute all \( \hat{z}_l \) of the input layer and compute the
+activation function and the pertinent outputs \( \hat{a}^l \) for
+\( l=2,3,\dots,L \).
+
      
+
+
+
      
+
      
+
+
      
+Thereafter we compute the ouput error \( \hat{\delta}^L \) by computing all
+$$
+\delta_j^L = f'(z_j^L)\frac{\partial {\cal C}}{\partial (a_j^L)}.
+$$
+
      
+
+
+
      
+
      
+
+
      
+Then we compute the back propagate error for each \( l=L-1,L-2,\dots,2 \) as
+$$
+\delta_j^l = \sum_k \delta_k^{l+1}w_{kj}^{l+1}f'(z_j^l).
+$$
+
      
+
+
+
      
+
      
+
+
      
+Finally, we update the weights and the biases using gradient descent for each \( l=L-1,L-2,\dots,2 \) and update the weights and biases according to the rules
+$$
+w_{jk}^l\leftarrow  = w_{jk}^l- \eta \delta_j^la_k^{l-1},
+$$
+
+
+$$
+b_j^l \leftarrow b_j^l-\eta \frac{\partial {\cal C}}{\partial b_j^l}=b_j^l-\eta \delta_j^l,
+$$
+
      
+
+
+
      
+The parameter \( \eta \) is the learning parameter discussed in connection with the gradient descent methods.
+Here it is convenient to use stochastic gradient descent (see the examples below) with mini-batches with an outer loop that steps through multiple epochs of training.
+
+
      
+
+
+
      Setting up a Multi-layer perceptron model for classification  
      
+
+
      
+We are now gong to develop an example based on the MNIST data
+base. This is a classification problem and we need to use our
+cross-entropy function we discussed in connection with logistic
+regression. The cross-entropy defines our cost function for the
+classificaton problems with neural networks.
+
+
      
+In binary classification with two classes \( (0, 1) \) we define the
+logistic/sigmoid function as the probability that a particular input
+is in class \( 0 \) or \( 1 \).  This is possible because the logistic
+function takes any input from the real numbers and inputs a number
+between 0 and 1, and can therefore be interpreted as a probability. It
+also has other nice properties, such as a derivative that is simple to
+calculate.
+
+
      
+For an input \( \boldsymbol{a} \) from the hidden layer, the probability that the input \( \boldsymbol{x} \)
+is in class 0 or 1 is just. We let \( \theta \) represent the unknown weights and biases to be adjusted by our equations). The variable \( x \)
+represents our activation values \( z \). We have
+$$
+P(y = 0 \mid \hat{x}, \hat{\theta}) = \frac{1}{1 + \exp{(- \hat{x}})} ,
+$$
+
+and
+$$
+P(y = 1 \mid \hat{x}, \hat{\theta}) = 1 - P(y = 0 \mid \hat{x}, \hat{\theta}) ,
+$$
+
+
      
+where \( y \in \{0, 1\} \)  and \( \hat{\theta} \) represents the weights and biases
+of our network.
+
+
      
+









      
+
+
      Defining the cost function 
      
+
+
      
+Our cost function is given as (see the Logistic regression lectures)
+$$
+\mathcal{C}(\hat{\theta}) = - \ln P(\mathcal{D} \mid \hat{\theta}) = - \sum_{i=1}^n
+y_i \ln[P(y_i = 0)] + (1 - y_i) \ln [1 - P(y_i = 0)] = \sum_{i=1}^n \mathcal{L}_i(\hat{\theta}) .
+$$
+
+
      
+This last equality means that we can interpret our cost function as a sum over the loss function
+for each point in the dataset \( \mathcal{L}_i(\hat{\theta}) \).  
+The negative sign is just so that we can think about our algorithm as minimizing a positive number, rather
+than maximizing a negative number.
+
+
      
+In multiclass classification it is common to treat each integer label as a so called one-hot vector:
+
+
      
+\( y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) , \) and
+
+
      
+\( y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) , \)
+
+
      
+i.e. a binary bit string of length \( C \), where \( C = 10 \) is the number of classes in the MNIST dataset (numbers from \( 0 \) to \( 9 \))..
+
+
      
+If \( \hat{x}_i \) is the \( i \)-th input (image), \( y_{ic} \) refers to the \( c \)-th component of the \( i \)-th
+output vector \( \hat{y}_i \).  
+The probability of \( \hat{x}_i \) being in class \( c \) will be given by the softmax function:  
+
+$$
+P(y_{ic} = 1 \mid \hat{x}_i, \hat{\theta}) = \frac{\exp{((\hat{a}_i^{hidden})^T \hat{w}_c)}}
+{\sum_{c'=0}^{C-1} \exp{((\hat{a}_i^{hidden})^T \hat{w}_{c'})}} ,
+$$
+
+
      
+which reduces to the logistic function in the binary case.  
+The likelihood of this \( C \)-class classifier
+is now given as:  
+
+$$
+P(\mathcal{D} \mid \hat{\theta}) = \prod_{i=1}^n \prod_{c=0}^{C-1} [P(y_{ic} = 1)]^{y_{ic}} .
+$$
+
+Again we take the negative log-likelihood to define our cost function:  
+
+$$
+\mathcal{C}(\hat{\theta}) = - \log{P(\mathcal{D} \mid \hat{\theta})}.
+$$
+
+See the logistic regression lectures for a full definition of the cost function.
+
+
      
+The back propagation equations need now only a small change, namely the definition of a new cost function. We are thus ready to use the same equations as before!
+
+
      
+









      
+
+
      Example: binary classification problem 
      
+
+
      
+As an example of the above, relevant for project 2 as well, let us consider a binary class. As discussed in our logistic regression lectures, we defined a cost function in terms of the parameters \( \beta \) as
+$$
+\mathcal{C}(\hat{\beta}) = - \sum_{i=1}^n \left(y_i\log{p(y_i \vert x_i,\hat{\beta})}+(1-y_i)\log{1-p(y_i \vert x_i,\hat{\beta})}\right),
+$$
+
+where we had defined the logistic (sigmoid) function
+$$
+p(y_i =1\vert x_i,\hat{\beta})=\frac{\exp{(\beta_0+\beta_1 x_i)}}{1+\exp{(\beta_0+\beta_1 x_i)}},
+$$
+
+and
+$$
+p(y_i =0\vert x_i,\hat{\beta})=1-p(y_i =1\vert x_i,\hat{\beta}).
+$$
+
+The parameters \( \hat{\beta} \) were defined using a minimization method like gradient descent or Newton-Raphson's method.
+
+
      
+Now we replace \( x_i \) with the activation \( z_i^l \) for a given layer \( l \) and the outputs as \( y_i=a_i^l=f(z_i^l) \), with \( z_i^l \) now being a function of the weights \( w_{ij}^l \) and biases \( b_i^l \). 
+We have then
+$$
+a_i^l = y_i = \frac{\exp{(z_i^l)}}{1+\exp{(z_i^l)}},
+$$
+
+with 
+$$
+z_i^l = \sum_{j}w_{ij}^l a_j^{l-1}+b_i^l,
+$$
+
+where the superscript \( l-1 \) indicates that these are the outputs from layer \( l-1 \).
+Our cost function at the final layer \( l=L \) is now
+$$
+\mathcal{C}(\hat{W}) = - \sum_{i=1}^n \left(t_i\log{a_i^L}+(1-t_i)\log{(1-a_i^L)}\right),
+$$
+
+where we have defined the targets \( t_i \). The derivatives of the cost function with respect to the output \( a_i^L \) are then easily calculated and we get
+$$
+\frac{\partial \mathcal{C}(\hat{W})}{\partial a_i^L} = \frac{a_i^L-t_i}{a_i^L(1-a_i^L)}. 
+$$
+
+In case we use another activation function than the logistic one, we need to evaluate other derivatives.
+
+
      
+









      
+
+
      The Softmax function 
      
+In case we employ the more general case given by the Softmax equation, we need to evaluate the derivative of the activation function with respect to the activation \( z_i^l \), that is we need
+$$
+\frac{\partial f(z_i^l)}{\partial w_{jk}^l} =
+\frac{\partial f(z_i^l)}{\partial z_j^l} \frac{\partial z_j^l}{\partial w_{jk}^l}= \frac{\partial f(z_i^l)}{\partial z_j^l}a_k^{l-1}.
+$$
+
+For the Softmax function we have
+$$
+f(z_i^l) = \frac{\exp{(z_i^l)}}{\sum_{m=1}^K\exp{(z_m^l)}}.
+$$
+
+Its derivative with respect to \( z_j^l \) gives 
+$$
+\frac{\partial f(z_i^l)}{\partial z_j^l}= f(z_i^l)\left(\delta_{ij}-f(z_j^l)\right), 
+$$
+
+which in case of the simply binary model reduces to  having \( i=j \).
+
+
      
+
+
+
      Developing a code for doing neural networks with back propagation 
      
+
+
      
+One can identify a set of key steps when using neural networks to solve supervised learning problems:  
+
+
        
+
      1.  Collect and pre-process data
        2.   
+
      2.  Define model and architecture
        3.   
+
      3.  Choose cost function and optimizer
        4.   
+
      4.  Train the model
        5.   
+
      5.  Evaluate model performance on test data
        6.   
+
      6.  Adjust hyperparameters (if necessary, network architecture)
        7. 
+
      
+
+









      
+
+
      Collect and pre-process data 
      
+
+
      
+Here we will be using the MNIST dataset, which is readily available through the scikit-learn
+package. You may also find it for example here.  
+The MNIST (Modified National Institute of Standards and Technology) database is a large database
+of handwritten digits that is commonly used for training various image processing systems.  
+The MNIST dataset consists of 70 000 images of size \( 28\times 28 \) pixels, each labeled from 0 to 9.  
+The scikit-learn dataset we will use consists of a selection of 1797 images of size \( 8\times 8 \) collected and processed from this database.
+
+
      
+To feed data into a feed-forward neural network we need to represent
+the inputs as a design/feature matrix \( X = (n_{inputs}, n_{features}) \).  Each
+row represents an input, in this case a handwritten digit, and
+each column represents a feature, in this case a pixel.  The
+correct answers, also known as labels or targets are
+represented as a 1D array of integers 
+\( Y = (n_{inputs}) = (5, 3, 1, 8,...) \).
+
+
      
+As an example, say we want to build a neural network using supervised learning to predict Body-Mass Index (BMI) from
+measurements of height (in m)  
+and weight (in kg). If we have measurements of 5 people the design/feature matrix could be for example:  
+
+$$ X = \begin{bmatrix}
+1.85 & 81\\
+1.71 & 65\\
+1.95 & 103\\
+1.55 & 42\\
+1.63 & 56
+\end{bmatrix} ,$$
+
+
      
+and the targets would be:  
+
+$$ Y = (23.7, 22.2, 27.1, 17.5, 21.1) $$
+
+
      
+Since each input image is a 2D matrix, we need to flatten the image
+(i.e. "unravel" the 2D matrix into a 1D array) to turn the data into a
+design/feature matrix. This means we lose all spatial information in the
+image, such as locality and translational invariance. More complicated
+architectures such as Convolutional Neural Networks can take advantage
+of such information, and are most commonly applied when analyzing
+images.
+
+
      
+
+
+
      # import necessary packages
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn import datasets
+
+
+# ensure the same random numbers appear every time
+np.random.seed(0)
+
+# display images in notebook
+%matplotlib inline
+plt.rcParams['figure.figsize'] = (12,12)
+
+
+# download MNIST dataset
+digits = datasets.load_digits()
+
+# define inputs and labels
+inputs = digits.images
+labels = digits.target
+
+print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
+
+
+# flatten the image
+# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64
+n_inputs = len(inputs)
+inputs = inputs.reshape(n_inputs, -1)
+print("X = (n_inputs, n_features) = " + str(inputs.shape))
+
+
+# choose some random images to display
+indices = np.arange(n_inputs)
+random_indices = np.random.choice(indices, size=5)
+
+for i, image in enumerate(digits.images[random_indices]):
+    plt.subplot(1, 5, i+1)
+    plt.axis('off')
+    plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')
+    plt.title("Label: %d" % digits.target[random_indices[i]])
+plt.show()
+
      
+
      
+









      
+
+
      Train and test datasets 
      
+
+
      
+Performing analysis before partitioning the dataset is a major error, that can lead to incorrect conclusions.
+
+
      
+We will reserve \( 80 \% \) of our dataset for training and \( 20 \% \) for testing.
+
+
      
+It is important that the train and test datasets are drawn randomly from our dataset, to ensure
+no bias in the sampling.  
+Say you are taking measurements of weather data to predict the weather in the coming 5 days.
+You don't want to train your model on measurements taken from the hours 00.00 to 12.00, and then test it on data
+collected from 12.00 to 24.00.
+
+
      
+
+
+
      from sklearn.model_selection import train_test_split
+
+# one-liner from scikit-learn library
+train_size = 0.8
+test_size = 1 - train_size
+X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,
+                                                    test_size=test_size)
+
+# equivalently in numpy
+def train_test_split_numpy(inputs, labels, train_size, test_size):
+    n_inputs = len(inputs)
+    inputs_shuffled = inputs.copy()
+    labels_shuffled = labels.copy()
+    
+    np.random.shuffle(inputs_shuffled)
+    np.random.shuffle(labels_shuffled)
+    
+    train_end = int(n_inputs*train_size)
+    X_train, X_test = inputs_shuffled[:train_end], inputs_shuffled[train_end:]
+    Y_train, Y_test = labels_shuffled[:train_end], labels_shuffled[train_end:]
+    
+    return X_train, X_test, Y_train, Y_test
+
+#X_train, X_test, Y_train, Y_test = train_test_split_numpy(inputs, labels, train_size, test_size)
+
+print("Number of training images: " + str(len(X_train)))
+print("Number of test images: " + str(len(X_test)))
+
      
+
      
+









      
+
+
      Define model and architecture 
      
+
+
      
+Our simple feed-forward neural network will consist of an input layer, a single hidden layer and an output layer. The activation \( y \) of each neuron is a weighted sum of inputs, passed through an activation function. In case of the simple perceptron model we have 
+
+$$ z = \sum_{i=1}^n w_i a_i ,$$
+
+$$ y = f(z) ,$$
+
+
      
+where \( f \) is the activation function, \( a_i \) represents input from neuron \( i \) in the preceding layer
+and \( w_i \) is the weight to input \( i \).  
+The activation of the neurons in the input layer is just the features (e.g. a pixel value).
+
+
      
+The simplest activation function for a neuron is the Heaviside function:
+
+$$ f(z) = 
+\begin{cases}
+1,  &  z > 0\\
+0,  & \text{otherwise}
+\end{cases}
+$$
+
+
      
+A feed-forward neural network with this activation is known as a perceptron.  
+For a binary classifier (i.e. two classes, 0 or 1, dog or not-dog) we can also use this in our output layer.  
+This activation can be generalized to \( k \) classes (using e.g. the one-against-all strategy), 
+and we call these architectures multiclass perceptrons.
+
+
      
+However, it is now common to use the terms Single Layer Perceptron (SLP) (1 hidden layer) and  
+Multilayer Perceptron (MLP) (2 or more hidden layers) to refer to feed-forward neural networks with any activation function.
+
+
      
+Typical choices for activation functions include the sigmoid function, hyperbolic tangent, and Rectified Linear Unit (ReLU).  
+We will be using the sigmoid function \( \sigma(x) \):  
+
+$$ f(x) = \sigma(x) = \frac{1}{1 + e^{-x}} ,$$
+
+
      
+which is inspired by probability theory (see logistic regression) and was most commonly used until about 2011. See the discussion below concerning other activation functions.
+
+
      
+
+
+
      Layers 
      
+
+
        
+
      •  Input
        •  
+
      
+
+Since each input image has 8x8 = 64 pixels or features, we have an input layer of 64 neurons.  
+
+
        
+
      •  Hidden layer
        • 
+
      
+
+We will use 50 neurons in the hidden layer receiving input from the neurons in the input layer.  
+Since each neuron in the hidden layer is connected to the 64 inputs we have 64x50 = 3200 weights to the hidden layer.  
+
+
        
+
      •  Output
        • 
+
      
+
+If we were building a binary classifier, it would be sufficient with a single neuron in the output layer,
+which could output 0 or 1 according to the Heaviside function. This would be an example of a hard classifier, meaning it outputs the class of the input directly. However, if we are dealing with noisy data it is often beneficial to use a soft classifier, which outputs the probability of being in class 0 or 1.
+
+
      
+For a soft binary classifier, we could use a single neuron and interpret the output as either being the probability of being in class 0 or the probability of being in class 1. Alternatively we could use 2 neurons, and interpret each neuron as the probability of being in each class.
+
+
      
+Since we are doing multiclass classification, with 10 categories, it is natural to use 10 neurons in the output layer. We number the neurons \( j = 0,1,...,9 \). The activation of each output neuron \( j \) will be according to the softmax function:  
+
+$$ P(\text{class \( j \)} \mid \text{input \( \hat{a} \)}) = \frac{\exp{(\hat{a}^T \hat{w}_j)}}
+{\sum_{c=0}^{9} \exp{(\hat{a}^T \hat{w}_c)}} ,$$
+
+
      
+i.e. each neuron \( j \) outputs the probability of being in class \( j \) given an input from the hidden layer \( \hat{a} \), with \( \hat{w}_j \) the weights of neuron \( j \) to the inputs.  
+The denominator is a normalization factor to ensure the outputs (probabilities) sum up to 1.  
+The exponent is just the weighted sum of inputs as before:  
+
+$$ z_j = \sum_{i=1}^n w_ {ij} a_i+b_j.$$
+
+
      
+Since each neuron in the output layer is connected to the 50 inputs from the hidden layer we have 50x10 = 500
+weights to the output layer.
+
+
      
+
+
+
      Weights and biases 
      
+
+
      
+Typically weights are initialized with small values distributed around zero, drawn from a uniform
+or normal distribution. Setting all weights to zero means all neurons give the same output, making the network useless.
+
+
      
+Adding a bias value to the weighted sum of inputs allows the neural network to represent a greater range
+of values. Without it, any input with the value 0 will be mapped to zero (before being passed through the activation). The bias unit has an output of 1, and a weight to each neuron \( j \), \( b_j \):  
+
+$$ z_j = \sum_{i=1}^n w_ {ij} a_i + b_j.$$
+
+
      
+The bias weights \( \hat{b} \) are often initialized to zero, but a small value like \( 0.01 \) ensures all neurons have some output which can be backpropagated in the first training cycle.
+
      
+
+
+
      # building our neural network
+
+n_inputs, n_features = X_train.shape
+n_hidden_neurons = 50
+n_categories = 10
+
+# we make the weights normally distributed using numpy.random.randn
+
+# weights and bias in the hidden layer
+hidden_weights = np.random.randn(n_features, n_hidden_neurons)
+hidden_bias = np.zeros(n_hidden_neurons) + 0.01
+
+# weights and bias in the output layer
+output_weights = np.random.randn(n_hidden_neurons, n_categories)
+output_bias = np.zeros(n_categories) + 0.01
+
      
+
      
+









      
+
+
      Feed-forward pass 
      
+
+
      
+Denote \( F \) the number of features, \( H \) the number of hidden neurons and \( C \) the number of categories.  
+For each input image we calculate a weighted sum of input features (pixel values) to each neuron \( j \) in the hidden layer \( l \):  
+
+$$ z_{j}^{l} = \sum_{i=1}^{F} w_{ij}^{l} x_i + b_{j}^{l},$$
+
+
      
+this is then passed through our activation function  
+
+$$ a_{j}^{l} = f(z_{j}^{l}) .$$
+
+
      
+We calculate a weighted sum of inputs (activations in the hidden layer) to each neuron \( j \) in the output layer:  
+
+$$ z_{j}^{L} = \sum_{i=1}^{H} w_{ij}^{L} a_{i}^{l} + b_{j}^{L}.$$
+
+
      
+Finally we calculate the output of neuron \( j \) in the output layer using the softmax function:  
+
+$$ a_{j}^{L} = \frac{\exp{(z_j^{L})}}
+{\sum_{c=0}^{C-1} \exp{(z_c^{L})}} .$$
+
+
      
+
+
+
      Matrix multiplications 
      
+
+
      
+Since our data has the dimensions \( X = (n_{inputs}, n_{features}) \) and our weights to the hidden
+layer have the dimensions  
+\( W_{hidden} = (n_{features}, n_{hidden}) \),
+we can easily feed the network all our training data in one go by taking the matrix product  
+
+$$ X W^{h} = (n_{inputs}, n_{hidden}),$$
+
+
      
+and obtain a matrix that holds the weighted sum of inputs to the hidden layer
+for each input image and each hidden neuron.    
+We also add the bias to obtain a matrix of weighted sums to the hidden layer \( Z^{h} \):  
+
+$$ \hat{z}^{l} = \hat{X} \hat{W}^{l} + \hat{b}^{l} ,$$
+
+
      
+meaning the same bias (1D array with size equal number of hidden neurons) is added to each input image.  
+This is then passed through the activation:  
+
+$$ \hat{a}^{l} = f(\hat{z}^l) .$$
+
+
      
+This is fed to the output layer:  
+
+$$ \hat{z}^{L} = \hat{a}^{L} \hat{W}^{L} + \hat{b}^{L} .$$
+
+
      
+Finally we receive our output values for each image and each category by passing it through the softmax function:  
+
+$$ output = softmax (\hat{z}^{L}) = (n_{inputs}, n_{categories}) .$$
+
+
      
+
+
+
      # setup the feed-forward pass, subscript h = hidden layer
+
+def sigmoid(x):
+    return 1/(1 + np.exp(-x))
+
+def feed_forward(X):
+    # weighted sum of inputs to the hidden layer
+    z_h = np.matmul(X, hidden_weights) + hidden_bias
+    # activation in the hidden layer
+    a_h = sigmoid(z_h)
+    
+    # weighted sum of inputs to the output layer
+    z_o = np.matmul(a_h, output_weights) + output_bias
+    # softmax output
+    # axis 0 holds each input and axis 1 the probabilities of each category
+    exp_term = np.exp(z_o)
+    probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+    
+    return probabilities
+
+probabilities = feed_forward(X_train)
+print("probabilities = (n_inputs, n_categories) = " + str(probabilities.shape))
+print("probability that image 0 is in category 0,1,2,...,9 = \n" + str(probabilities[0]))
+print("probabilities sum up to: " + str(probabilities[0].sum()))
+print()
+
+# we obtain a prediction by taking the class with the highest likelihood
+def predict(X):
+    probabilities = feed_forward(X)
+    return np.argmax(probabilities, axis=1)
+
+predictions = predict(X_train)
+print("predictions = (n_inputs) = " + str(predictions.shape))
+print("prediction for image 0: " + str(predictions[0]))
+print("correct label for image 0: " + str(Y_train[0]))
+
      
+
      
+









      
+
+
      Choose cost function and optimizer 
      
+
+
      
+To measure how well our neural network is doing we need to introduce a cost function.  
+We will call the function that gives the error of a single sample output the loss function, and the function
+that gives the total error of our network across all samples the cost function.
+A typical choice for multiclass classification is the cross-entropy loss, also known as the negative log likelihood.
+
+
      
+In multiclass classification it is common to treat each integer label as a so called one-hot vector:  
+
+$$ y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) ,$$  
+
+$$ y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) ,$$
+
+
      
+i.e. a binary bit string of length \( C \), where \( C = 10 \) is the number of classes in the MNIST dataset.
+
+
      
+Let \( y_{ic} \) denote the \( c \)-th component of the \( i \)-th one-hot vector.  
+We define the cost function \( \mathcal{C} \) as a sum over the cross-entropy loss for each point \( \hat{x}_i \) in the dataset.
+
+
      
+In the one-hot representation only one of the terms in the loss function is non-zero, namely the
+probability of the correct category \( c' \)  
+(i.e. the category \( c' \) such that \( y_{ic'} = 1 \)). This means that the cross entropy loss only punishes you for how wrong
+you got the correct label. The probability of category \( c \) is given by the softmax function. The vector \( \hat{\theta} \) represents the parameters of our network, i.e. all the weights and biases.
+
+
      
+









      
+
+
      Optimizing the cost function 
      
+
+
      
+The network is trained by finding the weights and biases that minimize the cost function. One of the most widely used classes of methods is gradient descent and its generalizations. The idea behind gradient descent
+is simply to adjust the weights in the direction where the gradient of the cost function is large and negative. This ensures we flow toward a local minimum of the cost function.  
+Each parameter \( \theta \) is iteratively adjusted according to the rule  
+
+$$ \theta_{i+1} = \theta_i - \eta \nabla \mathcal{C}(\theta_i) ,$$
+
+
      
+where \( \eta \) is known as the learning rate, which controls how big a step we take towards the minimum.  
+This update can be repeated for any number of iterations, or until we are satisfied with the result.
+
+
      
+A simple and effective improvement is a variant called Batch Gradient Descent.  
+Instead of calculating the gradient on the whole dataset, we calculate an approximation of the gradient
+on a subset of the data called a minibatch.  
+If there are \( N \) data points and we have a minibatch size of \( M \), the total number of batches
+is \( N/M \).  
+We denote each minibatch \( B_k \), with \( k = 1, 2,...,N/M \). The gradient then becomes:  
+
+$$ \nabla \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \nabla \mathcal{L}_i(\theta) \quad \rightarrow \quad
+\frac{1}{M} \sum_{i \in B_k} \nabla \mathcal{L}_i(\theta) ,$$
+
+
      
+i.e. instead of averaging the loss over the entire dataset, we average over a minibatch.
+
+
      
+This has two important benefits:  
+
+
        
+
      1.  Introducing stochasticity decreases the chance that the algorithm becomes stuck in a local minima.
        2.   
+
      2.  It significantly speeds up the calculation, since we do not have to use the entire dataset to calculate the gradient.
        3.   
+
      
+
+The various optmization  methods, with codes and algorithms,  are discussed in our lectures on Gradient descent approaches.
+
+
      
+
+
+
      Regularization 
      
+
+
      
+It is common to add an extra term to the cost function, proportional
+to the size of the weights.  This is equivalent to constraining the
+size of the weights, so that they do not grow out of control.
+Constraining the size of the weights means that the weights cannot
+grow arbitrarily large to fit the training data, and in this way
+reduces overfitting.
+
+
      
+We will measure the size of the weights using the so called L2-norm, meaning our cost function becomes:  
+
+$$  \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \mathcal{L}_i(\theta) \quad \rightarrow \quad
+\frac{1}{N} \sum_{i=1}^N  \mathcal{L}_i(\theta) + \lambda \lvert \lvert \hat{w} \rvert \rvert_2^2 
+= \frac{1}{N} \sum_{i=1}^N  \mathcal{L}(\theta) + \lambda \sum_{ij} w_{ij}^2,$$
+
+
      
+i.e. we sum up all the weights squared. The factor \( \lambda \) is known as a regularization parameter.
+
+
      
+In order to train the model, we need to calculate the derivative of
+the cost function with respect to every bias and weight in the
+network.  In total our network has \( (64 + 1)\times 50=3250 \) weights in
+the hidden layer and \( (50 + 1)\times 10=510 \) weights to the output
+layer (\( +1 \) for the bias), and the gradient must be calculated for
+every parameter.  We use the backpropagation algorithm discussed
+above. This is a clever use of the chain rule that allows us to
+calculate the gradient efficently.
+
+
      
+









      
+
+
      Matrix  multiplication 
      
+
+
      
+To more efficently train our network these equations are implemented using matrix operations.  
+The error in the output layer is calculated simply as, with \( \hat{t} \) being our targets,  
+
+$$ \delta_L = \hat{t} - \hat{y} = (n_{inputs}, n_{categories}) .$$
+
+
      
+The gradient for the output weights is calculated as  
+
+$$ \nabla W_{L} = \hat{a}^T \delta_L   = (n_{hidden}, n_{categories}) ,$$
+
+
      
+where \( \hat{a} = (n_{inputs}, n_{hidden}) \). This simply means that we are summing up the gradients for each input.  
+Since we are going backwards we have to transpose the activation matrix.
+
+
      
+The gradient with respect to the output bias is then  
+
+$$ \nabla \hat{b}_{L} = \sum_{i=1}^{n_{inputs}} \delta_L = (n_{categories}) .$$
+
+
      
+The error in the hidden layer is  
+
+$$ \Delta_h = \delta_L W_{L}^T \circ f'(z_{h}) = \delta_L W_{L}^T \circ a_{h} \circ (1 - a_{h}) = (n_{inputs}, n_{hidden}) ,$$
+
+
      
+where \( f'(a_{h}) \) is the derivative of the activation in the hidden layer. The matrix products mean
+that we are summing up the products for each neuron in the output layer. The symbol \( \circ \) denotes
+the Hadamard product, meaning element-wise multiplication.
+
+
      
+This again gives us the gradients in the hidden layer:  
+
+$$ \nabla W_{h} = X^T \delta_h = (n_{features}, n_{hidden}) ,$$  
+
+$$ \nabla b_{h} = \sum_{i=1}^{n_{inputs}} \delta_h = (n_{hidden}) .$$
+
+
      
+
+
+
      # to categorical turns our integer vector into a onehot representation
+from sklearn.metrics import accuracy_score
+
+# one-hot in numpy
+def to_categorical_numpy(integer_vector):
+    n_inputs = len(integer_vector)
+    n_categories = np.max(integer_vector) + 1
+    onehot_vector = np.zeros((n_inputs, n_categories))
+    onehot_vector[range(n_inputs), integer_vector] = 1
+    
+    return onehot_vector
+
+#Y_train_onehot, Y_test_onehot = to_categorical(Y_train), to_categorical(Y_test)
+Y_train_onehot, Y_test_onehot = to_categorical_numpy(Y_train), to_categorical_numpy(Y_test)
+
+def feed_forward_train(X):
+    # weighted sum of inputs to the hidden layer
+    z_h = np.matmul(X, hidden_weights) + hidden_bias
+    # activation in the hidden layer
+    a_h = sigmoid(z_h)
+    
+    # weighted sum of inputs to the output layer
+    z_o = np.matmul(a_h, output_weights) + output_bias
+    # softmax output
+    # axis 0 holds each input and axis 1 the probabilities of each category
+    exp_term = np.exp(z_o)
+    probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+    
+    # for backpropagation need activations in hidden and output layers
+    return a_h, probabilities
+
+def backpropagation(X, Y):
+    a_h, probabilities = feed_forward_train(X)
+    
+    # error in the output layer
+    error_output = probabilities - Y
+    # error in the hidden layer
+    error_hidden = np.matmul(error_output, output_weights.T) * a_h * (1 - a_h)
+    
+    # gradients for the output layer
+    output_weights_gradient = np.matmul(a_h.T, error_output)
+    output_bias_gradient = np.sum(error_output, axis=0)
+    
+    # gradient for the hidden layer
+    hidden_weights_gradient = np.matmul(X.T, error_hidden)
+    hidden_bias_gradient = np.sum(error_hidden, axis=0)
+
+    return output_weights_gradient, output_bias_gradient, hidden_weights_gradient, hidden_bias_gradient
+
+print("Old accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train)))
+
+eta = 0.01
+lmbd = 0.01
+for i in range(1000):
+    # calculate gradients
+    dWo, dBo, dWh, dBh = backpropagation(X_train, Y_train_onehot)
+    
+    # regularization term gradients
+    dWo += lmbd * output_weights
+    dWh += lmbd * hidden_weights
+    
+    # update weights and biases
+    output_weights -= eta * dWo
+    output_bias -= eta * dBo
+    hidden_weights -= eta * dWh
+    hidden_bias -= eta * dBh
+
+print("New accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train)))
+
      
+
      
+









      
+
+
      Improving performance 
      
+
+
      
+As we can see the network does not seem to be learning at all. It seems to be just guessing the label for each image.  
+In order to obtain a network that does something useful, we will have to do a bit more work.
+
+
      
+The choice of hyperparameters such as learning rate and regularization parameter is hugely influential for the performance of the network. Typically a grid-search is performed, wherein we test different hyperparameters separated by orders of magnitude. For example we could test the learning rates \( \eta = 10^{-6}, 10^{-5},...,10^{-1} \) with different regularization parameters \( \lambda = 10^{-6},...,10^{-0} \).
+
+
      
+Next, we haven't implemented minibatching yet, which introduces stochasticity and is though to act as an important regularizer on the weights. We call a feed-forward + backward pass with a minibatch an iteration, and a full training period
+going through the entire dataset (\( n/M \) batches) an epoch.
+
+
      
+If this does not improve network performance, you may want to consider altering the network architecture, adding more neurons or hidden layers.  
+Andrew Ng goes through some of these considerations in this video. You can find a summary of the video here.
+
+
      
+









      
+
+
      Full object-oriented implementation 
      
+
+
      
+It is very natural to think of the network as an object, with specific instances of the network
+being realizations of this object with different hyperparameters. An implementation using Python classes provides a clean structure and interface, and the full implementation of our neural network is given below.
+
+
      
+
+
+
      class NeuralNetwork:
+    def __init__(
+            self,
+            X_data,
+            Y_data,
+            n_hidden_neurons=50,
+            n_categories=10,
+            epochs=10,
+            batch_size=100,
+            eta=0.1,
+            lmbd=0.0):
+
+        self.X_data_full = X_data
+        self.Y_data_full = Y_data
+
+        self.n_inputs = X_data.shape[0]
+        self.n_features = X_data.shape[1]
+        self.n_hidden_neurons = n_hidden_neurons
+        self.n_categories = n_categories
+
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self.iterations = self.n_inputs // self.batch_size
+        self.eta = eta
+        self.lmbd = lmbd
+
+        self.create_biases_and_weights()
+
+    def create_biases_and_weights(self):
+        self.hidden_weights = np.random.randn(self.n_features, self.n_hidden_neurons)
+        self.hidden_bias = np.zeros(self.n_hidden_neurons) + 0.01
+
+        self.output_weights = np.random.randn(self.n_hidden_neurons, self.n_categories)
+        self.output_bias = np.zeros(self.n_categories) + 0.01
+
+    def feed_forward(self):
+        # feed-forward for training
+        self.z_h = np.matmul(self.X_data, self.hidden_weights) + self.hidden_bias
+        self.a_h = sigmoid(self.z_h)
+
+        self.z_o = np.matmul(self.a_h, self.output_weights) + self.output_bias
+
+        exp_term = np.exp(self.z_o)
+        self.probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+
+    def feed_forward_out(self, X):
+        # feed-forward for output
+        z_h = np.matmul(X, self.hidden_weights) + self.hidden_bias
+        a_h = sigmoid(z_h)
+
+        z_o = np.matmul(a_h, self.output_weights) + self.output_bias
+        
+        exp_term = np.exp(z_o)
+        probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+        return probabilities
+
+    def backpropagation(self):
+        error_output = self.probabilities - self.Y_data
+        error_hidden = np.matmul(error_output, self.output_weights.T) * self.a_h * (1 - self.a_h)
+
+        self.output_weights_gradient = np.matmul(self.a_h.T, error_output)
+        self.output_bias_gradient = np.sum(error_output, axis=0)
+
+        self.hidden_weights_gradient = np.matmul(self.X_data.T, error_hidden)
+        self.hidden_bias_gradient = np.sum(error_hidden, axis=0)
+
+        if self.lmbd > 0.0:
+            self.output_weights_gradient += self.lmbd * self.output_weights
+            self.hidden_weights_gradient += self.lmbd * self.hidden_weights
+
+        self.output_weights -= self.eta * self.output_weights_gradient
+        self.output_bias -= self.eta * self.output_bias_gradient
+        self.hidden_weights -= self.eta * self.hidden_weights_gradient
+        self.hidden_bias -= self.eta * self.hidden_bias_gradient
+
+    def predict(self, X):
+        probabilities = self.feed_forward_out(X)
+        return np.argmax(probabilities, axis=1)
+
+    def predict_probabilities(self, X):
+        probabilities = self.feed_forward_out(X)
+        return probabilities
+
+    def train(self):
+        data_indices = np.arange(self.n_inputs)
+
+        for i in range(self.epochs):
+            for j in range(self.iterations):
+                # pick datapoints with replacement
+                chosen_datapoints = np.random.choice(
+                    data_indices, size=self.batch_size, replace=False
+                )
+
+                # minibatch training data
+                self.X_data = self.X_data_full[chosen_datapoints]
+                self.Y_data = self.Y_data_full[chosen_datapoints]
+
+                self.feed_forward()
+                self.backpropagation()
+
      
+
      
+









      
+
+
      Evaluate model performance on test data 
      
+
+
      
+To measure the performance of our network we evaluate how well it does it data it has never seen before, i.e. the test data.  
+We measure the performance of the network using the accuracy score.  
+The accuracy is as you would expect just the number of images correctly labeled divided by the total number of images. A perfect classifier will have an accuracy score of \( 1 \).  
+
+$$ \text{Accuracy} = \frac{\sum_{i=1}^n I(\hat{y}_i = y_i)}{n} ,$$
+
+
      
+where \( I \) is the indicator function, \( 1 \) if \( \hat{y}_i = y_i \) and \( 0 \) otherwise.
+
+
      
+
+
+
      epochs = 100
+batch_size = 100
+
+dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size,
+                    n_hidden_neurons=n_hidden_neurons, n_categories=n_categories)
+dnn.train()
+test_predict = dnn.predict(X_test)
+
+# accuracy score from scikit library
+print("Accuracy score on test set: ", accuracy_score(Y_test, test_predict))
+
+# equivalent in numpy
+def accuracy_score_numpy(Y_test, Y_pred):
+    return np.sum(Y_test == Y_pred) / len(Y_test)
+
+#print("Accuracy score on test set: ", accuracy_score_numpy(Y_test, test_predict))
+
      
+
      
+









      
+
+
      Adjust hyperparameters 
      
+
+
      
+We now perform a grid search to find the optimal hyperparameters for the network.  
+Note that we are only using 1 layer with 50 neurons, and human performance is estimated to be around \( 98\% \) (\( 2\% \) error rate).
+
+
      
+
+
+
      eta_vals = np.logspace(-5, 1, 7)
+lmbd_vals = np.logspace(-5, 1, 7)
+# store the models for later use
+DNN_numpy = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+
+# grid search
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size,
+                            n_hidden_neurons=n_hidden_neurons, n_categories=n_categories)
+        dnn.train()
+        
+        DNN_numpy[i][j] = dnn
+        
+        test_predict = dnn.predict(X_test)
+        
+        print("Learning rate  = ", eta)
+        print("Lambda = ", lmbd)
+        print("Accuracy score on test set: ", accuracy_score(Y_test, test_predict))
+        print()
+
      
+
      
+









      
+
+
      Visualization 
      
+
+
      
+
+
+
      # visual representation of grid search
+# uses seaborn heatmap, you can also do this with matplotlib imshow
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        dnn = DNN_numpy[i][j]
+        
+        train_pred = dnn.predict(X_train) 
+        test_pred = dnn.predict(X_test)
+
+        train_accuracy[i][j] = accuracy_score(Y_train, train_pred)
+        test_accuracy[i][j] = accuracy_score(Y_test, test_pred)
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
      
+
      
+









      
+
+
      scikit-learn implementation 
      
+
+
      
+scikit-learn focuses more
+on traditional machine learning methods, such as regression,
+clustering, decision trees, etc. As such, it has only two types of
+neural networks: Multi Layer Perceptron outputting continuous values,
+MPLRegressor, and Multi Layer Perceptron outputting labels,
+MLPClassifier. We will see how simple it is to use these classes.
+
+
      
+scikit-learn implements a few improvements from our neural network,
+such as early stopping, a varying learning rate, different
+optimization methods, etc. We would therefore expect a better
+performance overall.
+
+
      
+
+
+
      from sklearn.neural_network import MLPClassifier
+# store models for later use
+DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        dnn = MLPClassifier(hidden_layer_sizes=(n_hidden_neurons), activation='logistic',
+                            alpha=lmbd, learning_rate_init=eta, max_iter=epochs)
+        dnn.fit(X_train, Y_train)
+        
+        DNN_scikit[i][j] = dnn
+        
+        print("Learning rate  = ", eta)
+        print("Lambda = ", lmbd)
+        print("Accuracy score on test set: ", dnn.score(X_test, Y_test))
+        print()
+
      
+
      
+









      
+
+
      Visualization 
      
+
      
+
+
+
      # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        dnn = DNN_scikit[i][j]
+        
+        train_pred = dnn.predict(X_train) 
+        test_pred = dnn.predict(X_test)
+
+        train_accuracy[i][j] = accuracy_score(Y_train, train_pred)
+        test_accuracy[i][j] = accuracy_score(Y_test, test_pred)
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
      
+
      
+









      
+
+
      Building neural networks in Tensorflow and Keras 
      
+
+
      
+Now we want  to build on the experience gained from our neural network implementation in NumPy and scikit-learn
+and use it to construct a neural network in Tensorflow. Once we have constructed a neural network in NumPy
+and Tensorflow, building one in Keras is really quite trivial, though the performance may suffer.
+
+
      
+In our previous example we used only one hidden layer, and in this we will use two. From this it should be quite
+clear how to build one using an arbitrary number of hidden layers, using data structures such as Python lists or
+NumPy arrays.
+
+
      
+









      
+
+
      Tensorflow 
      
+
+
      
+Tensorflow is an open source library machine learning library
+developed by the Google Brain team for internal use. It was released
+under the Apache 2.0 open source license in November 9, 2015.
+
+
      
+Tensorflow is a computational framework that allows you to construct
+machine learning models at different levels of abstraction, from
+high-level, object-oriented APIs like Keras, down to the C++ kernels
+that Tensorflow is built upon. The higher levels of abstraction are
+simpler to use, but less flexible, and our choice of implementation
+should reflect the problems we are trying to solve.
+
+
      
+Tensorflow uses so-called graphs to represent your computation
+in terms of the dependencies between individual operations, such that you first build a Tensorflow graph
+to represent your model, and then create a Tensorflow session to run the graph.
+
+
      
+In this guide we will analyze the same data as we did in our NumPy and
+scikit-learn tutorial, gathered from the MNIST database of images. We
+will give an introduction to the lower level Python Application
+Program Interfaces (APIs), and see how we use them to build our graph.
+Then we will build (effectively) the same graph in Keras, to see just
+how simple solving a machine learning problem can be.
+
+
      
+To install tensorflow on Unix/Linux systems, use pip as
+
      
+
+
+
      pip3 install tensorflow
+
      
+
      
+and/or if you use anaconda, just write (or install from the graphical user interface)
+
      
+
+
+
      conda install tensorflow
+
      
+
      
+









      
+
+
      Collect and pre-process data 
      
+
+
      
+
+
+
      # import necessary packages
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn import datasets
+
+
+# ensure the same random numbers appear every time
+np.random.seed(0)
+
+# display images in notebook
+%matplotlib inline
+plt.rcParams['figure.figsize'] = (12,12)
+
+
+# download MNIST dataset
+digits = datasets.load_digits()
+
+# define inputs and labels
+inputs = digits.images
+labels = digits.target
+
+print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
+
+
+# flatten the image
+# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64
+n_inputs = len(inputs)
+inputs = inputs.reshape(n_inputs, -1)
+print("X = (n_inputs, n_features) = " + str(inputs.shape))
+
+
+# choose some random images to display
+indices = np.arange(n_inputs)
+random_indices = np.random.choice(indices, size=5)
+
+for i, image in enumerate(digits.images[random_indices]):
+    plt.subplot(1, 5, i+1)
+    plt.axis('off')
+    plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')
+    plt.title("Label: %d" % digits.target[random_indices[i]])
+plt.show()
+
      
+
      
+
+
+
      from keras.utils import to_categorical
+from sklearn.model_selection import train_test_split
+
+# one-hot representation of labels
+labels = to_categorical(labels)
+
+# split into train and test data
+train_size = 0.8
+test_size = 1 - train_size
+X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,
+                                                    test_size=test_size)
+
      
+
      
+









      
+
+
      Using TensorFlow backend 
      
+
+
        
+
      1.  Define model and architecture
        2. 
+
      2.  Choose cost function and optimizer
        3. 
+
      
+
+
      
+
+
+
      import tensorflow as tf
+
+class NeuralNetworkTensorflow:
+    def __init__(
+            self,
+            X_train,
+            Y_train,
+            X_test,
+            Y_test,
+            n_neurons_layer1=100,
+            n_neurons_layer2=50,
+            n_categories=2,
+            epochs=10,
+            batch_size=100,
+            eta=0.1,
+            lmbd=0.0):
+        
+        # keep track of number of steps
+        self.global_step = tf.Variable(0, dtype=tf.int32, trainable=False, name='global_step')
+        
+        self.X_train = X_train
+        self.Y_train = Y_train
+        self.X_test = X_test
+        self.Y_test = Y_test
+        
+        self.n_inputs = X_train.shape[0]
+        self.n_features = X_train.shape[1]
+        self.n_neurons_layer1 = n_neurons_layer1
+        self.n_neurons_layer2 = n_neurons_layer2
+        self.n_categories = n_categories
+        
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self.iterations = self.n_inputs // self.batch_size
+        self.eta = eta
+        self.lmbd = lmbd
+        
+        # build network piece by piece
+        # name scopes (with) are used to enforce creation of new variables
+        # https://www.tensorflow.org/guide/variables
+        self.create_placeholders()
+        self.create_DNN()
+        self.create_loss()
+        self.create_optimiser()
+        self.create_accuracy()
+    
+    def create_placeholders(self):
+        # placeholders are fine here, but "Datasets" are the preferred method
+        # of streaming data into a model
+        with tf.name_scope('data'):
+            self.X = tf.placeholder(tf.float32, shape=(None, self.n_features), name='X_data')
+            self.Y = tf.placeholder(tf.float32, shape=(None, self.n_categories), name='Y_data')
+    
+    def create_DNN(self):
+        with tf.name_scope('DNN'):
+            # the weights are stored to calculate regularization loss later
+            
+            # Fully connected layer 1
+            self.W_fc1 = self.weight_variable([self.n_features, self.n_neurons_layer1], name='fc1', dtype=tf.float32)
+            b_fc1 = self.bias_variable([self.n_neurons_layer1], name='fc1', dtype=tf.float32)
+            a_fc1 = tf.nn.sigmoid(tf.matmul(self.X, self.W_fc1) + b_fc1)
+            
+            # Fully connected layer 2
+            self.W_fc2 = self.weight_variable([self.n_neurons_layer1, self.n_neurons_layer2], name='fc2', dtype=tf.float32)
+            b_fc2 = self.bias_variable([self.n_neurons_layer2], name='fc2', dtype=tf.float32)
+            a_fc2 = tf.nn.sigmoid(tf.matmul(a_fc1, self.W_fc2) + b_fc2)
+            
+            # Output layer
+            self.W_out = self.weight_variable([self.n_neurons_layer2, self.n_categories], name='out', dtype=tf.float32)
+            b_out = self.bias_variable([self.n_categories], name='out', dtype=tf.float32)
+            self.z_out = tf.matmul(a_fc2, self.W_out) + b_out
+    
+    def create_loss(self):
+        with tf.name_scope('loss'):
+            softmax_loss = tf.reduce_mean(tf.nn.softmax_cross_entropy_with_logits_v2(labels=self.Y, logits=self.z_out))
+            
+            regularizer_loss_fc1 = tf.nn.l2_loss(self.W_fc1)
+            regularizer_loss_fc2 = tf.nn.l2_loss(self.W_fc2)
+            regularizer_loss_out = tf.nn.l2_loss(self.W_out)
+            regularizer_loss = self.lmbd*(regularizer_loss_fc1 + regularizer_loss_fc2 + regularizer_loss_out)
+            
+            self.loss = softmax_loss + regularizer_loss
+
+    def create_accuracy(self):
+        with tf.name_scope('accuracy'):
+            probabilities = tf.nn.softmax(self.z_out)
+            predictions = tf.argmax(probabilities, axis=1)
+            labels = tf.argmax(self.Y, axis=1)
+            
+            correct_predictions = tf.equal(predictions, labels)
+            correct_predictions = tf.cast(correct_predictions, tf.float32)
+            self.accuracy = tf.reduce_mean(correct_predictions)
+    
+    def create_optimiser(self):
+        with tf.name_scope('optimizer'):
+            self.optimizer = tf.train.GradientDescentOptimizer(learning_rate=self.eta).minimize(self.loss, global_step=self.global_step)
+            
+    def weight_variable(self, shape, name='', dtype=tf.float32):
+        initial = tf.truncated_normal(shape, stddev=0.1)
+        return tf.Variable(initial, name=name, dtype=dtype)
+    
+    def bias_variable(self, shape, name='', dtype=tf.float32):
+        initial = tf.constant(0.1, shape=shape)
+        return tf.Variable(initial, name=name, dtype=dtype)
+    
+    def fit(self):
+        data_indices = np.arange(self.n_inputs)
+
+        with tf.Session() as sess:
+            sess.run(tf.global_variables_initializer())
+            for i in range(self.epochs):
+                for j in range(self.iterations):
+                    chosen_datapoints = np.random.choice(data_indices, size=self.batch_size, replace=False)
+                    batch_X, batch_Y = self.X_train[chosen_datapoints], self.Y_train[chosen_datapoints]
+            
+                    sess.run([DNN.loss, DNN.optimizer],
+                        feed_dict={DNN.X: batch_X,
+                                   DNN.Y: batch_Y})
+                    accuracy = sess.run(DNN.accuracy,
+                        feed_dict={DNN.X: batch_X,
+                                   DNN.Y: batch_Y})
+                    step = sess.run(DNN.global_step)
+    
+            self.train_loss, self.train_accuracy = sess.run([DNN.loss, DNN.accuracy],
+                feed_dict={DNN.X: self.X_train,
+                           DNN.Y: self.Y_train})
+        
+            self.test_loss, self.test_accuracy = sess.run([DNN.loss, DNN.accuracy],
+                feed_dict={DNN.X: self.X_test,
+                           DNN.Y: self.Y_test})
+
      
+
      
+









      
+
+
      Optimizing and using gradient descent 
      
+
+
      
+
+
+
      epochs = 100
+batch_size = 100
+n_neurons_layer1 = 100
+n_neurons_layer2 = 50
+n_categories = 10
+eta_vals = np.logspace(-5, 1, 7)
+lmbd_vals = np.logspace(-5, 1, 7)
+
      
+
      
+
+
+
      DNN_tf = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+        
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        DNN = NeuralNetworkTensorflow(X_train, Y_train, X_test, Y_test,
+                                      n_neurons_layer1, n_neurons_layer2, n_categories,
+                                      epochs=epochs, batch_size=batch_size, eta=eta, lmbd=lmbd)
+        DNN.fit()
+        
+        DNN_tf[i][j] = DNN
+        
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % DNN.test_accuracy)
+        print()
+
      
+
      
+
+
+
      # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        DNN = DNN_tf[i][j]
+
+        train_accuracy[i][j] = DNN.train_accuracy
+        test_accuracy[i][j] = DNN.test_accuracy
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
      
+
      
+
+
+
      # optional
+# we can use log files to visualize our graph in Tensorboard
+writer = tf.summary.FileWriter('logs/')
+writer.add_graph(tf.get_default_graph())
+
      
+
      
+









      
+
+
      Using Keras 
      
+
+
      
+Keras is a high level neural network
+that supports Tensorflow, CTNK and Theano as backends.  
+If you have Tensorflow installed Keras is available through the tf.keras module.  
+If you have Anaconda installed you may run the following command
+
      
+
+
+
      conda install keras
+
      
+
      
+Alternatively, if you have Tensorflow or one of the other supported backends install you may use the pip package manager:
+
+
      
+
+
+
      pip3 install keras
+
      
+
      
+or look up the instructions here.
+
+
      
+
+
+
      from keras.models import Sequential
+from keras.layers import Dense
+from keras.regularizers import l2
+from keras.optimizers import SGD
+
+def create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories, eta, lmbd):
+    model = Sequential()
+    model.add(Dense(n_neurons_layer1, activation='sigmoid', kernel_regularizer=l2(lmbd)))
+    model.add(Dense(n_neurons_layer2, activation='sigmoid', kernel_regularizer=l2(lmbd)))
+    model.add(Dense(n_categories, activation='softmax'))
+    
+    sgd = SGD(lr=eta)
+    model.compile(loss='categorical_crossentropy', optimizer=sgd, metrics=['accuracy'])
+    
+    return model
+
      
+
      
+
+
+
      DNN_keras = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+        
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        DNN = create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories,
+                                         eta=eta, lmbd=lmbd)
+        DNN.fit(X_train, Y_train, epochs=epochs, batch_size=batch_size, verbose=0)
+        scores = DNN.evaluate(X_test, Y_test)
+        
+        DNN_keras[i][j] = DNN
+        
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % scores[1])
+        print()
+
      
+
      
+
+
+
      # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        DNN = DNN_keras[i][j]
+
+        train_accuracy[i][j] = DNN.evaluate(X_train, Y_train)[1]
+        test_accuracy[i][j] = DNN.evaluate(X_test, Y_test)[1]
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
      
+
      
+
+
+
      Which activation function should I use? 
      
+
+
      
+The Back propagation algorithm we derived above works by going from
+the output layer to the input layer, propagating the error gradient on
+the way. Once the algorithm has computed the gradient of the cost
+function with regards to each parameter in the network, it uses these
+gradients to update each parameter with a Gradient Descent (GD) step.
+
+
      
+Unfortunately for us, the gradients often get smaller and smaller as the
+algorithm progresses down to the first hidden layers. As a result, the
+GD update leaves the lower layer connection weights
+virtually unchanged, and training never converges to a good
+solution. This is known in the literature as 
+the vanishing gradients problem.
+
+
      
+In other cases, the opposite can happen, namely the the gradients can grow bigger and
+bigger. The result is that many of the layers get large updates of the 
+weights the
+algorithm diverges. This is the exploding gradients problem, which is
+mostly encountered in recurrent neural networks. More generally, deep
+neural networks suffer from unstable gradients, different layers may
+learn at widely different speeds
+
+
      
+
+
+
      Is the Logistic activation function (Sigmoid)  our choice? 
      
+
+
      
+Although this unfortunate behavior has been empirically observed for
+quite a while (it was one of the reasons why deep neural networks were
+mostly abandoned for a long time), it is only around 2010 that
+significant progress was made in understanding it.
+
+
      
+A paper titled Understanding the Difficulty of Training Deep
+Feedforward Neural Networks by Xavier Glorot and Yoshua Bengio found that
+the problems with the popular logistic
+sigmoid activation function and the weight initialization technique
+that was most popular at the time, namely random initialization using
+a normal distribution with a mean of 0 and a standard deviation of
+1.
+
+
      
+They showed that with this activation function and this
+initialization scheme, the variance of the outputs of each layer is
+much greater than the variance of its inputs. Going forward in the
+network, the variance keeps increasing after each layer until the
+activation function saturates at the top layers. This is actually made
+worse by the fact that the logistic function has a mean of 0.5, not 0
+(the hyperbolic tangent function has a mean of 0 and behaves slightly
+better than the logistic function in deep networks).
+
+
      
+









      
+
+
      The derivative of the Logistic funtion 
      
+
+
      
+Looking at the logistic activation function, when inputs become large
+(negative or positive), the function saturates at 0 or 1, with a
+derivative extremely close to 0. Thus when backpropagation kicks in,
+it has virtually no gradient to propagate back through the network,
+and what little gradient exists keeps getting diluted as
+backpropagation progresses down through the top layers, so there is
+really nothing left for the lower layers.
+
+
      
+In their paper, Glorot and Bengio propose a way to significantly
+alleviate this problem. We need the signal to flow properly in both
+directions: in the forward direction when making predictions, and in
+the reverse direction when backpropagating gradients. We don’t want
+the signal to die out, nor do we want it to explode and saturate. For
+the signal to flow properly, the authors argue that we need the
+variance of the outputs of each layer to be equal to the variance of
+its inputs, and we also need the gradients to have equal variance
+before and after flowing through a layer in the reverse direction.
+
+
      
+One of the insights in the 2010 paper by Glorot and Bengio was that
+the vanishing/exploding gradients problems were in part due to a poor
+choice of activation function. Until then most people had assumed that
+if Nature had chosen to use roughly sigmoid activation functions in
+biological neurons, they must be an excellent choice. But it turns out
+that other activation functions behave much better in deep neural
+networks, in particular the ReLU activation function, mostly because
+it does not saturate for positive values (and also because it is quite
+fast to compute).
+
+
      
+









      
+
+
      The RELU function family 
      
+
+
      
+The ReLU activation function suffers from a problem known as the dying
+ReLUs: during training, some neurons effectively die, meaning they
+stop outputting anything other than 0.
+
+
      
+In some cases, you may find that half of your network’s neurons are
+dead, especially if you used a large learning rate. During training,
+if a neuron’s weights get updated such that the weighted sum of the
+neuron’s inputs is negative, it will start outputting 0. When this
+happen, the neuron is unlikely to come back to life since the gradient
+of the ReLU function is 0 when its input is negative.
+
+
      
+To solve this problem, nowadays practitioners use a  variant of the ReLU
+function, such as the leaky ReLU discussed above or the so-called
+exponential linear unit (ELU) function
+
+$$
+ELU(z) = \left\{\begin{array}{cc} \alpha\left( \exp{(z)}-1\right) & z < 0,\\  z & z \ge 0.\end{array}\right. 
+$$
+
+
      
+









      
+
+
      Which activation function should we use? 
      
+
+
      
+In general it seems that the ELU activation function is better than
+the leaky ReLU function (and its variants), which is better than
+ReLU. ReLU performs better than \( \tanh \) which in turn performs better
+than the logistic function.
+
+
      
+If runtime
+performance is an issue, then you may opt for the  leaky ReLU function  over the 
+ELU function If you don’t
+want to tweak yet another hyperparameter, you may just use the default
+\( \alpha \) of \( 0.01 \) for the leaky ReLU, and \( 1 \) for ELU. If you have
+spare time and computing power, you can use cross-validation or
+bootstrap to evaluate other activation functions.
+
+
      
+
+
+
      A top-down perspective on Neural networks 
      
+
+
      
+The first thing we would like to do is divide the data into two or three
+parts. A training set, a validation or dev (development) set, and a
+test set. The test set is the data on which we want to make
+predictions. The dev set is a subset of the training data we use to
+check how well we are doing out-of-sample, after training the model on
+the training dataset. We use the validation error as a proxy for the
+test error in order to make tweaks to our model. It is crucial that we
+do not use any of the test data to train the algorithm. This is a
+cardinal sin in ML. Then:
+
+
        
+
      •  Estimate optimal error rate
        • 
+
      •  Minimize underfitting (bias) on training data set.
        • 
+
      •  Make sure you are not overfitting.
        • 
+
      
+
+If the validation and test sets are drawn from the same distributions,
+then a good performance on the validation set should lead to similarly
+good performance on the test set.
+
+
      
+However, sometimes
+the training data and test data differ in subtle ways because, for
+example, they are collected using slightly different methods, or
+because it is cheaper to collect data in one way versus another. In
+this case, there can be a mismatch between the training and test
+data. This can lead to the neural network overfitting these small
+differences between the test and training sets, and a poor performance
+on the test set despite having a good performance on the validation
+set. To rectify this, Andrew Ng suggests making two validation or dev
+sets, one constructed from the training data and one constructed from
+the test data. The difference between the performance of the algorithm
+on these two validation sets quantifies the train-test mismatch. This
+can serve as another important diagnostic when using DNNs for
+supervised learning.
+
+
      
+









      
+
+
      Limitations of supervised learning with deep networks 
      
+
+
      
+Like all statistical methods, supervised learning using neural
+networks has important limitations. This is especially important when
+one seeks to apply these methods, especially to physics problems. Like
+all tools, DNNs are not a universal solution. Often, the same or
+better performance on a task can be achieved by using a few
+hand-engineered features (or even a collection of random
+features).
+
+
      
+Here we list some of the important limitations of supervised neural network based models. 
+
+
        
+
      •  Need labeled data. All supervised learning methods, DNNs for supervised learning require labeled data. Often, labeled data is harder to acquire than unlabeled data (e.g. one must pay for human experts to label images).
        • 
+
      •  Supervised neural networks are extremely data intensive. DNNs are data hungry. They perform best when data is plentiful. This is doubly so for supervised methods where the data must also be labeled. The utility of DNNs is extremely limited if data is hard to acquire or the datasets are small (hundreds to a few thousand samples). In this case, the performance of other methods that utilize hand-engineered features can exceed that of DNNs.
        • 
+
      •  Homogeneous data. Almost all DNNs deal with homogeneous data of one type. It is very hard to design architectures that mix and match data types (i.e. some continuous variables, some discrete variables, some time series). In applications beyond images, video, and language, this is often what is required. In contrast, ensemble models like random forests or gradient-boosted trees have no difficulty handling mixed data types.
        • 
+
      •  Many problems are not about prediction. In natural science we are often interested in learning something about the underlying distribution that generates the data. In this case, it is often difficult to cast these ideas in a supervised learning setting. While the problems are related, it is possible to make good predictions with a wrong model. The model might or might not be useful for understanding the underlying science.
        • 
+
      
+
+Some of these remarks are particular to DNNs, others are shared by all supervised learning methods. This motivates the use of unsupervised methods which in part circumvent these problems.
+
+
      
+









      
+
+
      Convolutional Neural Networks (recognizing images) 
      
 
 
      
 Convolutional neural networks (CNNs) were developed during the last
@@ -154,7 +2086,7 @@ Another good read is the article here Regular NNs don’t scale well to full images 
+
      Regular NNs don’t scale well to full images 
      
 
 
      
 As an example, consider
@@ -182,7 +2114,7 @@ would quickly lead to possible overfitting.
 
      
 









      
 
-
      3D volumes of neurons 
      
+
      3D volumes of neurons 
      
 
 
      
 Convolutional Neural Networks take advantage of the fact that the
@@ -222,7 +2154,7 @@ dimension.
 
      
 
 
-
      Layers used to build CNNs 
      
+
      Layers used to build CNNs 
      
 
 
      
 A simple CNN is a sequence of layers, and every layer of a CNN
@@ -245,7 +2177,7 @@ A simple CNN for image classification could have the architecture:
 
 









      
 
-
      Transforming images 
      
+
      Transforming images 
      
 
 
      
 CNNs transform the original image layer by layer from the original
@@ -264,7 +2196,7 @@ are consistent with the labels in the training set for each image.
 
      
 









      
 
-
      CNNs in brief 
      
+
      CNNs in brief 
      
 
 
      
 In summary:
@@ -285,7 +2217,7 @@ and the slides of 
 









      
 
-
      CNNs in more detail, building convolutional neural networks in Tensorflow and Keras 
      
+
      CNNs in more detail, building convolutional neural networks in Tensorflow and Keras 
      
 
 
      
 As discussed above, CNNs are neural networks built from the assumption that the inputs
@@ -301,7 +2233,7 @@ matrices, typically 1 for each color dimension (Red, Green, Blue).
 
      
 









      
 
-
      Setting it up 
      
+
      Setting it up 
      
 
 
      
 It means that to represent the entire
@@ -313,7 +2245,7 @@ $$
 
      
 









      
 
-
      The MNIST dataset again 
      
+
      The MNIST dataset again 
      
 
 
      
 The MNIST dataset consists of grayscale images with a pixel size of
@@ -331,7 +2263,7 @@ single neuron in the first hidden layer.
 
      
 









      
 
-
      Strong correlations 
      
+
      Strong correlations 
      
 Images typically have strong local correlations, meaning that a small
 part of the image varies little from its neighboring regions. If for
 example we have an image of a blue car, we can roughly assume that a
@@ -347,7 +2279,7 @@ fixed, and known as a       
 
 
-
      Layers of a CNN 
      
+
      Layers of a CNN 
      
 The layers of a convolutional neural network arrange neurons in 3D: width, height and depth.  
 The input image is typically a square matrix of depth 3.
 
@@ -369,7 +2301,7 @@ layer.
 
      
 









      
 
-
      Systematic reduction 
      
+
      Systematic reduction 
      
 
 
      
 By systematically reducing the size of the input volume, through
@@ -384,7 +2316,7 @@ classification.
 
      
 









      
 
-
      Prerequisites: Collect and pre-process data 
      
+
      Prerequisites: Collect and pre-process data 
      
 
      
 
 
@@ -413,8 +2345,8 @@ labels = digits.target
 # our images are grayscale so they should have a depth of 1
 inputs = inputs[:,:,:,np.newaxis]
 
-print("inputs = (n_inputs, pixel_width, pixel_height, depth) = " + str(inputs.shape))
-print("labels = (n_inputs) = " + str(labels.shape))
+print("inputs = (n_inputs, pixel_width, pixel_height, depth) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
 
 
 # choose some random images to display
@@ -432,7 +2364,7 @@ plt.show()
 
      
 









      
 
-
      Importing Keras and Tensorflow 
      
+
      Importing Keras and Tensorflow 
      
 
      
 
 
@@ -452,7 +2384,7 @@ X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=t
 
      
 









      
 
-
      Using TensorFlow backend 
      
+
      Using TensorFlow backend 
      
 
 
      
 We need to define model and architecture and choose cost function and optmizer.
@@ -600,7 +2532,7 @@ class ConvolutionalNeuralNetworkTensorflow:
 
      
 









      
 
-
      Train the model 
      
+
      Train the model 
      
 
 
      
 We need now to train the model, evaluate it and test its performance on test data, and eventually include hyperparameters.
@@ -625,17 +2557,17 @@ CNN_tf = np.zeros((len(eta_vals), print("Learning rate = ", eta)
-        print("Lambda = ", lmbd)
-        print("Test accuracy: %.3f" % CNN.test_accuracy)
-        print()
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % CNN.test_accuracy)
+        print()
             
         CNN_tf[i][j] = CNN











    -

    Visualizing the results

    +

    Visualizing the results

    @@ -658,14 +2590,14 @@ test_accuracy = np.zeros((len(eta_vals), 10, 10)) -sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis") +sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis") ax.set_title("Training Accuracy") ax.set_ylabel("$\eta$") ax.set_xlabel("$\lambda$") plt.show() fig, ax = plt.subplots(figsize = (10, 10)) -sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis") +sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis") ax.set_title("Test Accuracy") ax.set_ylabel("$\eta$") ax.set_xlabel("$\lambda$") @@ -674,7 +2606,7 @@ plt.show()

    -

    Running with Keras

    +

    Running with Keras

    @@ -717,7 +2649,7 @@ lmbd_vals = np.logspace(-5, Final part +

    Final part

    @@ -734,15 +2666,15 @@ lmbd_vals = np.logspace(-5, print("Learning rate = ", eta) - print("Lambda = ", lmbd) - print("Test accuracy: %.3f" % scores[1]) - print() + print("Learning rate = ", eta) + print("Lambda = ", lmbd) + print("Test accuracy: %.3f" % scores[1]) + print()











    -

    Final visualization

    +

    Final visualization

    @@ -781,7 +2713,7 @@ plt.show()











    -

    Fun links

    +

    Fun links

    1. Self-Driving cars using a convolutional neural network
      2. diff --git a/doc/pub/week41/html/week41.html b/doc/pub/week41/html/week41.html index 96486431c..13a71098e 100644 --- a/doc/pub/week41/html/week41.html +++ b/doc/pub/week41/html/week41.html @@ -31,6 +31,32 @@ p { text-indent: 0px; } hr { border: 0; width: 80%; border-bottom: 1px solid #aaa} p.caption { width: 80%; font-style: normal; text-align: left; } hr.figure { border: 0; width: 80%; border-bottom: 1px solid #aaa} +.alert-text-small { font-size: 80%; } +.alert-text-large { font-size: 130%; } +.alert-text-normal { font-size: 90%; } +.alert { + padding:8px 35px 8px 14px; margin-bottom:18px; + text-shadow:0 1px 0 rgba(255,255,255,0.5); + border:1px solid #bababa; + border-radius: 4px; + -webkit-border-radius: 4px; + -moz-border-radius: 4px; + color: #555; + background-color: #f8f8f8; + background-position: 10px 5px; + background-repeat: no-repeat; + background-size: 38px; + padding-left: 55px; + width: 75%; + } +.alert-block {padding-top:14px; padding-bottom:14px} +.alert-block > p, .alert-block > ul {margin-bottom:1em} +.alert li {margin-top: 1em} +.alert-block p+p {margin-top:5px} +.alert-notice { background-image: url(https://cdn.rawgit.com/hplgit/doconce/master/bundled/html_images/small_gray_notice.png); } +.alert-summary { background-image:url(https://cdn.rawgit.com/hplgit/doconce/master/bundled/html_images/small_gray_summary.png); } +.alert-warning { background-image: url(https://cdn.rawgit.com/hplgit/doconce/master/bundled/html_images/small_gray_warning.png); } +.alert-question {background-image:url(https://cdn.rawgit.com/hplgit/doconce/master/bundled/html_images/small_gray_question.png); } div { text-align: justify; text-justify: inter-word; } @@ -40,40 +66,98 @@ div { text-align: justify; text-justify: inter-word; } @@ -115,12 +199,1860 @@ MathJax.Hub.Config({
      [2] Department of Physics and Astronomy and National Superconducting Cyclotron Laboratory, Michigan State University

      -

      Sep 16, 2020

      +

      Oct 5, 2020












      -

      Convolutional Neural Networks (recognizing images)

      +

      Plan for week 40

      + + + +Reading suggestions for both days: Aurelien Geron's chapters 10-11 and Hastie et al chapter 11. + +

      +









      + +

      Overview video for week 41

      + +

      +"Overview Video, from Stochastic Gradient methods to Neural Networks":"https://www.uio.no/studier/emner/matnat/fys/FYS-STK3155/h20\ +/forelesningsvideoer/OverviewWeek41.mp4?vrtx=view-as-webpage" + +

      +









      + +

      Setting up the Back propagation algorithm

      + +

      +The four equations provide us with a way of computing the gradient of the cost function. Let us write this out in the form of an algorithm. + +

      +

      + +

      +First, we set up the input data \( \hat{x} \) and the activations +\( \hat{z}_1 \) of the input layer and compute the activation function and +the pertinent outputs \( \hat{a}^1 \). +

      + + +

      +

      + +

      +Secondly, we perform then the feed forward till we reach the output +layer and compute all \( \hat{z}_l \) of the input layer and compute the +activation function and the pertinent outputs \( \hat{a}^l \) for +\( l=2,3,\dots,L \). +

      + + +

      +

      + +

      +Thereafter we compute the ouput error \( \hat{\delta}^L \) by computing all +$$ +\delta_j^L = f'(z_j^L)\frac{\partial {\cal C}}{\partial (a_j^L)}. +$$ +

      + + +

      +

      + +

      +Then we compute the back propagate error for each \( l=L-1,L-2,\dots,2 \) as +$$ +\delta_j^l = \sum_k \delta_k^{l+1}w_{kj}^{l+1}f'(z_j^l). +$$ +

      + + +

      +

      + +

      +Finally, we update the weights and the biases using gradient descent for each \( l=L-1,L-2,\dots,2 \) and update the weights and biases according to the rules +$$ +w_{jk}^l\leftarrow = w_{jk}^l- \eta \delta_j^la_k^{l-1}, +$$ + + +$$ +b_j^l \leftarrow b_j^l-\eta \frac{\partial {\cal C}}{\partial b_j^l}=b_j^l-\eta \delta_j^l, +$$ +

      + + +

      +The parameter \( \eta \) is the learning parameter discussed in connection with the gradient descent methods. +Here it is convenient to use stochastic gradient descent (see the examples below) with mini-batches with an outer loop that steps through multiple epochs of training. + +

      + + +

      Setting up a Multi-layer perceptron model for classification

      + +

      +We are now gong to develop an example based on the MNIST data +base. This is a classification problem and we need to use our +cross-entropy function we discussed in connection with logistic +regression. The cross-entropy defines our cost function for the +classificaton problems with neural networks. + +

      +In binary classification with two classes \( (0, 1) \) we define the +logistic/sigmoid function as the probability that a particular input +is in class \( 0 \) or \( 1 \). This is possible because the logistic +function takes any input from the real numbers and inputs a number +between 0 and 1, and can therefore be interpreted as a probability. It +also has other nice properties, such as a derivative that is simple to +calculate. + +

      +For an input \( \boldsymbol{a} \) from the hidden layer, the probability that the input \( \boldsymbol{x} \) +is in class 0 or 1 is just. We let \( \theta \) represent the unknown weights and biases to be adjusted by our equations). The variable \( x \) +represents our activation values \( z \). We have +$$ +P(y = 0 \mid \hat{x}, \hat{\theta}) = \frac{1}{1 + \exp{(- \hat{x}})} , +$$ + +and +$$ +P(y = 1 \mid \hat{x}, \hat{\theta}) = 1 - P(y = 0 \mid \hat{x}, \hat{\theta}) , +$$ + +

      +where \( y \in \{0, 1\} \) and \( \hat{\theta} \) represents the weights and biases +of our network. + +

      +









      + +

      Defining the cost function

      + +

      +Our cost function is given as (see the Logistic regression lectures) +$$ +\mathcal{C}(\hat{\theta}) = - \ln P(\mathcal{D} \mid \hat{\theta}) = - \sum_{i=1}^n +y_i \ln[P(y_i = 0)] + (1 - y_i) \ln [1 - P(y_i = 0)] = \sum_{i=1}^n \mathcal{L}_i(\hat{\theta}) . +$$ + +

      +This last equality means that we can interpret our cost function as a sum over the loss function +for each point in the dataset \( \mathcal{L}_i(\hat{\theta}) \). +The negative sign is just so that we can think about our algorithm as minimizing a positive number, rather +than maximizing a negative number. + +

      +In multiclass classification it is common to treat each integer label as a so called one-hot vector: + +

      +\( y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) , \) and + +

      +\( y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) , \) + +

      +i.e. a binary bit string of length \( C \), where \( C = 10 \) is the number of classes in the MNIST dataset (numbers from \( 0 \) to \( 9 \)).. + +

      +If \( \hat{x}_i \) is the \( i \)-th input (image), \( y_{ic} \) refers to the \( c \)-th component of the \( i \)-th +output vector \( \hat{y}_i \). +The probability of \( \hat{x}_i \) being in class \( c \) will be given by the softmax function: + +$$ +P(y_{ic} = 1 \mid \hat{x}_i, \hat{\theta}) = \frac{\exp{((\hat{a}_i^{hidden})^T \hat{w}_c)}} +{\sum_{c'=0}^{C-1} \exp{((\hat{a}_i^{hidden})^T \hat{w}_{c'})}} , +$$ + +

      +which reduces to the logistic function in the binary case. +The likelihood of this \( C \)-class classifier +is now given as: + +$$ +P(\mathcal{D} \mid \hat{\theta}) = \prod_{i=1}^n \prod_{c=0}^{C-1} [P(y_{ic} = 1)]^{y_{ic}} . +$$ + +Again we take the negative log-likelihood to define our cost function: + +$$ +\mathcal{C}(\hat{\theta}) = - \log{P(\mathcal{D} \mid \hat{\theta})}. +$$ + +See the logistic regression lectures for a full definition of the cost function. + +

      +The back propagation equations need now only a small change, namely the definition of a new cost function. We are thus ready to use the same equations as before! + +

      +









      + +

      Example: binary classification problem

      + +

      +As an example of the above, relevant for project 2 as well, let us consider a binary class. As discussed in our logistic regression lectures, we defined a cost function in terms of the parameters \( \beta \) as +$$ +\mathcal{C}(\hat{\beta}) = - \sum_{i=1}^n \left(y_i\log{p(y_i \vert x_i,\hat{\beta})}+(1-y_i)\log{1-p(y_i \vert x_i,\hat{\beta})}\right), +$$ + +where we had defined the logistic (sigmoid) function +$$ +p(y_i =1\vert x_i,\hat{\beta})=\frac{\exp{(\beta_0+\beta_1 x_i)}}{1+\exp{(\beta_0+\beta_1 x_i)}}, +$$ + +and +$$ +p(y_i =0\vert x_i,\hat{\beta})=1-p(y_i =1\vert x_i,\hat{\beta}). +$$ + +The parameters \( \hat{\beta} \) were defined using a minimization method like gradient descent or Newton-Raphson's method. + +

      +Now we replace \( x_i \) with the activation \( z_i^l \) for a given layer \( l \) and the outputs as \( y_i=a_i^l=f(z_i^l) \), with \( z_i^l \) now being a function of the weights \( w_{ij}^l \) and biases \( b_i^l \). +We have then +$$ +a_i^l = y_i = \frac{\exp{(z_i^l)}}{1+\exp{(z_i^l)}}, +$$ + +with +$$ +z_i^l = \sum_{j}w_{ij}^l a_j^{l-1}+b_i^l, +$$ + +where the superscript \( l-1 \) indicates that these are the outputs from layer \( l-1 \). +Our cost function at the final layer \( l=L \) is now +$$ +\mathcal{C}(\hat{W}) = - \sum_{i=1}^n \left(t_i\log{a_i^L}+(1-t_i)\log{(1-a_i^L)}\right), +$$ + +where we have defined the targets \( t_i \). The derivatives of the cost function with respect to the output \( a_i^L \) are then easily calculated and we get +$$ +\frac{\partial \mathcal{C}(\hat{W})}{\partial a_i^L} = \frac{a_i^L-t_i}{a_i^L(1-a_i^L)}. +$$ + +In case we use another activation function than the logistic one, we need to evaluate other derivatives. + +

      +









      + +

      The Softmax function

      +In case we employ the more general case given by the Softmax equation, we need to evaluate the derivative of the activation function with respect to the activation \( z_i^l \), that is we need +$$ +\frac{\partial f(z_i^l)}{\partial w_{jk}^l} = +\frac{\partial f(z_i^l)}{\partial z_j^l} \frac{\partial z_j^l}{\partial w_{jk}^l}= \frac{\partial f(z_i^l)}{\partial z_j^l}a_k^{l-1}. +$$ + +For the Softmax function we have +$$ +f(z_i^l) = \frac{\exp{(z_i^l)}}{\sum_{m=1}^K\exp{(z_m^l)}}. +$$ + +Its derivative with respect to \( z_j^l \) gives +$$ +\frac{\partial f(z_i^l)}{\partial z_j^l}= f(z_i^l)\left(\delta_{ij}-f(z_j^l)\right), +$$ + +which in case of the simply binary model reduces to having \( i=j \). + +

      + + +

      Developing a code for doing neural networks with back propagation

      + +

      +One can identify a set of key steps when using neural networks to solve supervised learning problems: + +

        +
      1. Collect and pre-process data
        2. +
      2. Define model and architecture
        3. +
      3. Choose cost function and optimizer
        4. +
      4. Train the model
        5. +
      5. Evaluate model performance on test data
        6. +
      6. Adjust hyperparameters (if necessary, network architecture)
        7. +
      + +









      + +

      Collect and pre-process data

      + +

      +Here we will be using the MNIST dataset, which is readily available through the scikit-learn +package. You may also find it for example here. +The MNIST (Modified National Institute of Standards and Technology) database is a large database +of handwritten digits that is commonly used for training various image processing systems. +The MNIST dataset consists of 70 000 images of size \( 28\times 28 \) pixels, each labeled from 0 to 9. +The scikit-learn dataset we will use consists of a selection of 1797 images of size \( 8\times 8 \) collected and processed from this database. + +

      +To feed data into a feed-forward neural network we need to represent +the inputs as a design/feature matrix \( X = (n_{inputs}, n_{features}) \). Each +row represents an input, in this case a handwritten digit, and +each column represents a feature, in this case a pixel. The +correct answers, also known as labels or targets are +represented as a 1D array of integers +\( Y = (n_{inputs}) = (5, 3, 1, 8,...) \). + +

      +As an example, say we want to build a neural network using supervised learning to predict Body-Mass Index (BMI) from +measurements of height (in m) +and weight (in kg). If we have measurements of 5 people the design/feature matrix could be for example: + +$$ X = \begin{bmatrix} +1.85 & 81\\ +1.71 & 65\\ +1.95 & 103\\ +1.55 & 42\\ +1.63 & 56 +\end{bmatrix} ,$$ + +

      +and the targets would be: + +$$ Y = (23.7, 22.2, 27.1, 17.5, 21.1) $$ + +

      +Since each input image is a 2D matrix, we need to flatten the image +(i.e. "unravel" the 2D matrix into a 1D array) to turn the data into a +design/feature matrix. This means we lose all spatial information in the +image, such as locality and translational invariance. More complicated +architectures such as Convolutional Neural Networks can take advantage +of such information, and are most commonly applied when analyzing +images. + +

      + + +

      # import necessary packages
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn import datasets
+
+
+# ensure the same random numbers appear every time
+np.random.seed(0)
+
+# display images in notebook
+%matplotlib inline
+plt.rcParams['figure.figsize'] = (12,12)
+
+
+# download MNIST dataset
+digits = datasets.load_digits()
+
+# define inputs and labels
+inputs = digits.images
+labels = digits.target
+
+print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
+
+
+# flatten the image
+# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64
+n_inputs = len(inputs)
+inputs = inputs.reshape(n_inputs, -1)
+print("X = (n_inputs, n_features) = " + str(inputs.shape))
+
+
+# choose some random images to display
+indices = np.arange(n_inputs)
+random_indices = np.random.choice(indices, size=5)
+
+for i, image in enumerate(digits.images[random_indices]):
+    plt.subplot(1, 5, i+1)
+    plt.axis('off')
+    plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')
+    plt.title("Label: %d" % digits.target[random_indices[i]])
+plt.show()
+
      +

      +









      + +

      Train and test datasets

      + +

      +Performing analysis before partitioning the dataset is a major error, that can lead to incorrect conclusions. + +

      +We will reserve \( 80 \% \) of our dataset for training and \( 20 \% \) for testing. + +

      +It is important that the train and test datasets are drawn randomly from our dataset, to ensure +no bias in the sampling. +Say you are taking measurements of weather data to predict the weather in the coming 5 days. +You don't want to train your model on measurements taken from the hours 00.00 to 12.00, and then test it on data +collected from 12.00 to 24.00. + +

      + + +

      from sklearn.model_selection import train_test_split
+
+# one-liner from scikit-learn library
+train_size = 0.8
+test_size = 1 - train_size
+X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,
+                                                    test_size=test_size)
+
+# equivalently in numpy
+def train_test_split_numpy(inputs, labels, train_size, test_size):
+    n_inputs = len(inputs)
+    inputs_shuffled = inputs.copy()
+    labels_shuffled = labels.copy()
+    
+    np.random.shuffle(inputs_shuffled)
+    np.random.shuffle(labels_shuffled)
+    
+    train_end = int(n_inputs*train_size)
+    X_train, X_test = inputs_shuffled[:train_end], inputs_shuffled[train_end:]
+    Y_train, Y_test = labels_shuffled[:train_end], labels_shuffled[train_end:]
+    
+    return X_train, X_test, Y_train, Y_test
+
+#X_train, X_test, Y_train, Y_test = train_test_split_numpy(inputs, labels, train_size, test_size)
+
+print("Number of training images: " + str(len(X_train)))
+print("Number of test images: " + str(len(X_test)))
+
      +

      +









      + +

      Define model and architecture

      + +

      +Our simple feed-forward neural network will consist of an input layer, a single hidden layer and an output layer. The activation \( y \) of each neuron is a weighted sum of inputs, passed through an activation function. In case of the simple perceptron model we have + +$$ z = \sum_{i=1}^n w_i a_i ,$$ + +$$ y = f(z) ,$$ + +

      +where \( f \) is the activation function, \( a_i \) represents input from neuron \( i \) in the preceding layer +and \( w_i \) is the weight to input \( i \). +The activation of the neurons in the input layer is just the features (e.g. a pixel value). + +

      +The simplest activation function for a neuron is the Heaviside function: + +$$ f(z) = +\begin{cases} +1, & z > 0\\ +0, & \text{otherwise} +\end{cases} +$$ + +

      +A feed-forward neural network with this activation is known as a perceptron. +For a binary classifier (i.e. two classes, 0 or 1, dog or not-dog) we can also use this in our output layer. +This activation can be generalized to \( k \) classes (using e.g. the one-against-all strategy), +and we call these architectures multiclass perceptrons. + +

      +However, it is now common to use the terms Single Layer Perceptron (SLP) (1 hidden layer) and +Multilayer Perceptron (MLP) (2 or more hidden layers) to refer to feed-forward neural networks with any activation function. + +

      +Typical choices for activation functions include the sigmoid function, hyperbolic tangent, and Rectified Linear Unit (ReLU). +We will be using the sigmoid function \( \sigma(x) \): + +$$ f(x) = \sigma(x) = \frac{1}{1 + e^{-x}} ,$$ + +

      +which is inspired by probability theory (see logistic regression) and was most commonly used until about 2011. See the discussion below concerning other activation functions. + +

      + + +

      Layers

      + + + +Since each input image has 8x8 = 64 pixels or features, we have an input layer of 64 neurons. + + + +We will use 50 neurons in the hidden layer receiving input from the neurons in the input layer. +Since each neuron in the hidden layer is connected to the 64 inputs we have 64x50 = 3200 weights to the hidden layer. + + + +If we were building a binary classifier, it would be sufficient with a single neuron in the output layer, +which could output 0 or 1 according to the Heaviside function. This would be an example of a hard classifier, meaning it outputs the class of the input directly. However, if we are dealing with noisy data it is often beneficial to use a soft classifier, which outputs the probability of being in class 0 or 1. + +

      +For a soft binary classifier, we could use a single neuron and interpret the output as either being the probability of being in class 0 or the probability of being in class 1. Alternatively we could use 2 neurons, and interpret each neuron as the probability of being in each class. + +

      +Since we are doing multiclass classification, with 10 categories, it is natural to use 10 neurons in the output layer. We number the neurons \( j = 0,1,...,9 \). The activation of each output neuron \( j \) will be according to the softmax function: + +$$ P(\text{class \( j \)} \mid \text{input \( \hat{a} \)}) = \frac{\exp{(\hat{a}^T \hat{w}_j)}} +{\sum_{c=0}^{9} \exp{(\hat{a}^T \hat{w}_c)}} ,$$ + +

      +i.e. each neuron \( j \) outputs the probability of being in class \( j \) given an input from the hidden layer \( \hat{a} \), with \( \hat{w}_j \) the weights of neuron \( j \) to the inputs. +The denominator is a normalization factor to ensure the outputs (probabilities) sum up to 1. +The exponent is just the weighted sum of inputs as before: + +$$ z_j = \sum_{i=1}^n w_ {ij} a_i+b_j.$$ + +

      +Since each neuron in the output layer is connected to the 50 inputs from the hidden layer we have 50x10 = 500 +weights to the output layer. + +

      + + +

      Weights and biases

      + +

      +Typically weights are initialized with small values distributed around zero, drawn from a uniform +or normal distribution. Setting all weights to zero means all neurons give the same output, making the network useless. + +

      +Adding a bias value to the weighted sum of inputs allows the neural network to represent a greater range +of values. Without it, any input with the value 0 will be mapped to zero (before being passed through the activation). The bias unit has an output of 1, and a weight to each neuron \( j \), \( b_j \): + +$$ z_j = \sum_{i=1}^n w_ {ij} a_i + b_j.$$ + +

      +The bias weights \( \hat{b} \) are often initialized to zero, but a small value like \( 0.01 \) ensures all neurons have some output which can be backpropagated in the first training cycle. +

      + + +

      # building our neural network
+
+n_inputs, n_features = X_train.shape
+n_hidden_neurons = 50
+n_categories = 10
+
+# we make the weights normally distributed using numpy.random.randn
+
+# weights and bias in the hidden layer
+hidden_weights = np.random.randn(n_features, n_hidden_neurons)
+hidden_bias = np.zeros(n_hidden_neurons) + 0.01
+
+# weights and bias in the output layer
+output_weights = np.random.randn(n_hidden_neurons, n_categories)
+output_bias = np.zeros(n_categories) + 0.01
+
      +

      +









      + +

      Feed-forward pass

      + +

      +Denote \( F \) the number of features, \( H \) the number of hidden neurons and \( C \) the number of categories. +For each input image we calculate a weighted sum of input features (pixel values) to each neuron \( j \) in the hidden layer \( l \): + +$$ z_{j}^{l} = \sum_{i=1}^{F} w_{ij}^{l} x_i + b_{j}^{l},$$ + +

      +this is then passed through our activation function + +$$ a_{j}^{l} = f(z_{j}^{l}) .$$ + +

      +We calculate a weighted sum of inputs (activations in the hidden layer) to each neuron \( j \) in the output layer: + +$$ z_{j}^{L} = \sum_{i=1}^{H} w_{ij}^{L} a_{i}^{l} + b_{j}^{L}.$$ + +

      +Finally we calculate the output of neuron \( j \) in the output layer using the softmax function: + +$$ a_{j}^{L} = \frac{\exp{(z_j^{L})}} +{\sum_{c=0}^{C-1} \exp{(z_c^{L})}} .$$ + +

      + + +

      Matrix multiplications

      + +

      +Since our data has the dimensions \( X = (n_{inputs}, n_{features}) \) and our weights to the hidden +layer have the dimensions +\( W_{hidden} = (n_{features}, n_{hidden}) \), +we can easily feed the network all our training data in one go by taking the matrix product + +$$ X W^{h} = (n_{inputs}, n_{hidden}),$$ + +

      +and obtain a matrix that holds the weighted sum of inputs to the hidden layer +for each input image and each hidden neuron. +We also add the bias to obtain a matrix of weighted sums to the hidden layer \( Z^{h} \): + +$$ \hat{z}^{l} = \hat{X} \hat{W}^{l} + \hat{b}^{l} ,$$ + +

      +meaning the same bias (1D array with size equal number of hidden neurons) is added to each input image. +This is then passed through the activation: + +$$ \hat{a}^{l} = f(\hat{z}^l) .$$ + +

      +This is fed to the output layer: + +$$ \hat{z}^{L} = \hat{a}^{L} \hat{W}^{L} + \hat{b}^{L} .$$ + +

      +Finally we receive our output values for each image and each category by passing it through the softmax function: + +$$ output = softmax (\hat{z}^{L}) = (n_{inputs}, n_{categories}) .$$ + +

      + + +

      # setup the feed-forward pass, subscript h = hidden layer
+
+def sigmoid(x):
+    return 1/(1 + np.exp(-x))
+
+def feed_forward(X):
+    # weighted sum of inputs to the hidden layer
+    z_h = np.matmul(X, hidden_weights) + hidden_bias
+    # activation in the hidden layer
+    a_h = sigmoid(z_h)
+    
+    # weighted sum of inputs to the output layer
+    z_o = np.matmul(a_h, output_weights) + output_bias
+    # softmax output
+    # axis 0 holds each input and axis 1 the probabilities of each category
+    exp_term = np.exp(z_o)
+    probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+    
+    return probabilities
+
+probabilities = feed_forward(X_train)
+print("probabilities = (n_inputs, n_categories) = " + str(probabilities.shape))
+print("probability that image 0 is in category 0,1,2,...,9 = \n" + str(probabilities[0]))
+print("probabilities sum up to: " + str(probabilities[0].sum()))
+print()
+
+# we obtain a prediction by taking the class with the highest likelihood
+def predict(X):
+    probabilities = feed_forward(X)
+    return np.argmax(probabilities, axis=1)
+
+predictions = predict(X_train)
+print("predictions = (n_inputs) = " + str(predictions.shape))
+print("prediction for image 0: " + str(predictions[0]))
+print("correct label for image 0: " + str(Y_train[0]))
+
      +

      +









      + +

      Choose cost function and optimizer

      + +

      +To measure how well our neural network is doing we need to introduce a cost function. +We will call the function that gives the error of a single sample output the loss function, and the function +that gives the total error of our network across all samples the cost function. +A typical choice for multiclass classification is the cross-entropy loss, also known as the negative log likelihood. + +

      +In multiclass classification it is common to treat each integer label as a so called one-hot vector: + +$$ y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) ,$$ + +$$ y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) ,$$ + +

      +i.e. a binary bit string of length \( C \), where \( C = 10 \) is the number of classes in the MNIST dataset. + +

      +Let \( y_{ic} \) denote the \( c \)-th component of the \( i \)-th one-hot vector. +We define the cost function \( \mathcal{C} \) as a sum over the cross-entropy loss for each point \( \hat{x}_i \) in the dataset. + +

      +In the one-hot representation only one of the terms in the loss function is non-zero, namely the +probability of the correct category \( c' \) +(i.e. the category \( c' \) such that \( y_{ic'} = 1 \)). This means that the cross entropy loss only punishes you for how wrong +you got the correct label. The probability of category \( c \) is given by the softmax function. The vector \( \hat{\theta} \) represents the parameters of our network, i.e. all the weights and biases. + +

      +









      + +

      Optimizing the cost function

      + +

      +The network is trained by finding the weights and biases that minimize the cost function. One of the most widely used classes of methods is gradient descent and its generalizations. The idea behind gradient descent +is simply to adjust the weights in the direction where the gradient of the cost function is large and negative. This ensures we flow toward a local minimum of the cost function. +Each parameter \( \theta \) is iteratively adjusted according to the rule + +$$ \theta_{i+1} = \theta_i - \eta \nabla \mathcal{C}(\theta_i) ,$$ + +

      +where \( \eta \) is known as the learning rate, which controls how big a step we take towards the minimum. +This update can be repeated for any number of iterations, or until we are satisfied with the result. + +

      +A simple and effective improvement is a variant called Batch Gradient Descent. +Instead of calculating the gradient on the whole dataset, we calculate an approximation of the gradient +on a subset of the data called a minibatch. +If there are \( N \) data points and we have a minibatch size of \( M \), the total number of batches +is \( N/M \). +We denote each minibatch \( B_k \), with \( k = 1, 2,...,N/M \). The gradient then becomes: + +$$ \nabla \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \nabla \mathcal{L}_i(\theta) \quad \rightarrow \quad +\frac{1}{M} \sum_{i \in B_k} \nabla \mathcal{L}_i(\theta) ,$$ + +

      +i.e. instead of averaging the loss over the entire dataset, we average over a minibatch. + +

      +This has two important benefits: + +

        +
      1. Introducing stochasticity decreases the chance that the algorithm becomes stuck in a local minima.
        2. +
      2. It significantly speeds up the calculation, since we do not have to use the entire dataset to calculate the gradient.
        3. +
      + +The various optmization methods, with codes and algorithms, are discussed in our lectures on Gradient descent approaches. + +

      + + +

      Regularization

      + +

      +It is common to add an extra term to the cost function, proportional +to the size of the weights. This is equivalent to constraining the +size of the weights, so that they do not grow out of control. +Constraining the size of the weights means that the weights cannot +grow arbitrarily large to fit the training data, and in this way +reduces overfitting. + +

      +We will measure the size of the weights using the so called L2-norm, meaning our cost function becomes: + +$$ \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \mathcal{L}_i(\theta) \quad \rightarrow \quad +\frac{1}{N} \sum_{i=1}^N \mathcal{L}_i(\theta) + \lambda \lvert \lvert \hat{w} \rvert \rvert_2^2 += \frac{1}{N} \sum_{i=1}^N \mathcal{L}(\theta) + \lambda \sum_{ij} w_{ij}^2,$$ + +

      +i.e. we sum up all the weights squared. The factor \( \lambda \) is known as a regularization parameter. + +

      +In order to train the model, we need to calculate the derivative of +the cost function with respect to every bias and weight in the +network. In total our network has \( (64 + 1)\times 50=3250 \) weights in +the hidden layer and \( (50 + 1)\times 10=510 \) weights to the output +layer (\( +1 \) for the bias), and the gradient must be calculated for +every parameter. We use the backpropagation algorithm discussed +above. This is a clever use of the chain rule that allows us to +calculate the gradient efficently. + +

      +









      + +

      Matrix multiplication

      + +

      +To more efficently train our network these equations are implemented using matrix operations. +The error in the output layer is calculated simply as, with \( \hat{t} \) being our targets, + +$$ \delta_L = \hat{t} - \hat{y} = (n_{inputs}, n_{categories}) .$$ + +

      +The gradient for the output weights is calculated as + +$$ \nabla W_{L} = \hat{a}^T \delta_L = (n_{hidden}, n_{categories}) ,$$ + +

      +where \( \hat{a} = (n_{inputs}, n_{hidden}) \). This simply means that we are summing up the gradients for each input. +Since we are going backwards we have to transpose the activation matrix. + +

      +The gradient with respect to the output bias is then + +$$ \nabla \hat{b}_{L} = \sum_{i=1}^{n_{inputs}} \delta_L = (n_{categories}) .$$ + +

      +The error in the hidden layer is + +$$ \Delta_h = \delta_L W_{L}^T \circ f'(z_{h}) = \delta_L W_{L}^T \circ a_{h} \circ (1 - a_{h}) = (n_{inputs}, n_{hidden}) ,$$ + +

      +where \( f'(a_{h}) \) is the derivative of the activation in the hidden layer. The matrix products mean +that we are summing up the products for each neuron in the output layer. The symbol \( \circ \) denotes +the Hadamard product, meaning element-wise multiplication. + +

      +This again gives us the gradients in the hidden layer: + +$$ \nabla W_{h} = X^T \delta_h = (n_{features}, n_{hidden}) ,$$ + +$$ \nabla b_{h} = \sum_{i=1}^{n_{inputs}} \delta_h = (n_{hidden}) .$$ + +

      + + +

      # to categorical turns our integer vector into a onehot representation
+from sklearn.metrics import accuracy_score
+
+# one-hot in numpy
+def to_categorical_numpy(integer_vector):
+    n_inputs = len(integer_vector)
+    n_categories = np.max(integer_vector) + 1
+    onehot_vector = np.zeros((n_inputs, n_categories))
+    onehot_vector[range(n_inputs), integer_vector] = 1
+    
+    return onehot_vector
+
+#Y_train_onehot, Y_test_onehot = to_categorical(Y_train), to_categorical(Y_test)
+Y_train_onehot, Y_test_onehot = to_categorical_numpy(Y_train), to_categorical_numpy(Y_test)
+
+def feed_forward_train(X):
+    # weighted sum of inputs to the hidden layer
+    z_h = np.matmul(X, hidden_weights) + hidden_bias
+    # activation in the hidden layer
+    a_h = sigmoid(z_h)
+    
+    # weighted sum of inputs to the output layer
+    z_o = np.matmul(a_h, output_weights) + output_bias
+    # softmax output
+    # axis 0 holds each input and axis 1 the probabilities of each category
+    exp_term = np.exp(z_o)
+    probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+    
+    # for backpropagation need activations in hidden and output layers
+    return a_h, probabilities
+
+def backpropagation(X, Y):
+    a_h, probabilities = feed_forward_train(X)
+    
+    # error in the output layer
+    error_output = probabilities - Y
+    # error in the hidden layer
+    error_hidden = np.matmul(error_output, output_weights.T) * a_h * (1 - a_h)
+    
+    # gradients for the output layer
+    output_weights_gradient = np.matmul(a_h.T, error_output)
+    output_bias_gradient = np.sum(error_output, axis=0)
+    
+    # gradient for the hidden layer
+    hidden_weights_gradient = np.matmul(X.T, error_hidden)
+    hidden_bias_gradient = np.sum(error_hidden, axis=0)
+
+    return output_weights_gradient, output_bias_gradient, hidden_weights_gradient, hidden_bias_gradient
+
+print("Old accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train)))
+
+eta = 0.01
+lmbd = 0.01
+for i in range(1000):
+    # calculate gradients
+    dWo, dBo, dWh, dBh = backpropagation(X_train, Y_train_onehot)
+    
+    # regularization term gradients
+    dWo += lmbd * output_weights
+    dWh += lmbd * hidden_weights
+    
+    # update weights and biases
+    output_weights -= eta * dWo
+    output_bias -= eta * dBo
+    hidden_weights -= eta * dWh
+    hidden_bias -= eta * dBh
+
+print("New accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train)))
+
      +

      +









      + +

      Improving performance

      + +

      +As we can see the network does not seem to be learning at all. It seems to be just guessing the label for each image. +In order to obtain a network that does something useful, we will have to do a bit more work. + +

      +The choice of hyperparameters such as learning rate and regularization parameter is hugely influential for the performance of the network. Typically a grid-search is performed, wherein we test different hyperparameters separated by orders of magnitude. For example we could test the learning rates \( \eta = 10^{-6}, 10^{-5},...,10^{-1} \) with different regularization parameters \( \lambda = 10^{-6},...,10^{-0} \). + +

      +Next, we haven't implemented minibatching yet, which introduces stochasticity and is though to act as an important regularizer on the weights. We call a feed-forward + backward pass with a minibatch an iteration, and a full training period +going through the entire dataset (\( n/M \) batches) an epoch. + +

      +If this does not improve network performance, you may want to consider altering the network architecture, adding more neurons or hidden layers. +Andrew Ng goes through some of these considerations in this video. You can find a summary of the video here. + +

      +









      + +

      Full object-oriented implementation

      + +

      +It is very natural to think of the network as an object, with specific instances of the network +being realizations of this object with different hyperparameters. An implementation using Python classes provides a clean structure and interface, and the full implementation of our neural network is given below. + +

      + + +

      class NeuralNetwork:
+    def __init__(
+            self,
+            X_data,
+            Y_data,
+            n_hidden_neurons=50,
+            n_categories=10,
+            epochs=10,
+            batch_size=100,
+            eta=0.1,
+            lmbd=0.0):
+
+        self.X_data_full = X_data
+        self.Y_data_full = Y_data
+
+        self.n_inputs = X_data.shape[0]
+        self.n_features = X_data.shape[1]
+        self.n_hidden_neurons = n_hidden_neurons
+        self.n_categories = n_categories
+
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self.iterations = self.n_inputs // self.batch_size
+        self.eta = eta
+        self.lmbd = lmbd
+
+        self.create_biases_and_weights()
+
+    def create_biases_and_weights(self):
+        self.hidden_weights = np.random.randn(self.n_features, self.n_hidden_neurons)
+        self.hidden_bias = np.zeros(self.n_hidden_neurons) + 0.01
+
+        self.output_weights = np.random.randn(self.n_hidden_neurons, self.n_categories)
+        self.output_bias = np.zeros(self.n_categories) + 0.01
+
+    def feed_forward(self):
+        # feed-forward for training
+        self.z_h = np.matmul(self.X_data, self.hidden_weights) + self.hidden_bias
+        self.a_h = sigmoid(self.z_h)
+
+        self.z_o = np.matmul(self.a_h, self.output_weights) + self.output_bias
+
+        exp_term = np.exp(self.z_o)
+        self.probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+
+    def feed_forward_out(self, X):
+        # feed-forward for output
+        z_h = np.matmul(X, self.hidden_weights) + self.hidden_bias
+        a_h = sigmoid(z_h)
+
+        z_o = np.matmul(a_h, self.output_weights) + self.output_bias
+        
+        exp_term = np.exp(z_o)
+        probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)
+        return probabilities
+
+    def backpropagation(self):
+        error_output = self.probabilities - self.Y_data
+        error_hidden = np.matmul(error_output, self.output_weights.T) * self.a_h * (1 - self.a_h)
+
+        self.output_weights_gradient = np.matmul(self.a_h.T, error_output)
+        self.output_bias_gradient = np.sum(error_output, axis=0)
+
+        self.hidden_weights_gradient = np.matmul(self.X_data.T, error_hidden)
+        self.hidden_bias_gradient = np.sum(error_hidden, axis=0)
+
+        if self.lmbd > 0.0:
+            self.output_weights_gradient += self.lmbd * self.output_weights
+            self.hidden_weights_gradient += self.lmbd * self.hidden_weights
+
+        self.output_weights -= self.eta * self.output_weights_gradient
+        self.output_bias -= self.eta * self.output_bias_gradient
+        self.hidden_weights -= self.eta * self.hidden_weights_gradient
+        self.hidden_bias -= self.eta * self.hidden_bias_gradient
+
+    def predict(self, X):
+        probabilities = self.feed_forward_out(X)
+        return np.argmax(probabilities, axis=1)
+
+    def predict_probabilities(self, X):
+        probabilities = self.feed_forward_out(X)
+        return probabilities
+
+    def train(self):
+        data_indices = np.arange(self.n_inputs)
+
+        for i in range(self.epochs):
+            for j in range(self.iterations):
+                # pick datapoints with replacement
+                chosen_datapoints = np.random.choice(
+                    data_indices, size=self.batch_size, replace=False
+                )
+
+                # minibatch training data
+                self.X_data = self.X_data_full[chosen_datapoints]
+                self.Y_data = self.Y_data_full[chosen_datapoints]
+
+                self.feed_forward()
+                self.backpropagation()
+
      +

      +









      + +

      Evaluate model performance on test data

      + +

      +To measure the performance of our network we evaluate how well it does it data it has never seen before, i.e. the test data. +We measure the performance of the network using the accuracy score. +The accuracy is as you would expect just the number of images correctly labeled divided by the total number of images. A perfect classifier will have an accuracy score of \( 1 \). + +$$ \text{Accuracy} = \frac{\sum_{i=1}^n I(\hat{y}_i = y_i)}{n} ,$$ + +

      +where \( I \) is the indicator function, \( 1 \) if \( \hat{y}_i = y_i \) and \( 0 \) otherwise. + +

      + + +

      epochs = 100
+batch_size = 100
+
+dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size,
+                    n_hidden_neurons=n_hidden_neurons, n_categories=n_categories)
+dnn.train()
+test_predict = dnn.predict(X_test)
+
+# accuracy score from scikit library
+print("Accuracy score on test set: ", accuracy_score(Y_test, test_predict))
+
+# equivalent in numpy
+def accuracy_score_numpy(Y_test, Y_pred):
+    return np.sum(Y_test == Y_pred) / len(Y_test)
+
+#print("Accuracy score on test set: ", accuracy_score_numpy(Y_test, test_predict))
+
      +

      +









      + +

      Adjust hyperparameters

      + +

      +We now perform a grid search to find the optimal hyperparameters for the network. +Note that we are only using 1 layer with 50 neurons, and human performance is estimated to be around \( 98\% \) (\( 2\% \) error rate). + +

      + + +

      eta_vals = np.logspace(-5, 1, 7)
+lmbd_vals = np.logspace(-5, 1, 7)
+# store the models for later use
+DNN_numpy = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+
+# grid search
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size,
+                            n_hidden_neurons=n_hidden_neurons, n_categories=n_categories)
+        dnn.train()
+        
+        DNN_numpy[i][j] = dnn
+        
+        test_predict = dnn.predict(X_test)
+        
+        print("Learning rate  = ", eta)
+        print("Lambda = ", lmbd)
+        print("Accuracy score on test set: ", accuracy_score(Y_test, test_predict))
+        print()
+
      +

      +









      + +

      Visualization

      + +

      + + +

      # visual representation of grid search
+# uses seaborn heatmap, you can also do this with matplotlib imshow
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        dnn = DNN_numpy[i][j]
+        
+        train_pred = dnn.predict(X_train) 
+        test_pred = dnn.predict(X_test)
+
+        train_accuracy[i][j] = accuracy_score(Y_train, train_pred)
+        test_accuracy[i][j] = accuracy_score(Y_test, test_pred)
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
      +

      +









      + +

      scikit-learn implementation

      + +

      +scikit-learn focuses more +on traditional machine learning methods, such as regression, +clustering, decision trees, etc. As such, it has only two types of +neural networks: Multi Layer Perceptron outputting continuous values, +MPLRegressor, and Multi Layer Perceptron outputting labels, +MLPClassifier. We will see how simple it is to use these classes. + +

      +scikit-learn implements a few improvements from our neural network, +such as early stopping, a varying learning rate, different +optimization methods, etc. We would therefore expect a better +performance overall. + +

      + + +

      from sklearn.neural_network import MLPClassifier
+# store models for later use
+DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        dnn = MLPClassifier(hidden_layer_sizes=(n_hidden_neurons), activation='logistic',
+                            alpha=lmbd, learning_rate_init=eta, max_iter=epochs)
+        dnn.fit(X_train, Y_train)
+        
+        DNN_scikit[i][j] = dnn
+        
+        print("Learning rate  = ", eta)
+        print("Lambda = ", lmbd)
+        print("Accuracy score on test set: ", dnn.score(X_test, Y_test))
+        print()
+
      +

      +









      + +

      Visualization

      +

      + + +

      # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        dnn = DNN_scikit[i][j]
+        
+        train_pred = dnn.predict(X_train) 
+        test_pred = dnn.predict(X_test)
+
+        train_accuracy[i][j] = accuracy_score(Y_train, train_pred)
+        test_accuracy[i][j] = accuracy_score(Y_test, test_pred)
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
      +

      +









      + +

      Building neural networks in Tensorflow and Keras

      + +

      +Now we want to build on the experience gained from our neural network implementation in NumPy and scikit-learn +and use it to construct a neural network in Tensorflow. Once we have constructed a neural network in NumPy +and Tensorflow, building one in Keras is really quite trivial, though the performance may suffer. + +

      +In our previous example we used only one hidden layer, and in this we will use two. From this it should be quite +clear how to build one using an arbitrary number of hidden layers, using data structures such as Python lists or +NumPy arrays. + +

      +









      + +

      Tensorflow

      + +

      +Tensorflow is an open source library machine learning library +developed by the Google Brain team for internal use. It was released +under the Apache 2.0 open source license in November 9, 2015. + +

      +Tensorflow is a computational framework that allows you to construct +machine learning models at different levels of abstraction, from +high-level, object-oriented APIs like Keras, down to the C++ kernels +that Tensorflow is built upon. The higher levels of abstraction are +simpler to use, but less flexible, and our choice of implementation +should reflect the problems we are trying to solve. + +

      +Tensorflow uses so-called graphs to represent your computation +in terms of the dependencies between individual operations, such that you first build a Tensorflow graph +to represent your model, and then create a Tensorflow session to run the graph. + +

      +In this guide we will analyze the same data as we did in our NumPy and +scikit-learn tutorial, gathered from the MNIST database of images. We +will give an introduction to the lower level Python Application +Program Interfaces (APIs), and see how we use them to build our graph. +Then we will build (effectively) the same graph in Keras, to see just +how simple solving a machine learning problem can be. + +

      +To install tensorflow on Unix/Linux systems, use pip as +

      + + +

      pip3 install tensorflow
+
      +

      +and/or if you use anaconda, just write (or install from the graphical user interface) +

      + + +

      conda install tensorflow
+
      +

      +









      + +

      Collect and pre-process data

      + +

      + + +

      # import necessary packages
+import numpy as np
+import matplotlib.pyplot as plt
+from sklearn import datasets
+
+
+# ensure the same random numbers appear every time
+np.random.seed(0)
+
+# display images in notebook
+%matplotlib inline
+plt.rcParams['figure.figsize'] = (12,12)
+
+
+# download MNIST dataset
+digits = datasets.load_digits()
+
+# define inputs and labels
+inputs = digits.images
+labels = digits.target
+
+print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape))
+print("labels = (n_inputs) = " + str(labels.shape))
+
+
+# flatten the image
+# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64
+n_inputs = len(inputs)
+inputs = inputs.reshape(n_inputs, -1)
+print("X = (n_inputs, n_features) = " + str(inputs.shape))
+
+
+# choose some random images to display
+indices = np.arange(n_inputs)
+random_indices = np.random.choice(indices, size=5)
+
+for i, image in enumerate(digits.images[random_indices]):
+    plt.subplot(1, 5, i+1)
+    plt.axis('off')
+    plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')
+    plt.title("Label: %d" % digits.target[random_indices[i]])
+plt.show()
+
      +

      + + +

      from keras.utils import to_categorical
+from sklearn.model_selection import train_test_split
+
+# one-hot representation of labels
+labels = to_categorical(labels)
+
+# split into train and test data
+train_size = 0.8
+test_size = 1 - train_size
+X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,
+                                                    test_size=test_size)
+
      +

      +









      + +

      Using TensorFlow backend

      + +
        +
      1. Define model and architecture
        2. +
      2. Choose cost function and optimizer
        3. +
      + +

      + + +

      import tensorflow as tf
+
+class NeuralNetworkTensorflow:
+    def __init__(
+            self,
+            X_train,
+            Y_train,
+            X_test,
+            Y_test,
+            n_neurons_layer1=100,
+            n_neurons_layer2=50,
+            n_categories=2,
+            epochs=10,
+            batch_size=100,
+            eta=0.1,
+            lmbd=0.0):
+        
+        # keep track of number of steps
+        self.global_step = tf.Variable(0, dtype=tf.int32, trainable=False, name='global_step')
+        
+        self.X_train = X_train
+        self.Y_train = Y_train
+        self.X_test = X_test
+        self.Y_test = Y_test
+        
+        self.n_inputs = X_train.shape[0]
+        self.n_features = X_train.shape[1]
+        self.n_neurons_layer1 = n_neurons_layer1
+        self.n_neurons_layer2 = n_neurons_layer2
+        self.n_categories = n_categories
+        
+        self.epochs = epochs
+        self.batch_size = batch_size
+        self.iterations = self.n_inputs // self.batch_size
+        self.eta = eta
+        self.lmbd = lmbd
+        
+        # build network piece by piece
+        # name scopes (with) are used to enforce creation of new variables
+        # https://www.tensorflow.org/guide/variables
+        self.create_placeholders()
+        self.create_DNN()
+        self.create_loss()
+        self.create_optimiser()
+        self.create_accuracy()
+    
+    def create_placeholders(self):
+        # placeholders are fine here, but "Datasets" are the preferred method
+        # of streaming data into a model
+        with tf.name_scope('data'):
+            self.X = tf.placeholder(tf.float32, shape=(None, self.n_features), name='X_data')
+            self.Y = tf.placeholder(tf.float32, shape=(None, self.n_categories), name='Y_data')
+    
+    def create_DNN(self):
+        with tf.name_scope('DNN'):
+            # the weights are stored to calculate regularization loss later
+            
+            # Fully connected layer 1
+            self.W_fc1 = self.weight_variable([self.n_features, self.n_neurons_layer1], name='fc1', dtype=tf.float32)
+            b_fc1 = self.bias_variable([self.n_neurons_layer1], name='fc1', dtype=tf.float32)
+            a_fc1 = tf.nn.sigmoid(tf.matmul(self.X, self.W_fc1) + b_fc1)
+            
+            # Fully connected layer 2
+            self.W_fc2 = self.weight_variable([self.n_neurons_layer1, self.n_neurons_layer2], name='fc2', dtype=tf.float32)
+            b_fc2 = self.bias_variable([self.n_neurons_layer2], name='fc2', dtype=tf.float32)
+            a_fc2 = tf.nn.sigmoid(tf.matmul(a_fc1, self.W_fc2) + b_fc2)
+            
+            # Output layer
+            self.W_out = self.weight_variable([self.n_neurons_layer2, self.n_categories], name='out', dtype=tf.float32)
+            b_out = self.bias_variable([self.n_categories], name='out', dtype=tf.float32)
+            self.z_out = tf.matmul(a_fc2, self.W_out) + b_out
+    
+    def create_loss(self):
+        with tf.name_scope('loss'):
+            softmax_loss = tf.reduce_mean(tf.nn.softmax_cross_entropy_with_logits_v2(labels=self.Y, logits=self.z_out))
+            
+            regularizer_loss_fc1 = tf.nn.l2_loss(self.W_fc1)
+            regularizer_loss_fc2 = tf.nn.l2_loss(self.W_fc2)
+            regularizer_loss_out = tf.nn.l2_loss(self.W_out)
+            regularizer_loss = self.lmbd*(regularizer_loss_fc1 + regularizer_loss_fc2 + regularizer_loss_out)
+            
+            self.loss = softmax_loss + regularizer_loss
+
+    def create_accuracy(self):
+        with tf.name_scope('accuracy'):
+            probabilities = tf.nn.softmax(self.z_out)
+            predictions = tf.argmax(probabilities, axis=1)
+            labels = tf.argmax(self.Y, axis=1)
+            
+            correct_predictions = tf.equal(predictions, labels)
+            correct_predictions = tf.cast(correct_predictions, tf.float32)
+            self.accuracy = tf.reduce_mean(correct_predictions)
+    
+    def create_optimiser(self):
+        with tf.name_scope('optimizer'):
+            self.optimizer = tf.train.GradientDescentOptimizer(learning_rate=self.eta).minimize(self.loss, global_step=self.global_step)
+            
+    def weight_variable(self, shape, name='', dtype=tf.float32):
+        initial = tf.truncated_normal(shape, stddev=0.1)
+        return tf.Variable(initial, name=name, dtype=dtype)
+    
+    def bias_variable(self, shape, name='', dtype=tf.float32):
+        initial = tf.constant(0.1, shape=shape)
+        return tf.Variable(initial, name=name, dtype=dtype)
+    
+    def fit(self):
+        data_indices = np.arange(self.n_inputs)
+
+        with tf.Session() as sess:
+            sess.run(tf.global_variables_initializer())
+            for i in range(self.epochs):
+                for j in range(self.iterations):
+                    chosen_datapoints = np.random.choice(data_indices, size=self.batch_size, replace=False)
+                    batch_X, batch_Y = self.X_train[chosen_datapoints], self.Y_train[chosen_datapoints]
+            
+                    sess.run([DNN.loss, DNN.optimizer],
+                        feed_dict={DNN.X: batch_X,
+                                   DNN.Y: batch_Y})
+                    accuracy = sess.run(DNN.accuracy,
+                        feed_dict={DNN.X: batch_X,
+                                   DNN.Y: batch_Y})
+                    step = sess.run(DNN.global_step)
+    
+            self.train_loss, self.train_accuracy = sess.run([DNN.loss, DNN.accuracy],
+                feed_dict={DNN.X: self.X_train,
+                           DNN.Y: self.Y_train})
+        
+            self.test_loss, self.test_accuracy = sess.run([DNN.loss, DNN.accuracy],
+                feed_dict={DNN.X: self.X_test,
+                           DNN.Y: self.Y_test})
+
      +

      +









      + +

      Optimizing and using gradient descent

      + +

      + + +

      epochs = 100
+batch_size = 100
+n_neurons_layer1 = 100
+n_neurons_layer2 = 50
+n_categories = 10
+eta_vals = np.logspace(-5, 1, 7)
+lmbd_vals = np.logspace(-5, 1, 7)
+
      +

      + + +

      DNN_tf = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+        
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        DNN = NeuralNetworkTensorflow(X_train, Y_train, X_test, Y_test,
+                                      n_neurons_layer1, n_neurons_layer2, n_categories,
+                                      epochs=epochs, batch_size=batch_size, eta=eta, lmbd=lmbd)
+        DNN.fit()
+        
+        DNN_tf[i][j] = DNN
+        
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % DNN.test_accuracy)
+        print()
+
      +

      + + +

      # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        DNN = DNN_tf[i][j]
+
+        train_accuracy[i][j] = DNN.train_accuracy
+        test_accuracy[i][j] = DNN.test_accuracy
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
      +

      + + +

      # optional
+# we can use log files to visualize our graph in Tensorboard
+writer = tf.summary.FileWriter('logs/')
+writer.add_graph(tf.get_default_graph())
+
      +

      +









      + +

      Using Keras

      + +

      +Keras is a high level neural network +that supports Tensorflow, CTNK and Theano as backends. +If you have Tensorflow installed Keras is available through the tf.keras module. +If you have Anaconda installed you may run the following command +

      + + +

      conda install keras
+
      +

      +Alternatively, if you have Tensorflow or one of the other supported backends install you may use the pip package manager: + +

      + + +

      pip3 install keras
+
      +

      +or look up the instructions here. + +

      + + +

      from keras.models import Sequential
+from keras.layers import Dense
+from keras.regularizers import l2
+from keras.optimizers import SGD
+
+def create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories, eta, lmbd):
+    model = Sequential()
+    model.add(Dense(n_neurons_layer1, activation='sigmoid', kernel_regularizer=l2(lmbd)))
+    model.add(Dense(n_neurons_layer2, activation='sigmoid', kernel_regularizer=l2(lmbd)))
+    model.add(Dense(n_categories, activation='softmax'))
+    
+    sgd = SGD(lr=eta)
+    model.compile(loss='categorical_crossentropy', optimizer=sgd, metrics=['accuracy'])
+    
+    return model
+
      +

      + + +

      DNN_keras = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)
+        
+for i, eta in enumerate(eta_vals):
+    for j, lmbd in enumerate(lmbd_vals):
+        DNN = create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories,
+                                         eta=eta, lmbd=lmbd)
+        DNN.fit(X_train, Y_train, epochs=epochs, batch_size=batch_size, verbose=0)
+        scores = DNN.evaluate(X_test, Y_test)
+        
+        DNN_keras[i][j] = DNN
+        
+        print("Learning rate = ", eta)
+        print("Lambda = ", lmbd)
+        print("Test accuracy: %.3f" % scores[1])
+        print()
+
      +

      + + +

      # optional
+# visual representation of grid search
+# uses seaborn heatmap, could probably do this in matplotlib
+import seaborn as sns
+
+sns.set()
+
+train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))
+
+for i in range(len(eta_vals)):
+    for j in range(len(lmbd_vals)):
+        DNN = DNN_keras[i][j]
+
+        train_accuracy[i][j] = DNN.evaluate(X_train, Y_train)[1]
+        test_accuracy[i][j] = DNN.evaluate(X_test, Y_test)[1]
+
+        
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Training Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
+fig, ax = plt.subplots(figsize = (10, 10))
+sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis")
+ax.set_title("Test Accuracy")
+ax.set_ylabel("$\eta$")
+ax.set_xlabel("$\lambda$")
+plt.show()
+
      +

      + + +

      Which activation function should I use?

      + +

      +The Back propagation algorithm we derived above works by going from +the output layer to the input layer, propagating the error gradient on +the way. Once the algorithm has computed the gradient of the cost +function with regards to each parameter in the network, it uses these +gradients to update each parameter with a Gradient Descent (GD) step. + +

      +Unfortunately for us, the gradients often get smaller and smaller as the +algorithm progresses down to the first hidden layers. As a result, the +GD update leaves the lower layer connection weights +virtually unchanged, and training never converges to a good +solution. This is known in the literature as +the vanishing gradients problem. + +

      +In other cases, the opposite can happen, namely the the gradients can grow bigger and +bigger. The result is that many of the layers get large updates of the +weights the +algorithm diverges. This is the exploding gradients problem, which is +mostly encountered in recurrent neural networks. More generally, deep +neural networks suffer from unstable gradients, different layers may +learn at widely different speeds + +

      + + +

      Is the Logistic activation function (Sigmoid) our choice?

      + +

      +Although this unfortunate behavior has been empirically observed for +quite a while (it was one of the reasons why deep neural networks were +mostly abandoned for a long time), it is only around 2010 that +significant progress was made in understanding it. + +

      +A paper titled Understanding the Difficulty of Training Deep +Feedforward Neural Networks by Xavier Glorot and Yoshua Bengio found that +the problems with the popular logistic +sigmoid activation function and the weight initialization technique +that was most popular at the time, namely random initialization using +a normal distribution with a mean of 0 and a standard deviation of +1. + +

      +They showed that with this activation function and this +initialization scheme, the variance of the outputs of each layer is +much greater than the variance of its inputs. Going forward in the +network, the variance keeps increasing after each layer until the +activation function saturates at the top layers. This is actually made +worse by the fact that the logistic function has a mean of 0.5, not 0 +(the hyperbolic tangent function has a mean of 0 and behaves slightly +better than the logistic function in deep networks). + +

      +









      + +

      The derivative of the Logistic funtion

      + +

      +Looking at the logistic activation function, when inputs become large +(negative or positive), the function saturates at 0 or 1, with a +derivative extremely close to 0. Thus when backpropagation kicks in, +it has virtually no gradient to propagate back through the network, +and what little gradient exists keeps getting diluted as +backpropagation progresses down through the top layers, so there is +really nothing left for the lower layers. + +

      +In their paper, Glorot and Bengio propose a way to significantly +alleviate this problem. We need the signal to flow properly in both +directions: in the forward direction when making predictions, and in +the reverse direction when backpropagating gradients. We don’t want +the signal to die out, nor do we want it to explode and saturate. For +the signal to flow properly, the authors argue that we need the +variance of the outputs of each layer to be equal to the variance of +its inputs, and we also need the gradients to have equal variance +before and after flowing through a layer in the reverse direction. + +

      +One of the insights in the 2010 paper by Glorot and Bengio was that +the vanishing/exploding gradients problems were in part due to a poor +choice of activation function. Until then most people had assumed that +if Nature had chosen to use roughly sigmoid activation functions in +biological neurons, they must be an excellent choice. But it turns out +that other activation functions behave much better in deep neural +networks, in particular the ReLU activation function, mostly because +it does not saturate for positive values (and also because it is quite +fast to compute). + +

      +









      + +

      The RELU function family

      + +

      +The ReLU activation function suffers from a problem known as the dying +ReLUs: during training, some neurons effectively die, meaning they +stop outputting anything other than 0. + +

      +In some cases, you may find that half of your network’s neurons are +dead, especially if you used a large learning rate. During training, +if a neuron’s weights get updated such that the weighted sum of the +neuron’s inputs is negative, it will start outputting 0. When this +happen, the neuron is unlikely to come back to life since the gradient +of the ReLU function is 0 when its input is negative. + +

      +To solve this problem, nowadays practitioners use a variant of the ReLU +function, such as the leaky ReLU discussed above or the so-called +exponential linear unit (ELU) function + +$$ +ELU(z) = \left\{\begin{array}{cc} \alpha\left( \exp{(z)}-1\right) & z < 0,\\ z & z \ge 0.\end{array}\right. +$$ + +

      +









      + +

      Which activation function should we use?

      + +

      +In general it seems that the ELU activation function is better than +the leaky ReLU function (and its variants), which is better than +ReLU. ReLU performs better than \( \tanh \) which in turn performs better +than the logistic function. + +

      +If runtime +performance is an issue, then you may opt for the leaky ReLU function over the +ELU function If you don’t +want to tweak yet another hyperparameter, you may just use the default +\( \alpha \) of \( 0.01 \) for the leaky ReLU, and \( 1 \) for ELU. If you have +spare time and computing power, you can use cross-validation or +bootstrap to evaluate other activation functions. + +

      + + +

      A top-down perspective on Neural networks

      + +

      +The first thing we would like to do is divide the data into two or three +parts. A training set, a validation or dev (development) set, and a +test set. The test set is the data on which we want to make +predictions. The dev set is a subset of the training data we use to +check how well we are doing out-of-sample, after training the model on +the training dataset. We use the validation error as a proxy for the +test error in order to make tweaks to our model. It is crucial that we +do not use any of the test data to train the algorithm. This is a +cardinal sin in ML. Then: + +

      + +If the validation and test sets are drawn from the same distributions, +then a good performance on the validation set should lead to similarly +good performance on the test set. + +

      +However, sometimes +the training data and test data differ in subtle ways because, for +example, they are collected using slightly different methods, or +because it is cheaper to collect data in one way versus another. In +this case, there can be a mismatch between the training and test +data. This can lead to the neural network overfitting these small +differences between the test and training sets, and a poor performance +on the test set despite having a good performance on the validation +set. To rectify this, Andrew Ng suggests making two validation or dev +sets, one constructed from the training data and one constructed from +the test data. The difference between the performance of the algorithm +on these two validation sets quantifies the train-test mismatch. This +can serve as another important diagnostic when using DNNs for +supervised learning. + +

      +









      + +

      Limitations of supervised learning with deep networks

      + +

      +Like all statistical methods, supervised learning using neural +networks has important limitations. This is especially important when +one seeks to apply these methods, especially to physics problems. Like +all tools, DNNs are not a universal solution. Often, the same or +better performance on a task can be achieved by using a few +hand-engineered features (or even a collection of random +features). + +

      +Here we list some of the important limitations of supervised neural network based models. + +

      + +Some of these remarks are particular to DNNs, others are shared by all supervised learning methods. This motivates the use of unsupervised methods which in part circumvent these problems. + +

      +









      + +

      Convolutional Neural Networks (recognizing images)

      Convolutional neural networks (CNNs) were developed during the last @@ -159,7 +2091,7 @@ Another good read is the article here Regular NNs don’t scale well to full images +

      Regular NNs don’t scale well to full images

      As an example, consider @@ -187,7 +2119,7 @@ would quickly lead to possible overfitting.











      -

      3D volumes of neurons

      +

      3D volumes of neurons

      Convolutional Neural Networks take advantage of the fact that the @@ -227,7 +2159,7 @@ dimension.

      -

      Layers used to build CNNs

      +

      Layers used to build CNNs

      A simple CNN is a sequence of layers, and every layer of a CNN @@ -250,7 +2182,7 @@ A simple CNN for image classification could have the architecture:









      -

      Transforming images

      +

      Transforming images

      CNNs transform the original image layer by layer from the original @@ -269,7 +2201,7 @@ are consistent with the labels in the training set for each image.











      -

      CNNs in brief

      +

      CNNs in brief

      In summary: @@ -290,7 +2222,7 @@ and the slides of









      -

      CNNs in more detail, building convolutional neural networks in Tensorflow and Keras

      +

      CNNs in more detail, building convolutional neural networks in Tensorflow and Keras

      As discussed above, CNNs are neural networks built from the assumption that the inputs @@ -306,7 +2238,7 @@ matrices, typically 1 for each color dimension (Red, Green, Blue).











      -

      Setting it up

      +

      Setting it up

      It means that to represent the entire @@ -318,7 +2250,7 @@ $$











      -

      The MNIST dataset again

      +

      The MNIST dataset again

      The MNIST dataset consists of grayscale images with a pixel size of @@ -336,7 +2268,7 @@ single neuron in the first hidden layer.











      -

      Strong correlations

      +

      Strong correlations

      Images typically have strong local correlations, meaning that a small part of the image varies little from its neighboring regions. If for example we have an image of a blue car, we can roughly assume that a @@ -352,7 +2284,7 @@ fixed, and known as a       -

      Layers of a CNN

      +

      Layers of a CNN

      The layers of a convolutional neural network arrange neurons in 3D: width, height and depth. The input image is typically a square matrix of depth 3. @@ -374,7 +2306,7 @@ layer.











      -

      Systematic reduction

      +

      Systematic reduction

      By systematically reducing the size of the input volume, through @@ -389,7 +2321,7 @@ classification.











      -

      Prerequisites: Collect and pre-process data

      +

      Prerequisites: Collect and pre-process data

      @@ -418,8 +2350,8 @@ labels = digits # our images are grayscale so they should have a depth of 1 inputs = inputs[:,:,:,np.newaxis] -print("inputs = (n_inputs, pixel_width, pixel_height, depth) = " + str(inputs.shape)) -print("labels = (n_inputs) = " + str(labels.shape)) +print("inputs = (n_inputs, pixel_width, pixel_height, depth) = " + str(inputs.shape)) +print("labels = (n_inputs) = " + str(labels.shape)) # choose some random images to display @@ -437,7 +2369,7 @@ plt.show()











      -

      Importing Keras and Tensorflow

      +

      Importing Keras and Tensorflow

      @@ -457,7 +2389,7 @@ X_train, X_test, Y_train, Y_test = train_tes











      -

      Using TensorFlow backend

      +

      Using TensorFlow backend

      We need to define model and architecture and choose cost function and optmizer. @@ -605,7 +2537,7 @@ class ConvolutionalNeuralNetworkTensorflow:











      -

      Train the model

      +

      Train the model

      We need now to train the model, evaluate it and test its performance on test data, and eventually include hyperparameters. @@ -630,17 +2562,17 @@ CNN_tf = np.=eta, lmbd=lmbd) CNN.fit() - print("Learning rate = ", eta) - print("Lambda = ", lmbd) - print("Test accuracy: %.3f" % CNN.test_accuracy) - print() + print("Learning rate = ", eta) + print("Lambda = ", lmbd) + print("Test accuracy: %.3f" % CNN.test_accuracy) + print() CNN_tf[i][j] = CNN











      -

      Visualizing the results

      +

      Visualizing the results

      @@ -663,14 +2595,14 @@ test_accuracy = np= plt.subplots(figsize = (10, 10)) -sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis") +sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis") ax.set_title("Training Accuracy") ax.set_ylabel("$\eta$") ax.set_xlabel("$\lambda$") plt.show() fig, ax = plt.subplots(figsize = (10, 10)) -sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis") +sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis") ax.set_title("Test Accuracy") ax.set_ylabel("$\eta$") ax.set_xlabel("$\lambda$") @@ -679,7 +2611,7 @@ plt.show()

      -

      Running with Keras

      +

      Running with Keras

      @@ -722,7 +2654,7 @@ lmbd_vals = np.











      -

      Final part

      +

      Final part

      @@ -739,15 +2671,15 @@ lmbd_vals = np. CNN_keras[i][j] = CNN - print("Learning rate = ", eta) - print("Lambda = ", lmbd) - print("Test accuracy: %.3f" % scores[1]) - print() + print("Learning rate = ", eta) + print("Lambda = ", lmbd) + print("Test accuracy: %.3f" % scores[1]) + print()











      -

      Final visualization

      +

      Final visualization

      @@ -786,7 +2718,7 @@ plt.show()











      -

      Fun links

      +

      Fun links

      1. Self-Driving cars using a convolutional neural network
        2. diff --git a/doc/pub/week41/ipynb/ipynb-week41-src.tar.gz b/doc/pub/week41/ipynb/ipynb-week41-src.tar.gz index c6f20f9c738dca7304ca13c092f8dc528fd4c0a2..6b1ffac99524e3618d35e9ee23363c86ea5c16e9 100644 GIT binary patch literal 87344 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 z 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
          FikNFs^j@G-=WXFd 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 M0K=Q!3jmM-02yDoJ^%m! diff --git a/doc/pub/week41/ipynb/week41.ipynb b/doc/pub/week41/ipynb/week41.ipynb index 8230ccc2a..335842002 100644 --- a/doc/pub/week41/ipynb/week41.ipynb +++ b/doc/pub/week41/ipynb/week41.ipynb @@ -10,13 +10,2115 @@ " \n", "**Morten Hjorth-Jensen**, Department of Physics, University of Oslo and Department of Physics and Astronomy and National Superconducting Cyclotron Laboratory, Michigan State University\n", "\n", - "Date: **Sep 16, 2020**\n", + "Date: **Oct 5, 2020**\n", "\n", "Copyright 1999-2020, Morten Hjorth-Jensen. Released under CC Attribution-NonCommercial 4.0 license\n", "\n", "\n", "\n", "\n", + "## Plan for week 40\n", + "\n", + "* Thursday: Building our own Feed-forward Neural Network\n", + "\n", + "* Friday: Playing around with our own Feed-forward Neural Network and introduction to TensorFlow. Start convolutional Neural Networks.\n", + "\n", + "Reading suggestions for both days: [Aurelien Geron's chapters 10-11](https://github.com/CompPhysics/MachineLearning/blob/master/doc/T\\\n", + "extbooks/TensorflowML.pdf) and Hastie et al chapter 11.\n", + "\n", + "## Overview video for week 41\n", + "\n", + "\"Overview Video, from Stochastic Gradient methods to Neural Networks\":\"https://www.uio.no/studier/emner/matnat/fys/FYS-STK3155/h20\\\n", + "/forelesningsvideoer/OverviewWeek41.mp4?vrtx=view-as-webpage\"\n", + "\n", + "\n", + "## Setting up the Back propagation algorithm\n", + "\n", + "\n", + "\n", + "The four equations provide us with a way of computing the gradient of the cost function. Let us write this out in the form of an algorithm.\n", + "\n", + "First, we set up the input data $\\hat{x}$ and the activations\n", + "$\\hat{z}_1$ of the input layer and compute the activation function and\n", + "the pertinent outputs $\\hat{a}^1$.\n", + "\n", + "\n", + "\n", + "Secondly, we perform then the feed forward till we reach the output\n", + "layer and compute all $\\hat{z}_l$ of the input layer and compute the\n", + "activation function and the pertinent outputs $\\hat{a}^l$ for\n", + "$l=2,3,\\dots,L$.\n", + "\n", + "\n", + "\n", + "Thereafter we compute the ouput error $\\hat{\\delta}^L$ by computing all" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\delta_j^L = f'(z_j^L)\\frac{\\partial {\\cal C}}{\\partial (a_j^L)}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Then we compute the back propagate error for each $l=L-1,L-2,\\dots,2$ as" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\delta_j^l = \\sum_k \\delta_k^{l+1}w_{kj}^{l+1}f'(z_j^l).\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Finally, we update the weights and the biases using gradient descent for each $l=L-1,L-2,\\dots,2$ and update the weights and biases according to the rules" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "w_{jk}^l\\leftarrow = w_{jk}^l- \\eta \\delta_j^la_k^{l-1},\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "b_j^l \\leftarrow b_j^l-\\eta \\frac{\\partial {\\cal C}}{\\partial b_j^l}=b_j^l-\\eta \\delta_j^l,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The parameter $\\eta$ is the learning parameter discussed in connection with the gradient descent methods.\n", + "Here it is convenient to use stochastic gradient descent (see the examples below) with mini-batches with an outer loop that steps through multiple epochs of training.\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "## Setting up a Multi-layer perceptron model for classification\n", + "\n", + "We are now gong to develop an example based on the MNIST data\n", + "base. This is a classification problem and we need to use our\n", + "cross-entropy function we discussed in connection with logistic\n", + "regression. The cross-entropy defines our cost function for the\n", + "classificaton problems with neural networks.\n", + "\n", + "In binary classification with two classes $(0, 1)$ we define the\n", + "logistic/sigmoid function as the probability that a particular input\n", + "is in class $0$ or $1$. This is possible because the logistic\n", + "function takes any input from the real numbers and inputs a number\n", + "between 0 and 1, and can therefore be interpreted as a probability. It\n", + "also has other nice properties, such as a derivative that is simple to\n", + "calculate.\n", + "\n", + "For an input $\\boldsymbol{a}$ from the hidden layer, the probability that the input $\\boldsymbol{x}$\n", + "is in class 0 or 1 is just. We let $\\theta$ represent the unknown weights and biases to be adjusted by our equations). The variable $x$\n", + "represents our activation values $z$. We have" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "P(y = 0 \\mid \\hat{x}, \\hat{\\theta}) = \\frac{1}{1 + \\exp{(- \\hat{x}})} ,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "and" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "P(y = 1 \\mid \\hat{x}, \\hat{\\theta}) = 1 - P(y = 0 \\mid \\hat{x}, \\hat{\\theta}) ,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "where $y \\in \\{0, 1\\}$ and $\\hat{\\theta}$ represents the weights and biases\n", + "of our network.\n", + "\n", + "\n", + "## Defining the cost function\n", + "\n", + "Our cost function is given as (see the Logistic regression lectures)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\mathcal{C}(\\hat{\\theta}) = - \\ln P(\\mathcal{D} \\mid \\hat{\\theta}) = - \\sum_{i=1}^n\n", + "y_i \\ln[P(y_i = 0)] + (1 - y_i) \\ln [1 - P(y_i = 0)] = \\sum_{i=1}^n \\mathcal{L}_i(\\hat{\\theta}) .\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This last equality means that we can interpret our *cost* function as a sum over the *loss* function\n", + "for each point in the dataset $\\mathcal{L}_i(\\hat{\\theta})$. \n", + "The negative sign is just so that we can think about our algorithm as minimizing a positive number, rather\n", + "than maximizing a negative number. \n", + "\n", + "In *multiclass* classification it is common to treat each integer label as a so called *one-hot* vector: \n", + "\n", + "$y = 5 \\quad \\rightarrow \\quad \\hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) ,$ and\n", + "\n", + "\n", + "$y = 1 \\quad \\rightarrow \\quad \\hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) ,$ \n", + "\n", + "\n", + "i.e. a binary bit string of length $C$, where $C = 10$ is the number of classes in the MNIST dataset (numbers from $0$ to $9$).. \n", + "\n", + "If $\\hat{x}_i$ is the $i$-th input (image), $y_{ic}$ refers to the $c$-th component of the $i$-th\n", + "output vector $\\hat{y}_i$. \n", + "The probability of $\\hat{x}_i$ being in class $c$ will be given by the softmax function:" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "P(y_{ic} = 1 \\mid \\hat{x}_i, \\hat{\\theta}) = \\frac{\\exp{((\\hat{a}_i^{hidden})^T \\hat{w}_c)}}\n", + "{\\sum_{c'=0}^{C-1} \\exp{((\\hat{a}_i^{hidden})^T \\hat{w}_{c'})}} ,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "which reduces to the logistic function in the binary case. \n", + "The likelihood of this $C$-class classifier\n", + "is now given as:" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "P(\\mathcal{D} \\mid \\hat{\\theta}) = \\prod_{i=1}^n \\prod_{c=0}^{C-1} [P(y_{ic} = 1)]^{y_{ic}} .\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Again we take the negative log-likelihood to define our cost function:" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\mathcal{C}(\\hat{\\theta}) = - \\log{P(\\mathcal{D} \\mid \\hat{\\theta})}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "See the logistic regression lectures for a full definition of the cost function.\n", + "\n", + "The back propagation equations need now only a small change, namely the definition of a new cost function. We are thus ready to use the same equations as before!\n", + "\n", + "## Example: binary classification problem\n", + "\n", + "As an example of the above, relevant for project 2 as well, let us consider a binary class. As discussed in our logistic regression lectures, we defined a cost function in terms of the parameters $\\beta$ as" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\mathcal{C}(\\hat{\\beta}) = - \\sum_{i=1}^n \\left(y_i\\log{p(y_i \\vert x_i,\\hat{\\beta})}+(1-y_i)\\log{1-p(y_i \\vert x_i,\\hat{\\beta})}\\right),\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "where we had defined the logistic (sigmoid) function" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "p(y_i =1\\vert x_i,\\hat{\\beta})=\\frac{\\exp{(\\beta_0+\\beta_1 x_i)}}{1+\\exp{(\\beta_0+\\beta_1 x_i)}},\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "and" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "p(y_i =0\\vert x_i,\\hat{\\beta})=1-p(y_i =1\\vert x_i,\\hat{\\beta}).\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The parameters $\\hat{\\beta}$ were defined using a minimization method like gradient descent or Newton-Raphson's method. \n", + "\n", + "Now we replace $x_i$ with the activation $z_i^l$ for a given layer $l$ and the outputs as $y_i=a_i^l=f(z_i^l)$, with $z_i^l$ now being a function of the weights $w_{ij}^l$ and biases $b_i^l$. \n", + "We have then" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "a_i^l = y_i = \\frac{\\exp{(z_i^l)}}{1+\\exp{(z_i^l)}},\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "with" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "z_i^l = \\sum_{j}w_{ij}^l a_j^{l-1}+b_i^l,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "where the superscript $l-1$ indicates that these are the outputs from layer $l-1$.\n", + "Our cost function at the final layer $l=L$ is now" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\mathcal{C}(\\hat{W}) = - \\sum_{i=1}^n \\left(t_i\\log{a_i^L}+(1-t_i)\\log{(1-a_i^L)}\\right),\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "where we have defined the targets $t_i$. The derivatives of the cost function with respect to the output $a_i^L$ are then easily calculated and we get" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\frac{\\partial \\mathcal{C}(\\hat{W})}{\\partial a_i^L} = \\frac{a_i^L-t_i}{a_i^L(1-a_i^L)}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In case we use another activation function than the logistic one, we need to evaluate other derivatives. \n", + "\n", + "\n", + "## The Softmax function\n", + "In case we employ the more general case given by the Softmax equation, we need to evaluate the derivative of the activation function with respect to the activation $z_i^l$, that is we need" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\frac{\\partial f(z_i^l)}{\\partial w_{jk}^l} =\n", + "\\frac{\\partial f(z_i^l)}{\\partial z_j^l} \\frac{\\partial z_j^l}{\\partial w_{jk}^l}= \\frac{\\partial f(z_i^l)}{\\partial z_j^l}a_k^{l-1}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "For the Softmax function we have" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "f(z_i^l) = \\frac{\\exp{(z_i^l)}}{\\sum_{m=1}^K\\exp{(z_m^l)}}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Its derivative with respect to $z_j^l$ gives" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "\\frac{\\partial f(z_i^l)}{\\partial z_j^l}= f(z_i^l)\\left(\\delta_{ij}-f(z_j^l)\\right),\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "which in case of the simply binary model reduces to having $i=j$. \n", + "\n", + "\n", + "## Developing a code for doing neural networks with back propagation\n", + "\n", + "\n", + "One can identify a set of key steps when using neural networks to solve supervised learning problems: \n", + "\n", + "1. Collect and pre-process data \n", + "\n", + "2. Define model and architecture \n", + "\n", + "3. Choose cost function and optimizer \n", + "\n", + "4. Train the model \n", + "\n", + "5. Evaluate model performance on test data \n", + "\n", + "6. Adjust hyperparameters (if necessary, network architecture)\n", + "\n", + "## Collect and pre-process data\n", + "\n", + "Here we will be using the MNIST dataset, which is readily available through the **scikit-learn**\n", + "package. You may also find it for example [here](http://yann.lecun.com/exdb/mnist/). \n", + "The *MNIST* (Modified National Institute of Standards and Technology) database is a large database\n", + "of handwritten digits that is commonly used for training various image processing systems. \n", + "The MNIST dataset consists of 70 000 images of size $28\\times 28$ pixels, each labeled from 0 to 9. \n", + "The scikit-learn dataset we will use consists of a selection of 1797 images of size $8\\times 8$ collected and processed from this database. \n", + "\n", + "To feed data into a feed-forward neural network we need to represent\n", + "the inputs as a design/feature matrix $X = (n_{inputs}, n_{features})$. Each\n", + "row represents an *input*, in this case a handwritten digit, and\n", + "each column represents a *feature*, in this case a pixel. The\n", + "correct answers, also known as *labels* or *targets* are\n", + "represented as a 1D array of integers \n", + "$Y = (n_{inputs}) = (5, 3, 1, 8,...)$.\n", + "\n", + "As an example, say we want to build a neural network using supervised learning to predict Body-Mass Index (BMI) from\n", + "measurements of height (in m) \n", + "and weight (in kg). If we have measurements of 5 people the design/feature matrix could be for example: \n", + "\n", + "$$ X = \\begin{bmatrix}\n", + "1.85 & 81\\\\\n", + "1.71 & 65\\\\\n", + "1.95 & 103\\\\\n", + "1.55 & 42\\\\\n", + "1.63 & 56\n", + "\\end{bmatrix} ,$$ \n", + "\n", + "and the targets would be: \n", + "\n", + "$$ Y = (23.7, 22.2, 27.1, 17.5, 21.1) $$ \n", + "\n", + "Since each input image is a 2D matrix, we need to flatten the image\n", + "(i.e. \"unravel\" the 2D matrix into a 1D array) to turn the data into a\n", + "design/feature matrix. This means we lose all spatial information in the\n", + "image, such as locality and translational invariance. More complicated\n", + "architectures such as Convolutional Neural Networks can take advantage\n", + "of such information, and are most commonly applied when analyzing\n", + "images." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "\n", + "# import necessary packages\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "from sklearn import datasets\n", + "\n", + "\n", + "# ensure the same random numbers appear every time\n", + "np.random.seed(0)\n", + "\n", + "# display images in notebook\n", + "%matplotlib inline\n", + "plt.rcParams['figure.figsize'] = (12,12)\n", + "\n", + "\n", + "# download MNIST dataset\n", + "digits = datasets.load_digits()\n", + "\n", + "# define inputs and labels\n", + "inputs = digits.images\n", + "labels = digits.target\n", + "\n", + "print(\"inputs = (n_inputs, pixel_width, pixel_height) = \" + str(inputs.shape))\n", + "print(\"labels = (n_inputs) = \" + str(labels.shape))\n", + "\n", + "\n", + "# flatten the image\n", + "# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64\n", + "n_inputs = len(inputs)\n", + "inputs = inputs.reshape(n_inputs, -1)\n", + "print(\"X = (n_inputs, n_features) = \" + str(inputs.shape))\n", + "\n", + "\n", + "# choose some random images to display\n", + "indices = np.arange(n_inputs)\n", + "random_indices = np.random.choice(indices, size=5)\n", + "\n", + "for i, image in enumerate(digits.images[random_indices]):\n", + " plt.subplot(1, 5, i+1)\n", + " plt.axis('off')\n", + " plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')\n", + " plt.title(\"Label: %d\" % digits.target[random_indices[i]])\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Train and test datasets\n", + "\n", + "Performing analysis before partitioning the dataset is a major error, that can lead to incorrect conclusions. \n", + "\n", + "We will reserve $80 \\%$ of our dataset for training and $20 \\%$ for testing. \n", + "\n", + "It is important that the train and test datasets are drawn randomly from our dataset, to ensure\n", + "no bias in the sampling. \n", + "Say you are taking measurements of weather data to predict the weather in the coming 5 days.\n", + "You don't want to train your model on measurements taken from the hours 00.00 to 12.00, and then test it on data\n", + "collected from 12.00 to 24.00." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "from sklearn.model_selection import train_test_split\n", + "\n", + "# one-liner from scikit-learn library\n", + "train_size = 0.8\n", + "test_size = 1 - train_size\n", + "X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,\n", + " test_size=test_size)\n", + "\n", + "# equivalently in numpy\n", + "def train_test_split_numpy(inputs, labels, train_size, test_size):\n", + " n_inputs = len(inputs)\n", + " inputs_shuffled = inputs.copy()\n", + " labels_shuffled = labels.copy()\n", + " \n", + " np.random.shuffle(inputs_shuffled)\n", + " np.random.shuffle(labels_shuffled)\n", + " \n", + " train_end = int(n_inputs*train_size)\n", + " X_train, X_test = inputs_shuffled[:train_end], inputs_shuffled[train_end:]\n", + " Y_train, Y_test = labels_shuffled[:train_end], labels_shuffled[train_end:]\n", + " \n", + " return X_train, X_test, Y_train, Y_test\n", + "\n", + "#X_train, X_test, Y_train, Y_test = train_test_split_numpy(inputs, labels, train_size, test_size)\n", + "\n", + "print(\"Number of training images: \" + str(len(X_train)))\n", + "print(\"Number of test images: \" + str(len(X_test)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Define model and architecture\n", + "\n", + "Our simple feed-forward neural network will consist of an *input* layer, a single *hidden* layer and an *output* layer. The activation $y$ of each neuron is a weighted sum of inputs, passed through an activation function. In case of the simple perceptron model we have \n", + "\n", + "$$ z = \\sum_{i=1}^n w_i a_i ,$$\n", + "\n", + "$$ y = f(z) ,$$\n", + "\n", + "where $f$ is the activation function, $a_i$ represents input from neuron $i$ in the preceding layer\n", + "and $w_i$ is the weight to input $i$. \n", + "The activation of the neurons in the input layer is just the features (e.g. a pixel value). \n", + "\n", + "The simplest activation function for a neuron is the *Heaviside* function:\n", + "\n", + "$$ f(z) = \n", + "\\begin{cases}\n", + "1, & z > 0\\\\\n", + "0, & \\text{otherwise}\n", + "\\end{cases}\n", + "$$\n", + "\n", + "A feed-forward neural network with this activation is known as a *perceptron*. \n", + "For a binary classifier (i.e. two classes, 0 or 1, dog or not-dog) we can also use this in our output layer. \n", + "This activation can be generalized to $k$ classes (using e.g. the *one-against-all* strategy), \n", + "and we call these architectures *multiclass perceptrons*. \n", + "\n", + "However, it is now common to use the terms Single Layer Perceptron (SLP) (1 hidden layer) and \n", + "Multilayer Perceptron (MLP) (2 or more hidden layers) to refer to feed-forward neural networks with any activation function. \n", + "\n", + "Typical choices for activation functions include the sigmoid function, hyperbolic tangent, and Rectified Linear Unit (ReLU). \n", + "We will be using the sigmoid function $\\sigma(x)$: \n", + "\n", + "$$ f(x) = \\sigma(x) = \\frac{1}{1 + e^{-x}} ,$$\n", + "\n", + "which is inspired by probability theory (see logistic regression) and was most commonly used until about 2011. See the discussion below concerning other activation functions.\n", + "\n", + "\n", + "## Layers\n", + "\n", + "* Input \n", + "\n", + "Since each input image has 8x8 = 64 pixels or features, we have an input layer of 64 neurons. \n", + "\n", + "* Hidden layer\n", + "\n", + "We will use 50 neurons in the hidden layer receiving input from the neurons in the input layer. \n", + "Since each neuron in the hidden layer is connected to the 64 inputs we have 64x50 = 3200 weights to the hidden layer. \n", + "\n", + "* Output\n", + "\n", + "If we were building a binary classifier, it would be sufficient with a single neuron in the output layer,\n", + "which could output 0 or 1 according to the Heaviside function. This would be an example of a *hard* classifier, meaning it outputs the class of the input directly. However, if we are dealing with noisy data it is often beneficial to use a *soft* classifier, which outputs the probability of being in class 0 or 1. \n", + "\n", + "For a soft binary classifier, we could use a single neuron and interpret the output as either being the probability of being in class 0 or the probability of being in class 1. Alternatively we could use 2 neurons, and interpret each neuron as the probability of being in each class. \n", + "\n", + "Since we are doing multiclass classification, with 10 categories, it is natural to use 10 neurons in the output layer. We number the neurons $j = 0,1,...,9$. The activation of each output neuron $j$ will be according to the *softmax* function: \n", + "\n", + "$$ P(\\text{class $j$} \\mid \\text{input $\\hat{a}$}) = \\frac{\\exp{(\\hat{a}^T \\hat{w}_j)}}\n", + "{\\sum_{c=0}^{9} \\exp{(\\hat{a}^T \\hat{w}_c)}} ,$$ \n", + "\n", + "i.e. each neuron $j$ outputs the probability of being in class $j$ given an input from the hidden layer $\\hat{a}$, with $\\hat{w}_j$ the weights of neuron $j$ to the inputs. \n", + "The denominator is a normalization factor to ensure the outputs (probabilities) sum up to 1. \n", + "The exponent is just the weighted sum of inputs as before: \n", + "\n", + "$$ z_j = \\sum_{i=1}^n w_ {ij} a_i+b_j.$$ \n", + "\n", + "Since each neuron in the output layer is connected to the 50 inputs from the hidden layer we have 50x10 = 500\n", + "weights to the output layer.\n", + "\n", + "\n", + "## Weights and biases\n", + "\n", + "Typically weights are initialized with small values distributed around zero, drawn from a uniform\n", + "or normal distribution. Setting all weights to zero means all neurons give the same output, making the network useless. \n", + "\n", + "Adding a bias value to the weighted sum of inputs allows the neural network to represent a greater range\n", + "of values. Without it, any input with the value 0 will be mapped to zero (before being passed through the activation). The bias unit has an output of 1, and a weight to each neuron $j$, $b_j$: \n", + "\n", + "$$ z_j = \\sum_{i=1}^n w_ {ij} a_i + b_j.$$ \n", + "\n", + "The bias weights $\\hat{b}$ are often initialized to zero, but a small value like $0.01$ ensures all neurons have some output which can be backpropagated in the first training cycle." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# building our neural network\n", + "\n", + "n_inputs, n_features = X_train.shape\n", + "n_hidden_neurons = 50\n", + "n_categories = 10\n", + "\n", + "# we make the weights normally distributed using numpy.random.randn\n", + "\n", + "# weights and bias in the hidden layer\n", + "hidden_weights = np.random.randn(n_features, n_hidden_neurons)\n", + "hidden_bias = np.zeros(n_hidden_neurons) + 0.01\n", + "\n", + "# weights and bias in the output layer\n", + "output_weights = np.random.randn(n_hidden_neurons, n_categories)\n", + "output_bias = np.zeros(n_categories) + 0.01" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Feed-forward pass\n", + "\n", + "Denote $F$ the number of features, $H$ the number of hidden neurons and $C$ the number of categories. \n", + "For each input image we calculate a weighted sum of input features (pixel values) to each neuron $j$ in the hidden layer $l$: \n", + "\n", + "$$ z_{j}^{l} = \\sum_{i=1}^{F} w_{ij}^{l} x_i + b_{j}^{l},$$\n", + "\n", + "this is then passed through our activation function \n", + "\n", + "$$ a_{j}^{l} = f(z_{j}^{l}) .$$ \n", + "\n", + "We calculate a weighted sum of inputs (activations in the hidden layer) to each neuron $j$ in the output layer: \n", + "\n", + "$$ z_{j}^{L} = \\sum_{i=1}^{H} w_{ij}^{L} a_{i}^{l} + b_{j}^{L}.$$ \n", + "\n", + "Finally we calculate the output of neuron $j$ in the output layer using the softmax function: \n", + "\n", + "$$ a_{j}^{L} = \\frac{\\exp{(z_j^{L})}}\n", + "{\\sum_{c=0}^{C-1} \\exp{(z_c^{L})}} .$$ \n", + "\n", + "\n", + "## Matrix multiplications\n", + "\n", + "Since our data has the dimensions $X = (n_{inputs}, n_{features})$ and our weights to the hidden\n", + "layer have the dimensions \n", + "$W_{hidden} = (n_{features}, n_{hidden})$,\n", + "we can easily feed the network all our training data in one go by taking the matrix product \n", + "\n", + "$$ X W^{h} = (n_{inputs}, n_{hidden}),$$ \n", + "\n", + "and obtain a matrix that holds the weighted sum of inputs to the hidden layer\n", + "for each input image and each hidden neuron. \n", + "We also add the bias to obtain a matrix of weighted sums to the hidden layer $Z^{h}$: \n", + "\n", + "$$ \\hat{z}^{l} = \\hat{X} \\hat{W}^{l} + \\hat{b}^{l} ,$$\n", + "\n", + "meaning the same bias (1D array with size equal number of hidden neurons) is added to each input image. \n", + "This is then passed through the activation: \n", + "\n", + "$$ \\hat{a}^{l} = f(\\hat{z}^l) .$$ \n", + "\n", + "This is fed to the output layer: \n", + "\n", + "$$ \\hat{z}^{L} = \\hat{a}^{L} \\hat{W}^{L} + \\hat{b}^{L} .$$\n", + "\n", + "Finally we receive our output values for each image and each category by passing it through the softmax function: \n", + "\n", + "$$ output = softmax (\\hat{z}^{L}) = (n_{inputs}, n_{categories}) .$$" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# setup the feed-forward pass, subscript h = hidden layer\n", + "\n", + "def sigmoid(x):\n", + " return 1/(1 + np.exp(-x))\n", + "\n", + "def feed_forward(X):\n", + " # weighted sum of inputs to the hidden layer\n", + " z_h = np.matmul(X, hidden_weights) + hidden_bias\n", + " # activation in the hidden layer\n", + " a_h = sigmoid(z_h)\n", + " \n", + " # weighted sum of inputs to the output layer\n", + " z_o = np.matmul(a_h, output_weights) + output_bias\n", + " # softmax output\n", + " # axis 0 holds each input and axis 1 the probabilities of each category\n", + " exp_term = np.exp(z_o)\n", + " probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)\n", + " \n", + " return probabilities\n", + "\n", + "probabilities = feed_forward(X_train)\n", + "print(\"probabilities = (n_inputs, n_categories) = \" + str(probabilities.shape))\n", + "print(\"probability that image 0 is in category 0,1,2,...,9 = \\n\" + str(probabilities[0]))\n", + "print(\"probabilities sum up to: \" + str(probabilities[0].sum()))\n", + "print()\n", + "\n", + "# we obtain a prediction by taking the class with the highest likelihood\n", + "def predict(X):\n", + " probabilities = feed_forward(X)\n", + " return np.argmax(probabilities, axis=1)\n", + "\n", + "predictions = predict(X_train)\n", + "print(\"predictions = (n_inputs) = \" + str(predictions.shape))\n", + "print(\"prediction for image 0: \" + str(predictions[0]))\n", + "print(\"correct label for image 0: \" + str(Y_train[0]))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Choose cost function and optimizer\n", + "\n", + "To measure how well our neural network is doing we need to introduce a cost function. \n", + "We will call the function that gives the error of a single sample output the *loss* function, and the function\n", + "that gives the total error of our network across all samples the *cost* function.\n", + "A typical choice for multiclass classification is the *cross-entropy* loss, also known as the negative log likelihood. \n", + "\n", + "In *multiclass* classification it is common to treat each integer label as a so called *one-hot* vector: \n", + "\n", + "$$ y = 5 \\quad \\rightarrow \\quad \\hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) ,$$ \n", + "\n", + "\n", + "$$ y = 1 \\quad \\rightarrow \\quad \\hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) ,$$ \n", + "\n", + "\n", + "i.e. a binary bit string of length $C$, where $C = 10$ is the number of classes in the MNIST dataset. \n", + "\n", + "Let $y_{ic}$ denote the $c$-th component of the $i$-th one-hot vector. \n", + "We define the cost function $\\mathcal{C}$ as a sum over the cross-entropy loss for each point $\\hat{x}_i$ in the dataset.\n", + "\n", + "In the one-hot representation only one of the terms in the loss function is non-zero, namely the\n", + "probability of the correct category $c'$ \n", + "(i.e. the category $c'$ such that $y_{ic'} = 1$). This means that the cross entropy loss only punishes you for how wrong\n", + "you got the correct label. The probability of category $c$ is given by the softmax function. The vector $\\hat{\\theta}$ represents the parameters of our network, i.e. all the weights and biases. \n", + "\n", + "\n", + "## Optimizing the cost function\n", + "\n", + "The network is trained by finding the weights and biases that minimize the cost function. One of the most widely used classes of methods is *gradient descent* and its generalizations. The idea behind gradient descent\n", + "is simply to adjust the weights in the direction where the gradient of the cost function is large and negative. This ensures we flow toward a *local* minimum of the cost function. \n", + "Each parameter $\\theta$ is iteratively adjusted according to the rule \n", + "\n", + "$$ \\theta_{i+1} = \\theta_i - \\eta \\nabla \\mathcal{C}(\\theta_i) ,$$\n", + "\n", + "where $\\eta$ is known as the *learning rate*, which controls how big a step we take towards the minimum. \n", + "This update can be repeated for any number of iterations, or until we are satisfied with the result. \n", + "\n", + "A simple and effective improvement is a variant called *Batch Gradient Descent*. \n", + "Instead of calculating the gradient on the whole dataset, we calculate an approximation of the gradient\n", + "on a subset of the data called a *minibatch*. \n", + "If there are $N$ data points and we have a minibatch size of $M$, the total number of batches\n", + "is $N/M$. \n", + "We denote each minibatch $B_k$, with $k = 1, 2,...,N/M$. The gradient then becomes: \n", + "\n", + "$$ \\nabla \\mathcal{C}(\\theta) = \\frac{1}{N} \\sum_{i=1}^N \\nabla \\mathcal{L}_i(\\theta) \\quad \\rightarrow \\quad\n", + "\\frac{1}{M} \\sum_{i \\in B_k} \\nabla \\mathcal{L}_i(\\theta) ,$$\n", + "\n", + "i.e. instead of averaging the loss over the entire dataset, we average over a minibatch. \n", + "\n", + "This has two important benefits: \n", + "1. Introducing stochasticity decreases the chance that the algorithm becomes stuck in a local minima. \n", + "\n", + "2. It significantly speeds up the calculation, since we do not have to use the entire dataset to calculate the gradient. \n", + "\n", + "The various optmization methods, with codes and algorithms, are discussed in our lectures on [Gradient descent approaches](https://compphysics.github.io/MachineLearning/doc/pub/Splines/html/Splines-bs.html).\n", + "\n", + "\n", + "## Regularization\n", + "\n", + "It is common to add an extra term to the cost function, proportional\n", + "to the size of the weights. This is equivalent to constraining the\n", + "size of the weights, so that they do not grow out of control.\n", + "Constraining the size of the weights means that the weights cannot\n", + "grow arbitrarily large to fit the training data, and in this way\n", + "reduces *overfitting*.\n", + "\n", + "We will measure the size of the weights using the so called *L2-norm*, meaning our cost function becomes: \n", + "\n", + "$$ \\mathcal{C}(\\theta) = \\frac{1}{N} \\sum_{i=1}^N \\mathcal{L}_i(\\theta) \\quad \\rightarrow \\quad\n", + "\\frac{1}{N} \\sum_{i=1}^N \\mathcal{L}_i(\\theta) + \\lambda \\lvert \\lvert \\hat{w} \\rvert \\rvert_2^2 \n", + "= \\frac{1}{N} \\sum_{i=1}^N \\mathcal{L}(\\theta) + \\lambda \\sum_{ij} w_{ij}^2,$$ \n", + "\n", + "i.e. we sum up all the weights squared. The factor $\\lambda$ is known as a regularization parameter.\n", + "\n", + "\n", + "In order to train the model, we need to calculate the derivative of\n", + "the cost function with respect to every bias and weight in the\n", + "network. In total our network has $(64 + 1)\\times 50=3250$ weights in\n", + "the hidden layer and $(50 + 1)\\times 10=510$ weights to the output\n", + "layer ($+1$ for the bias), and the gradient must be calculated for\n", + "every parameter. We use the *backpropagation* algorithm discussed\n", + "above. This is a clever use of the chain rule that allows us to\n", + "calculate the gradient efficently. \n", + "\n", + "\n", + "## Matrix multiplication\n", + "\n", + "To more efficently train our network these equations are implemented using matrix operations. \n", + "The error in the output layer is calculated simply as, with $\\hat{t}$ being our targets, \n", + "\n", + "$$ \\delta_L = \\hat{t} - \\hat{y} = (n_{inputs}, n_{categories}) .$$ \n", + "\n", + "The gradient for the output weights is calculated as \n", + "\n", + "$$ \\nabla W_{L} = \\hat{a}^T \\delta_L = (n_{hidden}, n_{categories}) ,$$\n", + "\n", + "where $\\hat{a} = (n_{inputs}, n_{hidden})$. This simply means that we are summing up the gradients for each input. \n", + "Since we are going backwards we have to transpose the activation matrix. \n", + "\n", + "The gradient with respect to the output bias is then \n", + "\n", + "$$ \\nabla \\hat{b}_{L} = \\sum_{i=1}^{n_{inputs}} \\delta_L = (n_{categories}) .$$ \n", + "\n", + "The error in the hidden layer is \n", + "\n", + "$$ \\Delta_h = \\delta_L W_{L}^T \\circ f'(z_{h}) = \\delta_L W_{L}^T \\circ a_{h} \\circ (1 - a_{h}) = (n_{inputs}, n_{hidden}) ,$$ \n", + "\n", + "where $f'(a_{h})$ is the derivative of the activation in the hidden layer. The matrix products mean\n", + "that we are summing up the products for each neuron in the output layer. The symbol $\\circ$ denotes\n", + "the *Hadamard product*, meaning element-wise multiplication. \n", + "\n", + "This again gives us the gradients in the hidden layer: \n", + "\n", + "$$ \\nabla W_{h} = X^T \\delta_h = (n_{features}, n_{hidden}) ,$$ \n", + "\n", + "$$ \\nabla b_{h} = \\sum_{i=1}^{n_{inputs}} \\delta_h = (n_{hidden}) .$$" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# to categorical turns our integer vector into a onehot representation\n", + "from sklearn.metrics import accuracy_score\n", + "\n", + "# one-hot in numpy\n", + "def to_categorical_numpy(integer_vector):\n", + " n_inputs = len(integer_vector)\n", + " n_categories = np.max(integer_vector) + 1\n", + " onehot_vector = np.zeros((n_inputs, n_categories))\n", + " onehot_vector[range(n_inputs), integer_vector] = 1\n", + " \n", + " return onehot_vector\n", + "\n", + "#Y_train_onehot, Y_test_onehot = to_categorical(Y_train), to_categorical(Y_test)\n", + "Y_train_onehot, Y_test_onehot = to_categorical_numpy(Y_train), to_categorical_numpy(Y_test)\n", + "\n", + "def feed_forward_train(X):\n", + " # weighted sum of inputs to the hidden layer\n", + " z_h = np.matmul(X, hidden_weights) + hidden_bias\n", + " # activation in the hidden layer\n", + " a_h = sigmoid(z_h)\n", + " \n", + " # weighted sum of inputs to the output layer\n", + " z_o = np.matmul(a_h, output_weights) + output_bias\n", + " # softmax output\n", + " # axis 0 holds each input and axis 1 the probabilities of each category\n", + " exp_term = np.exp(z_o)\n", + " probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)\n", + " \n", + " # for backpropagation need activations in hidden and output layers\n", + " return a_h, probabilities\n", + "\n", + "def backpropagation(X, Y):\n", + " a_h, probabilities = feed_forward_train(X)\n", + " \n", + " # error in the output layer\n", + " error_output = probabilities - Y\n", + " # error in the hidden layer\n", + " error_hidden = np.matmul(error_output, output_weights.T) * a_h * (1 - a_h)\n", + " \n", + " # gradients for the output layer\n", + " output_weights_gradient = np.matmul(a_h.T, error_output)\n", + " output_bias_gradient = np.sum(error_output, axis=0)\n", + " \n", + " # gradient for the hidden layer\n", + " hidden_weights_gradient = np.matmul(X.T, error_hidden)\n", + " hidden_bias_gradient = np.sum(error_hidden, axis=0)\n", + "\n", + " return output_weights_gradient, output_bias_gradient, hidden_weights_gradient, hidden_bias_gradient\n", + "\n", + "print(\"Old accuracy on training data: \" + str(accuracy_score(predict(X_train), Y_train)))\n", + "\n", + "eta = 0.01\n", + "lmbd = 0.01\n", + "for i in range(1000):\n", + " # calculate gradients\n", + " dWo, dBo, dWh, dBh = backpropagation(X_train, Y_train_onehot)\n", + " \n", + " # regularization term gradients\n", + " dWo += lmbd * output_weights\n", + " dWh += lmbd * hidden_weights\n", + " \n", + " # update weights and biases\n", + " output_weights -= eta * dWo\n", + " output_bias -= eta * dBo\n", + " hidden_weights -= eta * dWh\n", + " hidden_bias -= eta * dBh\n", + "\n", + "print(\"New accuracy on training data: \" + str(accuracy_score(predict(X_train), Y_train)))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Improving performance\n", + "\n", + "As we can see the network does not seem to be learning at all. It seems to be just guessing the label for each image. \n", + "In order to obtain a network that does something useful, we will have to do a bit more work. \n", + "\n", + "The choice of *hyperparameters* such as learning rate and regularization parameter is hugely influential for the performance of the network. Typically a *grid-search* is performed, wherein we test different hyperparameters separated by orders of magnitude. For example we could test the learning rates $\\eta = 10^{-6}, 10^{-5},...,10^{-1}$ with different regularization parameters $\\lambda = 10^{-6},...,10^{-0}$. \n", + "\n", + "Next, we haven't implemented minibatching yet, which introduces stochasticity and is though to act as an important regularizer on the weights. We call a feed-forward + backward pass with a minibatch an *iteration*, and a full training period\n", + "going through the entire dataset ($n/M$ batches) an *epoch*.\n", + "\n", + "If this does not improve network performance, you may want to consider altering the network architecture, adding more neurons or hidden layers. \n", + "Andrew Ng goes through some of these considerations in this [video](https://youtu.be/F1ka6a13S9I). You can find a summary of the video [here](https://kevinzakka.github.io/2016/09/26/applying-deep-learning/). \n", + "\n", + "## Full object-oriented implementation\n", + "\n", + "It is very natural to think of the network as an object, with specific instances of the network\n", + "being realizations of this object with different hyperparameters. An implementation using Python classes provides a clean structure and interface, and the full implementation of our neural network is given below." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "class NeuralNetwork:\n", + " def __init__(\n", + " self,\n", + " X_data,\n", + " Y_data,\n", + " n_hidden_neurons=50,\n", + " n_categories=10,\n", + " epochs=10,\n", + " batch_size=100,\n", + " eta=0.1,\n", + " lmbd=0.0):\n", + "\n", + " self.X_data_full = X_data\n", + " self.Y_data_full = Y_data\n", + "\n", + " self.n_inputs = X_data.shape[0]\n", + " self.n_features = X_data.shape[1]\n", + " self.n_hidden_neurons = n_hidden_neurons\n", + " self.n_categories = n_categories\n", + "\n", + " self.epochs = epochs\n", + " self.batch_size = batch_size\n", + " self.iterations = self.n_inputs // self.batch_size\n", + " self.eta = eta\n", + " self.lmbd = lmbd\n", + "\n", + " self.create_biases_and_weights()\n", + "\n", + " def create_biases_and_weights(self):\n", + " self.hidden_weights = np.random.randn(self.n_features, self.n_hidden_neurons)\n", + " self.hidden_bias = np.zeros(self.n_hidden_neurons) + 0.01\n", + "\n", + " self.output_weights = np.random.randn(self.n_hidden_neurons, self.n_categories)\n", + " self.output_bias = np.zeros(self.n_categories) + 0.01\n", + "\n", + " def feed_forward(self):\n", + " # feed-forward for training\n", + " self.z_h = np.matmul(self.X_data, self.hidden_weights) + self.hidden_bias\n", + " self.a_h = sigmoid(self.z_h)\n", + "\n", + " self.z_o = np.matmul(self.a_h, self.output_weights) + self.output_bias\n", + "\n", + " exp_term = np.exp(self.z_o)\n", + " self.probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)\n", + "\n", + " def feed_forward_out(self, X):\n", + " # feed-forward for output\n", + " z_h = np.matmul(X, self.hidden_weights) + self.hidden_bias\n", + " a_h = sigmoid(z_h)\n", + "\n", + " z_o = np.matmul(a_h, self.output_weights) + self.output_bias\n", + " \n", + " exp_term = np.exp(z_o)\n", + " probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True)\n", + " return probabilities\n", + "\n", + " def backpropagation(self):\n", + " error_output = self.probabilities - self.Y_data\n", + " error_hidden = np.matmul(error_output, self.output_weights.T) * self.a_h * (1 - self.a_h)\n", + "\n", + " self.output_weights_gradient = np.matmul(self.a_h.T, error_output)\n", + " self.output_bias_gradient = np.sum(error_output, axis=0)\n", + "\n", + " self.hidden_weights_gradient = np.matmul(self.X_data.T, error_hidden)\n", + " self.hidden_bias_gradient = np.sum(error_hidden, axis=0)\n", + "\n", + " if self.lmbd > 0.0:\n", + " self.output_weights_gradient += self.lmbd * self.output_weights\n", + " self.hidden_weights_gradient += self.lmbd * self.hidden_weights\n", + "\n", + " self.output_weights -= self.eta * self.output_weights_gradient\n", + " self.output_bias -= self.eta * self.output_bias_gradient\n", + " self.hidden_weights -= self.eta * self.hidden_weights_gradient\n", + " self.hidden_bias -= self.eta * self.hidden_bias_gradient\n", + "\n", + " def predict(self, X):\n", + " probabilities = self.feed_forward_out(X)\n", + " return np.argmax(probabilities, axis=1)\n", + "\n", + " def predict_probabilities(self, X):\n", + " probabilities = self.feed_forward_out(X)\n", + " return probabilities\n", + "\n", + " def train(self):\n", + " data_indices = np.arange(self.n_inputs)\n", + "\n", + " for i in range(self.epochs):\n", + " for j in range(self.iterations):\n", + " # pick datapoints with replacement\n", + " chosen_datapoints = np.random.choice(\n", + " data_indices, size=self.batch_size, replace=False\n", + " )\n", + "\n", + " # minibatch training data\n", + " self.X_data = self.X_data_full[chosen_datapoints]\n", + " self.Y_data = self.Y_data_full[chosen_datapoints]\n", + "\n", + " self.feed_forward()\n", + " self.backpropagation()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Evaluate model performance on test data\n", + "\n", + "To measure the performance of our network we evaluate how well it does it data it has never seen before, i.e. the test data. \n", + "We measure the performance of the network using the *accuracy* score. \n", + "The accuracy is as you would expect just the number of images correctly labeled divided by the total number of images. A perfect classifier will have an accuracy score of $1$. \n", + "\n", + "$$ \\text{Accuracy} = \\frac{\\sum_{i=1}^n I(\\hat{y}_i = y_i)}{n} ,$$ \n", + "\n", + "where $I$ is the indicator function, $1$ if $\\hat{y}_i = y_i$ and $0$ otherwise." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "epochs = 100\n", + "batch_size = 100\n", + "\n", + "dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size,\n", + " n_hidden_neurons=n_hidden_neurons, n_categories=n_categories)\n", + "dnn.train()\n", + "test_predict = dnn.predict(X_test)\n", + "\n", + "# accuracy score from scikit library\n", + "print(\"Accuracy score on test set: \", accuracy_score(Y_test, test_predict))\n", + "\n", + "# equivalent in numpy\n", + "def accuracy_score_numpy(Y_test, Y_pred):\n", + " return np.sum(Y_test == Y_pred) / len(Y_test)\n", + "\n", + "#print(\"Accuracy score on test set: \", accuracy_score_numpy(Y_test, test_predict))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Adjust hyperparameters\n", + "\n", + "We now perform a grid search to find the optimal hyperparameters for the network. \n", + "Note that we are only using 1 layer with 50 neurons, and human performance is estimated to be around $98\\%$ ($2\\%$ error rate)." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "eta_vals = np.logspace(-5, 1, 7)\n", + "lmbd_vals = np.logspace(-5, 1, 7)\n", + "# store the models for later use\n", + "DNN_numpy = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)\n", + "\n", + "# grid search\n", + "for i, eta in enumerate(eta_vals):\n", + " for j, lmbd in enumerate(lmbd_vals):\n", + " dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size,\n", + " n_hidden_neurons=n_hidden_neurons, n_categories=n_categories)\n", + " dnn.train()\n", + " \n", + " DNN_numpy[i][j] = dnn\n", + " \n", + " test_predict = dnn.predict(X_test)\n", + " \n", + " print(\"Learning rate = \", eta)\n", + " print(\"Lambda = \", lmbd)\n", + " print(\"Accuracy score on test set: \", accuracy_score(Y_test, test_predict))\n", + " print()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Visualization" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# visual representation of grid search\n", + "# uses seaborn heatmap, you can also do this with matplotlib imshow\n", + "import seaborn as sns\n", + "\n", + "sns.set()\n", + "\n", + "train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "\n", + "for i in range(len(eta_vals)):\n", + " for j in range(len(lmbd_vals)):\n", + " dnn = DNN_numpy[i][j]\n", + " \n", + " train_pred = dnn.predict(X_train) \n", + " test_pred = dnn.predict(X_test)\n", + "\n", + " train_accuracy[i][j] = accuracy_score(Y_train, train_pred)\n", + " test_accuracy[i][j] = accuracy_score(Y_test, test_pred)\n", + "\n", + " \n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(train_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Training Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()\n", + "\n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(test_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Test Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## scikit-learn implementation\n", + "\n", + "**scikit-learn** focuses more\n", + "on traditional machine learning methods, such as regression,\n", + "clustering, decision trees, etc. As such, it has only two types of\n", + "neural networks: Multi Layer Perceptron outputting continuous values,\n", + "*MPLRegressor*, and Multi Layer Perceptron outputting labels,\n", + "*MLPClassifier*. We will see how simple it is to use these classes.\n", + "\n", + "**scikit-learn** implements a few improvements from our neural network,\n", + "such as early stopping, a varying learning rate, different\n", + "optimization methods, etc. We would therefore expect a better\n", + "performance overall." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "from sklearn.neural_network import MLPClassifier\n", + "# store models for later use\n", + "DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)\n", + "\n", + "for i, eta in enumerate(eta_vals):\n", + " for j, lmbd in enumerate(lmbd_vals):\n", + " dnn = MLPClassifier(hidden_layer_sizes=(n_hidden_neurons), activation='logistic',\n", + " alpha=lmbd, learning_rate_init=eta, max_iter=epochs)\n", + " dnn.fit(X_train, Y_train)\n", + " \n", + " DNN_scikit[i][j] = dnn\n", + " \n", + " print(\"Learning rate = \", eta)\n", + " print(\"Lambda = \", lmbd)\n", + " print(\"Accuracy score on test set: \", dnn.score(X_test, Y_test))\n", + " print()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Visualization" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# optional\n", + "# visual representation of grid search\n", + "# uses seaborn heatmap, could probably do this in matplotlib\n", + "import seaborn as sns\n", + "\n", + "sns.set()\n", + "\n", + "train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "\n", + "for i in range(len(eta_vals)):\n", + " for j in range(len(lmbd_vals)):\n", + " dnn = DNN_scikit[i][j]\n", + " \n", + " train_pred = dnn.predict(X_train) \n", + " test_pred = dnn.predict(X_test)\n", + "\n", + " train_accuracy[i][j] = accuracy_score(Y_train, train_pred)\n", + " test_accuracy[i][j] = accuracy_score(Y_test, test_pred)\n", + "\n", + " \n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(train_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Training Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()\n", + "\n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(test_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Test Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Building neural networks in Tensorflow and Keras\n", + "\n", + "Now we want to build on the experience gained from our neural network implementation in NumPy and scikit-learn\n", + "and use it to construct a neural network in Tensorflow. Once we have constructed a neural network in NumPy\n", + "and Tensorflow, building one in Keras is really quite trivial, though the performance may suffer. \n", + "\n", + "In our previous example we used only one hidden layer, and in this we will use two. From this it should be quite\n", + "clear how to build one using an arbitrary number of hidden layers, using data structures such as Python lists or\n", + "NumPy arrays.\n", + "\n", + "## Tensorflow\n", + "\n", + "Tensorflow is an open source library machine learning library\n", + "developed by the Google Brain team for internal use. It was released\n", + "under the Apache 2.0 open source license in November 9, 2015.\n", + "\n", + "Tensorflow is a computational framework that allows you to construct\n", + "machine learning models at different levels of abstraction, from\n", + "high-level, object-oriented APIs like Keras, down to the C++ kernels\n", + "that Tensorflow is built upon. The higher levels of abstraction are\n", + "simpler to use, but less flexible, and our choice of implementation\n", + "should reflect the problems we are trying to solve.\n", + "\n", + "[Tensorflow uses](https://www.tensorflow.org/guide/graphs) so-called graphs to represent your computation\n", + "in terms of the dependencies between individual operations, such that you first build a Tensorflow *graph*\n", + "to represent your model, and then create a Tensorflow *session* to run the graph.\n", + "\n", + "In this guide we will analyze the same data as we did in our NumPy and\n", + "scikit-learn tutorial, gathered from the MNIST database of images. We\n", + "will give an introduction to the lower level Python Application\n", + "Program Interfaces (APIs), and see how we use them to build our graph.\n", + "Then we will build (effectively) the same graph in Keras, to see just\n", + "how simple solving a machine learning problem can be.\n", + "\n", + "To install tensorflow on Unix/Linux systems, use pip as" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "pip3 install tensorflow" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "and/or if you use **anaconda**, just write (or install from the graphical user interface)" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "conda install tensorflow" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Collect and pre-process data" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# import necessary packages\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "from sklearn import datasets\n", + "\n", + "\n", + "# ensure the same random numbers appear every time\n", + "np.random.seed(0)\n", + "\n", + "# display images in notebook\n", + "%matplotlib inline\n", + "plt.rcParams['figure.figsize'] = (12,12)\n", + "\n", + "\n", + "# download MNIST dataset\n", + "digits = datasets.load_digits()\n", + "\n", + "# define inputs and labels\n", + "inputs = digits.images\n", + "labels = digits.target\n", + "\n", + "print(\"inputs = (n_inputs, pixel_width, pixel_height) = \" + str(inputs.shape))\n", + "print(\"labels = (n_inputs) = \" + str(labels.shape))\n", + "\n", + "\n", + "# flatten the image\n", + "# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64\n", + "n_inputs = len(inputs)\n", + "inputs = inputs.reshape(n_inputs, -1)\n", + "print(\"X = (n_inputs, n_features) = \" + str(inputs.shape))\n", + "\n", + "\n", + "# choose some random images to display\n", + "indices = np.arange(n_inputs)\n", + "random_indices = np.random.choice(indices, size=5)\n", + "\n", + "for i, image in enumerate(digits.images[random_indices]):\n", + " plt.subplot(1, 5, i+1)\n", + " plt.axis('off')\n", + " plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')\n", + " plt.title(\"Label: %d\" % digits.target[random_indices[i]])\n", + "plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "from keras.utils import to_categorical\n", + "from sklearn.model_selection import train_test_split\n", + "\n", + "# one-hot representation of labels\n", + "labels = to_categorical(labels)\n", + "\n", + "# split into train and test data\n", + "train_size = 0.8\n", + "test_size = 1 - train_size\n", + "X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,\n", + " test_size=test_size)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Using TensorFlow backend\n", + "\n", + "1. Define model and architecture\n", + "\n", + "2. Choose cost function and optimizer" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "import tensorflow as tf\n", + "\n", + "class NeuralNetworkTensorflow:\n", + " def __init__(\n", + " self,\n", + " X_train,\n", + " Y_train,\n", + " X_test,\n", + " Y_test,\n", + " n_neurons_layer1=100,\n", + " n_neurons_layer2=50,\n", + " n_categories=2,\n", + " epochs=10,\n", + " batch_size=100,\n", + " eta=0.1,\n", + " lmbd=0.0):\n", + " \n", + " # keep track of number of steps\n", + " self.global_step = tf.Variable(0, dtype=tf.int32, trainable=False, name='global_step')\n", + " \n", + " self.X_train = X_train\n", + " self.Y_train = Y_train\n", + " self.X_test = X_test\n", + " self.Y_test = Y_test\n", + " \n", + " self.n_inputs = X_train.shape[0]\n", + " self.n_features = X_train.shape[1]\n", + " self.n_neurons_layer1 = n_neurons_layer1\n", + " self.n_neurons_layer2 = n_neurons_layer2\n", + " self.n_categories = n_categories\n", + " \n", + " self.epochs = epochs\n", + " self.batch_size = batch_size\n", + " self.iterations = self.n_inputs // self.batch_size\n", + " self.eta = eta\n", + " self.lmbd = lmbd\n", + " \n", + " # build network piece by piece\n", + " # name scopes (with) are used to enforce creation of new variables\n", + " # https://www.tensorflow.org/guide/variables\n", + " self.create_placeholders()\n", + " self.create_DNN()\n", + " self.create_loss()\n", + " self.create_optimiser()\n", + " self.create_accuracy()\n", + " \n", + " def create_placeholders(self):\n", + " # placeholders are fine here, but \"Datasets\" are the preferred method\n", + " # of streaming data into a model\n", + " with tf.name_scope('data'):\n", + " self.X = tf.placeholder(tf.float32, shape=(None, self.n_features), name='X_data')\n", + " self.Y = tf.placeholder(tf.float32, shape=(None, self.n_categories), name='Y_data')\n", + " \n", + " def create_DNN(self):\n", + " with tf.name_scope('DNN'):\n", + " # the weights are stored to calculate regularization loss later\n", + " \n", + " # Fully connected layer 1\n", + " self.W_fc1 = self.weight_variable([self.n_features, self.n_neurons_layer1], name='fc1', dtype=tf.float32)\n", + " b_fc1 = self.bias_variable([self.n_neurons_layer1], name='fc1', dtype=tf.float32)\n", + " a_fc1 = tf.nn.sigmoid(tf.matmul(self.X, self.W_fc1) + b_fc1)\n", + " \n", + " # Fully connected layer 2\n", + " self.W_fc2 = self.weight_variable([self.n_neurons_layer1, self.n_neurons_layer2], name='fc2', dtype=tf.float32)\n", + " b_fc2 = self.bias_variable([self.n_neurons_layer2], name='fc2', dtype=tf.float32)\n", + " a_fc2 = tf.nn.sigmoid(tf.matmul(a_fc1, self.W_fc2) + b_fc2)\n", + " \n", + " # Output layer\n", + " self.W_out = self.weight_variable([self.n_neurons_layer2, self.n_categories], name='out', dtype=tf.float32)\n", + " b_out = self.bias_variable([self.n_categories], name='out', dtype=tf.float32)\n", + " self.z_out = tf.matmul(a_fc2, self.W_out) + b_out\n", + " \n", + " def create_loss(self):\n", + " with tf.name_scope('loss'):\n", + " softmax_loss = tf.reduce_mean(tf.nn.softmax_cross_entropy_with_logits_v2(labels=self.Y, logits=self.z_out))\n", + " \n", + " regularizer_loss_fc1 = tf.nn.l2_loss(self.W_fc1)\n", + " regularizer_loss_fc2 = tf.nn.l2_loss(self.W_fc2)\n", + " regularizer_loss_out = tf.nn.l2_loss(self.W_out)\n", + " regularizer_loss = self.lmbd*(regularizer_loss_fc1 + regularizer_loss_fc2 + regularizer_loss_out)\n", + " \n", + " self.loss = softmax_loss + regularizer_loss\n", + "\n", + " def create_accuracy(self):\n", + " with tf.name_scope('accuracy'):\n", + " probabilities = tf.nn.softmax(self.z_out)\n", + " predictions = tf.argmax(probabilities, axis=1)\n", + " labels = tf.argmax(self.Y, axis=1)\n", + " \n", + " correct_predictions = tf.equal(predictions, labels)\n", + " correct_predictions = tf.cast(correct_predictions, tf.float32)\n", + " self.accuracy = tf.reduce_mean(correct_predictions)\n", + " \n", + " def create_optimiser(self):\n", + " with tf.name_scope('optimizer'):\n", + " self.optimizer = tf.train.GradientDescentOptimizer(learning_rate=self.eta).minimize(self.loss, global_step=self.global_step)\n", + " \n", + " def weight_variable(self, shape, name='', dtype=tf.float32):\n", + " initial = tf.truncated_normal(shape, stddev=0.1)\n", + " return tf.Variable(initial, name=name, dtype=dtype)\n", + " \n", + " def bias_variable(self, shape, name='', dtype=tf.float32):\n", + " initial = tf.constant(0.1, shape=shape)\n", + " return tf.Variable(initial, name=name, dtype=dtype)\n", + " \n", + " def fit(self):\n", + " data_indices = np.arange(self.n_inputs)\n", + "\n", + " with tf.Session() as sess:\n", + " sess.run(tf.global_variables_initializer())\n", + " for i in range(self.epochs):\n", + " for j in range(self.iterations):\n", + " chosen_datapoints = np.random.choice(data_indices, size=self.batch_size, replace=False)\n", + " batch_X, batch_Y = self.X_train[chosen_datapoints], self.Y_train[chosen_datapoints]\n", + " \n", + " sess.run([DNN.loss, DNN.optimizer],\n", + " feed_dict={DNN.X: batch_X,\n", + " DNN.Y: batch_Y})\n", + " accuracy = sess.run(DNN.accuracy,\n", + " feed_dict={DNN.X: batch_X,\n", + " DNN.Y: batch_Y})\n", + " step = sess.run(DNN.global_step)\n", + " \n", + " self.train_loss, self.train_accuracy = sess.run([DNN.loss, DNN.accuracy],\n", + " feed_dict={DNN.X: self.X_train,\n", + " DNN.Y: self.Y_train})\n", + " \n", + " self.test_loss, self.test_accuracy = sess.run([DNN.loss, DNN.accuracy],\n", + " feed_dict={DNN.X: self.X_test,\n", + " DNN.Y: self.Y_test})" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Optimizing and using gradient descent" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "epochs = 100\n", + "batch_size = 100\n", + "n_neurons_layer1 = 100\n", + "n_neurons_layer2 = 50\n", + "n_categories = 10\n", + "eta_vals = np.logspace(-5, 1, 7)\n", + "lmbd_vals = np.logspace(-5, 1, 7)" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "DNN_tf = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)\n", + " \n", + "for i, eta in enumerate(eta_vals):\n", + " for j, lmbd in enumerate(lmbd_vals):\n", + " DNN = NeuralNetworkTensorflow(X_train, Y_train, X_test, Y_test,\n", + " n_neurons_layer1, n_neurons_layer2, n_categories,\n", + " epochs=epochs, batch_size=batch_size, eta=eta, lmbd=lmbd)\n", + " DNN.fit()\n", + " \n", + " DNN_tf[i][j] = DNN\n", + " \n", + " print(\"Learning rate = \", eta)\n", + " print(\"Lambda = \", lmbd)\n", + " print(\"Test accuracy: %.3f\" % DNN.test_accuracy)\n", + " print()" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# optional\n", + "# visual representation of grid search\n", + "# uses seaborn heatmap, could probably do this in matplotlib\n", + "import seaborn as sns\n", + "\n", + "sns.set()\n", + "\n", + "train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "\n", + "for i in range(len(eta_vals)):\n", + " for j in range(len(lmbd_vals)):\n", + " DNN = DNN_tf[i][j]\n", + "\n", + " train_accuracy[i][j] = DNN.train_accuracy\n", + " test_accuracy[i][j] = DNN.test_accuracy\n", + "\n", + " \n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(train_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Training Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()\n", + "\n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(test_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Test Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# optional\n", + "# we can use log files to visualize our graph in Tensorboard\n", + "writer = tf.summary.FileWriter('logs/')\n", + "writer.add_graph(tf.get_default_graph())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Using Keras\n", + "\n", + "Keras is a high level [neural network](https://en.wikipedia.org/wiki/Application_programming_interface)\n", + "that supports Tensorflow, CTNK and Theano as backends. \n", + "If you have Tensorflow installed Keras is available through the *tf.keras* module. \n", + "If you have Anaconda installed you may run the following command" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "conda install keras" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alternatively, if you have Tensorflow or one of the other supported backends install you may use the pip package manager:" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "pip3 install keras" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "or look up the [instructions here](https://keras.io/)." + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "from keras.models import Sequential\n", + "from keras.layers import Dense\n", + "from keras.regularizers import l2\n", + "from keras.optimizers import SGD\n", + "\n", + "def create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories, eta, lmbd):\n", + " model = Sequential()\n", + " model.add(Dense(n_neurons_layer1, activation='sigmoid', kernel_regularizer=l2(lmbd)))\n", + " model.add(Dense(n_neurons_layer2, activation='sigmoid', kernel_regularizer=l2(lmbd)))\n", + " model.add(Dense(n_categories, activation='softmax'))\n", + " \n", + " sgd = SGD(lr=eta)\n", + " model.compile(loss='categorical_crossentropy', optimizer=sgd, metrics=['accuracy'])\n", + " \n", + " return model" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "DNN_keras = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)\n", + " \n", + "for i, eta in enumerate(eta_vals):\n", + " for j, lmbd in enumerate(lmbd_vals):\n", + " DNN = create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories,\n", + " eta=eta, lmbd=lmbd)\n", + " DNN.fit(X_train, Y_train, epochs=epochs, batch_size=batch_size, verbose=0)\n", + " scores = DNN.evaluate(X_test, Y_test)\n", + " \n", + " DNN_keras[i][j] = DNN\n", + " \n", + " print(\"Learning rate = \", eta)\n", + " print(\"Lambda = \", lmbd)\n", + " print(\"Test accuracy: %.3f\" % scores[1])\n", + " print()" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "metadata": { + "collapsed": false + }, + "outputs": [], + "source": [ + "# optional\n", + "# visual representation of grid search\n", + "# uses seaborn heatmap, could probably do this in matplotlib\n", + "import seaborn as sns\n", + "\n", + "sns.set()\n", + "\n", + "train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "\n", + "for i in range(len(eta_vals)):\n", + " for j in range(len(lmbd_vals)):\n", + " DNN = DNN_keras[i][j]\n", + "\n", + " train_accuracy[i][j] = DNN.evaluate(X_train, Y_train)[1]\n", + " test_accuracy[i][j] = DNN.evaluate(X_test, Y_test)[1]\n", + "\n", + " \n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(train_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Training Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()\n", + "\n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(test_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Test Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "## Which activation function should I use?\n", + "\n", + "The Back propagation algorithm we derived above works by going from\n", + "the output layer to the input layer, propagating the error gradient on\n", + "the way. Once the algorithm has computed the gradient of the cost\n", + "function with regards to each parameter in the network, it uses these\n", + "gradients to update each parameter with a Gradient Descent (GD) step.\n", + "\n", + "\n", + "Unfortunately for us, the gradients often get smaller and smaller as the\n", + "algorithm progresses down to the first hidden layers. As a result, the\n", + "GD update leaves the lower layer connection weights\n", + "virtually unchanged, and training never converges to a good\n", + "solution. This is known in the literature as \n", + "**the vanishing gradients problem**. \n", + "\n", + "In other cases, the opposite can happen, namely the the gradients can grow bigger and\n", + "bigger. The result is that many of the layers get large updates of the \n", + "weights the\n", + "algorithm diverges. This is the **exploding gradients problem**, which is\n", + "mostly encountered in recurrent neural networks. More generally, deep\n", + "neural networks suffer from unstable gradients, different layers may\n", + "learn at widely different speeds\n", + "\n", + "\n", + "## Is the Logistic activation function (Sigmoid) our choice?\n", + "\n", + "Although this unfortunate behavior has been empirically observed for\n", + "quite a while (it was one of the reasons why deep neural networks were\n", + "mostly abandoned for a long time), it is only around 2010 that\n", + "significant progress was made in understanding it.\n", + "\n", + "A paper titled [Understanding the Difficulty of Training Deep\n", + "Feedforward Neural Networks by Xavier Glorot and Yoshua Bengio](http://proceedings.mlr.press/v9/glorot10a.html) found that\n", + "the problems with the popular logistic\n", + "sigmoid activation function and the weight initialization technique\n", + "that was most popular at the time, namely random initialization using\n", + "a normal distribution with a mean of 0 and a standard deviation of\n", + "1. \n", + "\n", + "They showed that with this activation function and this\n", + "initialization scheme, the variance of the outputs of each layer is\n", + "much greater than the variance of its inputs. Going forward in the\n", + "network, the variance keeps increasing after each layer until the\n", + "activation function saturates at the top layers. This is actually made\n", + "worse by the fact that the logistic function has a mean of 0.5, not 0\n", + "(the hyperbolic tangent function has a mean of 0 and behaves slightly\n", + "better than the logistic function in deep networks).\n", + "\n", + "\n", + "## The derivative of the Logistic funtion\n", + "\n", + "Looking at the logistic activation function, when inputs become large\n", + "(negative or positive), the function saturates at 0 or 1, with a\n", + "derivative extremely close to 0. Thus when backpropagation kicks in,\n", + "it has virtually no gradient to propagate back through the network,\n", + "and what little gradient exists keeps getting diluted as\n", + "backpropagation progresses down through the top layers, so there is\n", + "really nothing left for the lower layers.\n", + "\n", + "In their paper, Glorot and Bengio propose a way to significantly\n", + "alleviate this problem. We need the signal to flow properly in both\n", + "directions: in the forward direction when making predictions, and in\n", + "the reverse direction when backpropagating gradients. We don’t want\n", + "the signal to die out, nor do we want it to explode and saturate. For\n", + "the signal to flow properly, the authors argue that we need the\n", + "variance of the outputs of each layer to be equal to the variance of\n", + "its inputs, and we also need the gradients to have equal variance\n", + "before and after flowing through a layer in the reverse direction.\n", + "\n", + "\n", + "\n", + "One of the insights in the 2010 paper by Glorot and Bengio was that\n", + "the vanishing/exploding gradients problems were in part due to a poor\n", + "choice of activation function. Until then most people had assumed that\n", + "if Nature had chosen to use roughly sigmoid activation functions in\n", + "biological neurons, they must be an excellent choice. But it turns out\n", + "that other activation functions behave much better in deep neural\n", + "networks, in particular the ReLU activation function, mostly because\n", + "it does not saturate for positive values (and also because it is quite\n", + "fast to compute).\n", + "\n", + "\n", + "## The RELU function family\n", + "\n", + "The ReLU activation function suffers from a problem known as the dying\n", + "ReLUs: during training, some neurons effectively die, meaning they\n", + "stop outputting anything other than 0.\n", + "\n", + "In some cases, you may find that half of your network’s neurons are\n", + "dead, especially if you used a large learning rate. During training,\n", + "if a neuron’s weights get updated such that the weighted sum of the\n", + "neuron’s inputs is negative, it will start outputting 0. When this\n", + "happen, the neuron is unlikely to come back to life since the gradient\n", + "of the ReLU function is 0 when its input is negative.\n", + "\n", + "To solve this problem, nowadays practitioners use a variant of the ReLU\n", + "function, such as the leaky ReLU discussed above or the so-called\n", + "exponential linear unit (ELU) function" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "$$\n", + "ELU(z) = \\left\\{\\begin{array}{cc} \\alpha\\left( \\exp{(z)}-1\\right) & z < 0,\\\\ z & z \\ge 0.\\end{array}\\right.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Which activation function should we use?\n", + "\n", + "In general it seems that the ELU activation function is better than\n", + "the leaky ReLU function (and its variants), which is better than\n", + "ReLU. ReLU performs better than $\\tanh$ which in turn performs better\n", + "than the logistic function. \n", + "\n", + "If runtime\n", + "performance is an issue, then you may opt for the leaky ReLU function over the \n", + "ELU function If you don’t\n", + "want to tweak yet another hyperparameter, you may just use the default\n", + "$\\alpha$ of $0.01$ for the leaky ReLU, and $1$ for ELU. If you have\n", + "spare time and computing power, you can use cross-validation or\n", + "bootstrap to evaluate other activation functions.\n", + "\n", + "\n", + "\n", + "## A top-down perspective on Neural networks\n", + "\n", + "\n", + "The first thing we would like to do is divide the data into two or three\n", + "parts. A training set, a validation or dev (development) set, and a\n", + "test set. The test set is the data on which we want to make\n", + "predictions. The dev set is a subset of the training data we use to\n", + "check how well we are doing out-of-sample, after training the model on\n", + "the training dataset. We use the validation error as a proxy for the\n", + "test error in order to make tweaks to our model. It is crucial that we\n", + "do not use any of the test data to train the algorithm. This is a\n", + "cardinal sin in ML. Then:\n", + "\n", + "\n", + "* Estimate optimal error rate\n", + "\n", + "* Minimize underfitting (bias) on training data set.\n", + "\n", + "* Make sure you are not overfitting.\n", + "\n", + "If the validation and test sets are drawn from the same distributions,\n", + "then a good performance on the validation set should lead to similarly\n", + "good performance on the test set. \n", + "\n", + "However, sometimes\n", + "the training data and test data differ in subtle ways because, for\n", + "example, they are collected using slightly different methods, or\n", + "because it is cheaper to collect data in one way versus another. In\n", + "this case, there can be a mismatch between the training and test\n", + "data. This can lead to the neural network overfitting these small\n", + "differences between the test and training sets, and a poor performance\n", + "on the test set despite having a good performance on the validation\n", + "set. To rectify this, Andrew Ng suggests making two validation or dev\n", + "sets, one constructed from the training data and one constructed from\n", + "the test data. The difference between the performance of the algorithm\n", + "on these two validation sets quantifies the train-test mismatch. This\n", + "can serve as another important diagnostic when using DNNs for\n", + "supervised learning.\n", + "\n", + "## Limitations of supervised learning with deep networks\n", + "\n", + "Like all statistical methods, supervised learning using neural\n", + "networks has important limitations. This is especially important when\n", + "one seeks to apply these methods, especially to physics problems. Like\n", + "all tools, DNNs are not a universal solution. Often, the same or\n", + "better performance on a task can be achieved by using a few\n", + "hand-engineered features (or even a collection of random\n", + "features). \n", + "\n", + "Here we list some of the important limitations of supervised neural network based models. \n", + "\n", + "\n", + "\n", + "* **Need labeled data**. All supervised learning methods, DNNs for supervised learning require labeled data. Often, labeled data is harder to acquire than unlabeled data (e.g. one must pay for human experts to label images).\n", + "\n", + "* **Supervised neural networks are extremely data intensive.** DNNs are data hungry. They perform best when data is plentiful. This is doubly so for supervised methods where the data must also be labeled. The utility of DNNs is extremely limited if data is hard to acquire or the datasets are small (hundreds to a few thousand samples). In this case, the performance of other methods that utilize hand-engineered features can exceed that of DNNs.\n", + "\n", + "* **Homogeneous data.** Almost all DNNs deal with homogeneous data of one type. It is very hard to design architectures that mix and match data types (i.e. some continuous variables, some discrete variables, some time series). In applications beyond images, video, and language, this is often what is required. In contrast, ensemble models like random forests or gradient-boosted trees have no difficulty handling mixed data types.\n", + "\n", + "* **Many problems are not about prediction.** In natural science we are often interested in learning something about the underlying distribution that generates the data. In this case, it is often difficult to cast these ideas in a supervised learning setting. While the problems are related, it is possible to make good predictions with a *wrong* model. The model might or might not be useful for understanding the underlying science.\n", + "\n", + "Some of these remarks are particular to DNNs, others are shared by all supervised learning methods. This motivates the use of unsupervised methods which in part circumvent these problems.\n", + "\n", + "\n", + "\n", + "\n", + "\n", + "\n", "## Convolutional Neural Networks (recognizing images)\n", "\n", "\n", @@ -265,14 +2367,12 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": 26, "metadata": { "collapsed": false }, "outputs": [], "source": [ - "%matplotlib inline\n", - "\n", "# import necessary packages\n", "import numpy as np\n", "import matplotlib.pyplot as plt\n", @@ -324,7 +2424,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 27, "metadata": { "collapsed": false }, @@ -355,7 +2455,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 28, "metadata": { "collapsed": false }, @@ -512,7 +2612,7 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": 29, "metadata": { "collapsed": false }, @@ -553,7 +2653,7 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": 30, "metadata": { "collapsed": false }, @@ -601,7 +2701,7 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 31, "metadata": { "collapsed": false }, @@ -652,7 +2752,7 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 32, "metadata": { "collapsed": false }, @@ -733,5 +2833,5 @@ ], "metadata": {}, "nbformat": 4, - "nbformat_minor": 2 + "nbformat_minor": 4 } diff --git a/doc/src/week41/week41.do.txt b/doc/src/week41/week41.do.txt index 77547edf1..ff44ae165 100644 --- a/doc/src/week41/week41.do.txt +++ b/doc/src/week41/week41.do.txt @@ -3,6 +3,1674 @@ AUTHOR: Morten Hjorth-Jensen {copyright, 1999-present|CC BY-NC} at Department of DATE: today +!split +===== Plan for week 40 ===== + +* Thursday: Building our own Feed-forward Neural Network +* Friday: Playing around with our own Feed-forward Neural Network and introduction to TensorFlow. Start convolutional Neural Networks. + +Reading suggestions for both days: "Aurelien Geron's chapters 10-11":"https://github.com/CompPhysics/MachineLearning/blob/master/doc/T\ +extbooks/TensorflowML.pdf" and Hastie et al chapter 11. + +!split +===== Overview video for week 41 ===== + +"Overview Video, from Stochastic Gradient methods to Neural Networks":"https://www.uio.no/studier/emner/matnat/fys/FYS-STK3155/h20\ +/forelesningsvideoer/OverviewWeek41.mp4?vrtx=view-as-webpage" + + +!split +===== Setting up the Back propagation algorithm ===== + + + +The four equations provide us with a way of computing the gradient of the cost function. Let us write this out in the form of an algorithm. + +!bblock +First, we set up the input data $\hat{x}$ and the activations +$\hat{z}_1$ of the input layer and compute the activation function and +the pertinent outputs $\hat{a}^1$. +!eblock + +!bblock +Secondly, we perform then the feed forward till we reach the output +layer and compute all $\hat{z}_l$ of the input layer and compute the +activation function and the pertinent outputs $\hat{a}^l$ for +$l=2,3,\dots,L$. +!eblock + +!bblock +Thereafter we compute the ouput error $\hat{\delta}^L$ by computing all +!bt +\[ +\delta_j^L = f'(z_j^L)\frac{\partial {\cal C}}{\partial (a_j^L)}. +\] +!et +!eblock + +!bblock +Then we compute the back propagate error for each $l=L-1,L-2,\dots,2$ as +!bt +\[ +\delta_j^l = \sum_k \delta_k^{l+1}w_{kj}^{l+1}f'(z_j^l). +\] +!et +!eblock + +!bblock +Finally, we update the weights and the biases using gradient descent for each $l=L-1,L-2,\dots,2$ and update the weights and biases according to the rules +!bt +\[ +w_{jk}^l\leftarrow = w_{jk}^l- \eta \delta_j^la_k^{l-1}, +\] +!et + +!bt +\[ +b_j^l \leftarrow b_j^l-\eta \frac{\partial {\cal C}}{\partial b_j^l}=b_j^l-\eta \delta_j^l, +\] +!et +!eblock + +The parameter $\eta$ is the learning parameter discussed in connection with the gradient descent methods. +Here it is convenient to use stochastic gradient descent (see the examples below) with mini-batches with an outer loop that steps through multiple epochs of training. + + + + +!split +===== Setting up a Multi-layer perceptron model for classification ===== + +We are now gong to develop an example based on the MNIST data +base. This is a classification problem and we need to use our +cross-entropy function we discussed in connection with logistic +regression. The cross-entropy defines our cost function for the +classificaton problems with neural networks. + +In binary classification with two classes $(0, 1)$ we define the +logistic/sigmoid function as the probability that a particular input +is in class $0$ or $1$. This is possible because the logistic +function takes any input from the real numbers and inputs a number +between 0 and 1, and can therefore be interpreted as a probability. It +also has other nice properties, such as a derivative that is simple to +calculate. + +For an input $\boldsymbol{a}$ from the hidden layer, the probability that the input $\boldsymbol{x}$ +is in class 0 or 1 is just. We let $\theta$ represent the unknown weights and biases to be adjusted by our equations). The variable $x$ +represents our activation values $z$. We have +!bt +\[ +P(y = 0 \mid \hat{x}, \hat{\theta}) = \frac{1}{1 + \exp{(- \hat{x}})} , +\] +!et +and +!bt +\[ +P(y = 1 \mid \hat{x}, \hat{\theta}) = 1 - P(y = 0 \mid \hat{x}, \hat{\theta}) , +\] +!et + +where $y \in \{0, 1\}$ and $\hat{\theta}$ represents the weights and biases +of our network. + + +!split +===== Defining the cost function ===== + +Our cost function is given as (see the Logistic regression lectures) +!bt +\[ +\mathcal{C}(\hat{\theta}) = - \ln P(\mathcal{D} \mid \hat{\theta}) = - \sum_{i=1}^n +y_i \ln[P(y_i = 0)] + (1 - y_i) \ln [1 - P(y_i = 0)] = \sum_{i=1}^n \mathcal{L}_i(\hat{\theta}) . +\] +!et + +This last equality means that we can interpret our *cost* function as a sum over the *loss* function +for each point in the dataset $\mathcal{L}_i(\hat{\theta})$. +The negative sign is just so that we can think about our algorithm as minimizing a positive number, rather +than maximizing a negative number. + +In *multiclass* classification it is common to treat each integer label as a so called *one-hot* vector: + +$y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) ,$ and + + +$y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) ,$ + + +i.e. a binary bit string of length $C$, where $C = 10$ is the number of classes in the MNIST dataset (numbers from $0$ to $9$).. + +If $\hat{x}_i$ is the $i$-th input (image), $y_{ic}$ refers to the $c$-th component of the $i$-th +output vector $\hat{y}_i$. +The probability of $\hat{x}_i$ being in class $c$ will be given by the softmax function: + +!bt +\[ +P(y_{ic} = 1 \mid \hat{x}_i, \hat{\theta}) = \frac{\exp{((\hat{a}_i^{hidden})^T \hat{w}_c)}} +{\sum_{c'=0}^{C-1} \exp{((\hat{a}_i^{hidden})^T \hat{w}_{c'})}} , +\] +!et + +which reduces to the logistic function in the binary case. +The likelihood of this $C$-class classifier +is now given as: + +!bt +\[ +P(\mathcal{D} \mid \hat{\theta}) = \prod_{i=1}^n \prod_{c=0}^{C-1} [P(y_{ic} = 1)]^{y_{ic}} . +\] +!et +Again we take the negative log-likelihood to define our cost function: + +!bt +\[ +\mathcal{C}(\hat{\theta}) = - \log{P(\mathcal{D} \mid \hat{\theta})}. +\] +!et +See the logistic regression lectures for a full definition of the cost function. + +The back propagation equations need now only a small change, namely the definition of a new cost function. We are thus ready to use the same equations as before! + +!split +===== Example: binary classification problem ===== + +As an example of the above, relevant for project 2 as well, let us consider a binary class. As discussed in our logistic regression lectures, we defined a cost function in terms of the parameters $\beta$ as +!bt +\[ +\mathcal{C}(\hat{\beta}) = - \sum_{i=1}^n \left(y_i\log{p(y_i \vert x_i,\hat{\beta})}+(1-y_i)\log{1-p(y_i \vert x_i,\hat{\beta})}\right), +\] +!et +where we had defined the logistic (sigmoid) function +!bt +\[ +p(y_i =1\vert x_i,\hat{\beta})=\frac{\exp{(\beta_0+\beta_1 x_i)}}{1+\exp{(\beta_0+\beta_1 x_i)}}, +\] +!et +and +!bt +\[ +p(y_i =0\vert x_i,\hat{\beta})=1-p(y_i =1\vert x_i,\hat{\beta}). +\] +!et +The parameters $\hat{\beta}$ were defined using a minimization method like gradient descent or Newton-Raphson's method. + +Now we replace $x_i$ with the activation $z_i^l$ for a given layer $l$ and the outputs as $y_i=a_i^l=f(z_i^l)$, with $z_i^l$ now being a function of the weights $w_{ij}^l$ and biases $b_i^l$. +We have then +!bt +\[ +a_i^l = y_i = \frac{\exp{(z_i^l)}}{1+\exp{(z_i^l)}}, +\] +!et +with +!bt +\[ +z_i^l = \sum_{j}w_{ij}^l a_j^{l-1}+b_i^l, +\] +!et +where the superscript $l-1$ indicates that these are the outputs from layer $l-1$. +Our cost function at the final layer $l=L$ is now +!bt +\[ +\mathcal{C}(\hat{W}) = - \sum_{i=1}^n \left(t_i\log{a_i^L}+(1-t_i)\log{(1-a_i^L)}\right), +\] +!et +where we have defined the targets $t_i$. The derivatives of the cost function with respect to the output $a_i^L$ are then easily calculated and we get +!bt +\[ +\frac{\partial \mathcal{C}(\hat{W})}{\partial a_i^L} = \frac{a_i^L-t_i}{a_i^L(1-a_i^L)}. +\] +!et +In case we use another activation function than the logistic one, we need to evaluate other derivatives. + + +!split +===== The Softmax function ===== +In case we employ the more general case given by the Softmax equation, we need to evaluate the derivative of the activation function with respect to the activation $z_i^l$, that is we need +!bt +\[ +\frac{\partial f(z_i^l)}{\partial w_{jk}^l} = +\frac{\partial f(z_i^l)}{\partial z_j^l} \frac{\partial z_j^l}{\partial w_{jk}^l}= \frac{\partial f(z_i^l)}{\partial z_j^l}a_k^{l-1}. +\] +!et +For the Softmax function we have +!bt +\[ +f(z_i^l) = \frac{\exp{(z_i^l)}}{\sum_{m=1}^K\exp{(z_m^l)}}. +\] +!et +Its derivative with respect to $z_j^l$ gives +!bt +\[ +\frac{\partial f(z_i^l)}{\partial z_j^l}= f(z_i^l)\left(\delta_{ij}-f(z_j^l)\right), +\] +!et +which in case of the simply binary model reduces to having $i=j$. + +!split +===== Developing a code for doing neural networks with back propagation ===== + + +One can identify a set of key steps when using neural networks to solve supervised learning problems: + +o Collect and pre-process data +o Define model and architecture +o Choose cost function and optimizer +o Train the model +o Evaluate model performance on test data +o Adjust hyperparameters (if necessary, network architecture) + +!split +===== Collect and pre-process data ===== + +Here we will be using the MNIST dataset, which is readily available through the _scikit-learn_ +package. You may also find it for example "here":"http://yann.lecun.com/exdb/mnist/". +The *MNIST* (Modified National Institute of Standards and Technology) database is a large database +of handwritten digits that is commonly used for training various image processing systems. +The MNIST dataset consists of 70 000 images of size $28\times 28$ pixels, each labeled from 0 to 9. +The scikit-learn dataset we will use consists of a selection of 1797 images of size $8\times 8$ collected and processed from this database. + +To feed data into a feed-forward neural network we need to represent +the inputs as a design/feature matrix $X = (n_{inputs}, n_{features})$. Each +row represents an *input*, in this case a handwritten digit, and +each column represents a *feature*, in this case a pixel. The +correct answers, also known as *labels* or *targets* are +represented as a 1D array of integers +$Y = (n_{inputs}) = (5, 3, 1, 8,...)$. + +As an example, say we want to build a neural network using supervised learning to predict Body-Mass Index (BMI) from +measurements of height (in m) +and weight (in kg). If we have measurements of 5 people the design/feature matrix could be for example: + +$$ X = \begin{bmatrix} +1.85 & 81\\ +1.71 & 65\\ +1.95 & 103\\ +1.55 & 42\\ +1.63 & 56 +\end{bmatrix} ,$$ + +and the targets would be: + +$$ Y = (23.7, 22.2, 27.1, 17.5, 21.1) $$ + +Since each input image is a 2D matrix, we need to flatten the image +(i.e. "unravel" the 2D matrix into a 1D array) to turn the data into a +design/feature matrix. This means we lose all spatial information in the +image, such as locality and translational invariance. More complicated +architectures such as Convolutional Neural Networks can take advantage +of such information, and are most commonly applied when analyzing +images. + + +!bc pycod +# import necessary packages +import numpy as np +import matplotlib.pyplot as plt +from sklearn import datasets + + +# ensure the same random numbers appear every time +np.random.seed(0) + +# display images in notebook +%matplotlib inline +plt.rcParams['figure.figsize'] = (12,12) + + +# download MNIST dataset +digits = datasets.load_digits() + +# define inputs and labels +inputs = digits.images +labels = digits.target + +print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape)) +print("labels = (n_inputs) = " + str(labels.shape)) + + +# flatten the image +# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64 +n_inputs = len(inputs) +inputs = inputs.reshape(n_inputs, -1) +print("X = (n_inputs, n_features) = " + str(inputs.shape)) + + +# choose some random images to display +indices = np.arange(n_inputs) +random_indices = np.random.choice(indices, size=5) + +for i, image in enumerate(digits.images[random_indices]): + plt.subplot(1, 5, i+1) + plt.axis('off') + plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest') + plt.title("Label: %d" % digits.target[random_indices[i]]) +plt.show() +!ec + +!split +===== Train and test datasets ===== + +Performing analysis before partitioning the dataset is a major error, that can lead to incorrect conclusions. + +We will reserve $80 \%$ of our dataset for training and $20 \%$ for testing. + +It is important that the train and test datasets are drawn randomly from our dataset, to ensure +no bias in the sampling. +Say you are taking measurements of weather data to predict the weather in the coming 5 days. +You don't want to train your model on measurements taken from the hours 00.00 to 12.00, and then test it on data +collected from 12.00 to 24.00. + + +!bc pycod +from sklearn.model_selection import train_test_split + +# one-liner from scikit-learn library +train_size = 0.8 +test_size = 1 - train_size +X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size, + test_size=test_size) + +# equivalently in numpy +def train_test_split_numpy(inputs, labels, train_size, test_size): + n_inputs = len(inputs) + inputs_shuffled = inputs.copy() + labels_shuffled = labels.copy() + + np.random.shuffle(inputs_shuffled) + np.random.shuffle(labels_shuffled) + + train_end = int(n_inputs*train_size) + X_train, X_test = inputs_shuffled[:train_end], inputs_shuffled[train_end:] + Y_train, Y_test = labels_shuffled[:train_end], labels_shuffled[train_end:] + + return X_train, X_test, Y_train, Y_test + +#X_train, X_test, Y_train, Y_test = train_test_split_numpy(inputs, labels, train_size, test_size) + +print("Number of training images: " + str(len(X_train))) +print("Number of test images: " + str(len(X_test))) +!ec + +!split +===== Define model and architecture ===== + +Our simple feed-forward neural network will consist of an *input* layer, a single *hidden* layer and an *output* layer. The activation $y$ of each neuron is a weighted sum of inputs, passed through an activation function. In case of the simple perceptron model we have + +$$ z = \sum_{i=1}^n w_i a_i ,$$ + +$$ y = f(z) ,$$ + +where $f$ is the activation function, $a_i$ represents input from neuron $i$ in the preceding layer +and $w_i$ is the weight to input $i$. +The activation of the neurons in the input layer is just the features (e.g. a pixel value). + +The simplest activation function for a neuron is the *Heaviside* function: + +$$ f(z) = +\begin{cases} +1, & z > 0\\ +0, & \text{otherwise} +\end{cases} +$$ + +A feed-forward neural network with this activation is known as a *perceptron*. +For a binary classifier (i.e. two classes, 0 or 1, dog or not-dog) we can also use this in our output layer. +This activation can be generalized to $k$ classes (using e.g. the *one-against-all* strategy), +and we call these architectures *multiclass perceptrons*. + +However, it is now common to use the terms Single Layer Perceptron (SLP) (1 hidden layer) and +Multilayer Perceptron (MLP) (2 or more hidden layers) to refer to feed-forward neural networks with any activation function. + +Typical choices for activation functions include the sigmoid function, hyperbolic tangent, and Rectified Linear Unit (ReLU). +We will be using the sigmoid function $\sigma(x)$: + +$$ f(x) = \sigma(x) = \frac{1}{1 + e^{-x}} ,$$ + +which is inspired by probability theory (see logistic regression) and was most commonly used until about 2011. See the discussion below concerning other activation functions. + +!split +===== Layers ===== + +* Input +Since each input image has 8x8 = 64 pixels or features, we have an input layer of 64 neurons. + +* Hidden layer +We will use 50 neurons in the hidden layer receiving input from the neurons in the input layer. +Since each neuron in the hidden layer is connected to the 64 inputs we have 64x50 = 3200 weights to the hidden layer. + +* Output +If we were building a binary classifier, it would be sufficient with a single neuron in the output layer, +which could output 0 or 1 according to the Heaviside function. This would be an example of a *hard* classifier, meaning it outputs the class of the input directly. However, if we are dealing with noisy data it is often beneficial to use a *soft* classifier, which outputs the probability of being in class 0 or 1. + +For a soft binary classifier, we could use a single neuron and interpret the output as either being the probability of being in class 0 or the probability of being in class 1. Alternatively we could use 2 neurons, and interpret each neuron as the probability of being in each class. + +Since we are doing multiclass classification, with 10 categories, it is natural to use 10 neurons in the output layer. We number the neurons $j = 0,1,...,9$. The activation of each output neuron $j$ will be according to the *softmax* function: + +$$ P(\text{class $j$} \mid \text{input $\hat{a}$}) = \frac{\exp{(\hat{a}^T \hat{w}_j)}} +{\sum_{c=0}^{9} \exp{(\hat{a}^T \hat{w}_c)}} ,$$ + +i.e. each neuron $j$ outputs the probability of being in class $j$ given an input from the hidden layer $\hat{a}$, with $\hat{w}_j$ the weights of neuron $j$ to the inputs. +The denominator is a normalization factor to ensure the outputs (probabilities) sum up to 1. +The exponent is just the weighted sum of inputs as before: + +$$ z_j = \sum_{i=1}^n w_ {ij} a_i+b_j.$$ + +Since each neuron in the output layer is connected to the 50 inputs from the hidden layer we have 50x10 = 500 +weights to the output layer. + +!split +===== Weights and biases ===== + +Typically weights are initialized with small values distributed around zero, drawn from a uniform +or normal distribution. Setting all weights to zero means all neurons give the same output, making the network useless. + +Adding a bias value to the weighted sum of inputs allows the neural network to represent a greater range +of values. Without it, any input with the value 0 will be mapped to zero (before being passed through the activation). The bias unit has an output of 1, and a weight to each neuron $j$, $b_j$: + +$$ z_j = \sum_{i=1}^n w_ {ij} a_i + b_j.$$ + +The bias weights $\hat{b}$ are often initialized to zero, but a small value like $0.01$ ensures all neurons have some output which can be backpropagated in the first training cycle. +!bc pycod +# building our neural network + +n_inputs, n_features = X_train.shape +n_hidden_neurons = 50 +n_categories = 10 + +# we make the weights normally distributed using numpy.random.randn + +# weights and bias in the hidden layer +hidden_weights = np.random.randn(n_features, n_hidden_neurons) +hidden_bias = np.zeros(n_hidden_neurons) + 0.01 + +# weights and bias in the output layer +output_weights = np.random.randn(n_hidden_neurons, n_categories) +output_bias = np.zeros(n_categories) + 0.01 +!ec + +!split +===== Feed-forward pass ===== + +Denote $F$ the number of features, $H$ the number of hidden neurons and $C$ the number of categories. +For each input image we calculate a weighted sum of input features (pixel values) to each neuron $j$ in the hidden layer $l$: + +$$ z_{j}^{l} = \sum_{i=1}^{F} w_{ij}^{l} x_i + b_{j}^{l},$$ + +this is then passed through our activation function + +$$ a_{j}^{l} = f(z_{j}^{l}) .$$ + +We calculate a weighted sum of inputs (activations in the hidden layer) to each neuron $j$ in the output layer: + +$$ z_{j}^{L} = \sum_{i=1}^{H} w_{ij}^{L} a_{i}^{l} + b_{j}^{L}.$$ + +Finally we calculate the output of neuron $j$ in the output layer using the softmax function: + +$$ a_{j}^{L} = \frac{\exp{(z_j^{L})}} +{\sum_{c=0}^{C-1} \exp{(z_c^{L})}} .$$ + +!split +===== Matrix multiplications ===== + +Since our data has the dimensions $X = (n_{inputs}, n_{features})$ and our weights to the hidden +layer have the dimensions +$W_{hidden} = (n_{features}, n_{hidden})$, +we can easily feed the network all our training data in one go by taking the matrix product + +$$ X W^{h} = (n_{inputs}, n_{hidden}),$$ + +and obtain a matrix that holds the weighted sum of inputs to the hidden layer +for each input image and each hidden neuron. +We also add the bias to obtain a matrix of weighted sums to the hidden layer $Z^{h}$: + +$$ \hat{z}^{l} = \hat{X} \hat{W}^{l} + \hat{b}^{l} ,$$ + +meaning the same bias (1D array with size equal number of hidden neurons) is added to each input image. +This is then passed through the activation: + +$$ \hat{a}^{l} = f(\hat{z}^l) .$$ + +This is fed to the output layer: + +$$ \hat{z}^{L} = \hat{a}^{L} \hat{W}^{L} + \hat{b}^{L} .$$ + +Finally we receive our output values for each image and each category by passing it through the softmax function: + +$$ output = softmax (\hat{z}^{L}) = (n_{inputs}, n_{categories}) .$$ + + +!bc pycod +# setup the feed-forward pass, subscript h = hidden layer + +def sigmoid(x): + return 1/(1 + np.exp(-x)) + +def feed_forward(X): + # weighted sum of inputs to the hidden layer + z_h = np.matmul(X, hidden_weights) + hidden_bias + # activation in the hidden layer + a_h = sigmoid(z_h) + + # weighted sum of inputs to the output layer + z_o = np.matmul(a_h, output_weights) + output_bias + # softmax output + # axis 0 holds each input and axis 1 the probabilities of each category + exp_term = np.exp(z_o) + probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True) + + return probabilities + +probabilities = feed_forward(X_train) +print("probabilities = (n_inputs, n_categories) = " + str(probabilities.shape)) +print("probability that image 0 is in category 0,1,2,...,9 = \n" + str(probabilities[0])) +print("probabilities sum up to: " + str(probabilities[0].sum())) +print() + +# we obtain a prediction by taking the class with the highest likelihood +def predict(X): + probabilities = feed_forward(X) + return np.argmax(probabilities, axis=1) + +predictions = predict(X_train) +print("predictions = (n_inputs) = " + str(predictions.shape)) +print("prediction for image 0: " + str(predictions[0])) +print("correct label for image 0: " + str(Y_train[0])) +!ec + +!split +===== Choose cost function and optimizer ===== + +To measure how well our neural network is doing we need to introduce a cost function. +We will call the function that gives the error of a single sample output the *loss* function, and the function +that gives the total error of our network across all samples the *cost* function. +A typical choice for multiclass classification is the *cross-entropy* loss, also known as the negative log likelihood. + +In *multiclass* classification it is common to treat each integer label as a so called *one-hot* vector: + +$$ y = 5 \quad \rightarrow \quad \hat{y} = (0, 0, 0, 0, 0, 1, 0, 0, 0, 0) ,$$ + + +$$ y = 1 \quad \rightarrow \quad \hat{y} = (0, 1, 0, 0, 0, 0, 0, 0, 0, 0) ,$$ + + +i.e. a binary bit string of length $C$, where $C = 10$ is the number of classes in the MNIST dataset. + +Let $y_{ic}$ denote the $c$-th component of the $i$-th one-hot vector. +We define the cost function $\mathcal{C}$ as a sum over the cross-entropy loss for each point $\hat{x}_i$ in the dataset. + +In the one-hot representation only one of the terms in the loss function is non-zero, namely the +probability of the correct category $c'$ +(i.e. the category $c'$ such that $y_{ic'} = 1$). This means that the cross entropy loss only punishes you for how wrong +you got the correct label. The probability of category $c$ is given by the softmax function. The vector $\hat{\theta}$ represents the parameters of our network, i.e. all the weights and biases. + + +!split +===== Optimizing the cost function ===== + +The network is trained by finding the weights and biases that minimize the cost function. One of the most widely used classes of methods is *gradient descent* and its generalizations. The idea behind gradient descent +is simply to adjust the weights in the direction where the gradient of the cost function is large and negative. This ensures we flow toward a *local* minimum of the cost function. +Each parameter $\theta$ is iteratively adjusted according to the rule + +$$ \theta_{i+1} = \theta_i - \eta \nabla \mathcal{C}(\theta_i) ,$$ + +where $\eta$ is known as the *learning rate*, which controls how big a step we take towards the minimum. +This update can be repeated for any number of iterations, or until we are satisfied with the result. + +A simple and effective improvement is a variant called *Batch Gradient Descent*. +Instead of calculating the gradient on the whole dataset, we calculate an approximation of the gradient +on a subset of the data called a *minibatch*. +If there are $N$ data points and we have a minibatch size of $M$, the total number of batches +is $N/M$. +We denote each minibatch $B_k$, with $k = 1, 2,...,N/M$. The gradient then becomes: + +$$ \nabla \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \nabla \mathcal{L}_i(\theta) \quad \rightarrow \quad +\frac{1}{M} \sum_{i \in B_k} \nabla \mathcal{L}_i(\theta) ,$$ + +i.e. instead of averaging the loss over the entire dataset, we average over a minibatch. + +This has two important benefits: +o Introducing stochasticity decreases the chance that the algorithm becomes stuck in a local minima. +o It significantly speeds up the calculation, since we do not have to use the entire dataset to calculate the gradient. + +The various optmization methods, with codes and algorithms, are discussed in our lectures on "Gradient descent approaches":"https://compphysics.github.io/MachineLearning/doc/pub/Splines/html/Splines-bs.html". + +!split +===== Regularization ===== + +It is common to add an extra term to the cost function, proportional +to the size of the weights. This is equivalent to constraining the +size of the weights, so that they do not grow out of control. +Constraining the size of the weights means that the weights cannot +grow arbitrarily large to fit the training data, and in this way +reduces *overfitting*. + +We will measure the size of the weights using the so called *L2-norm*, meaning our cost function becomes: + +$$ \mathcal{C}(\theta) = \frac{1}{N} \sum_{i=1}^N \mathcal{L}_i(\theta) \quad \rightarrow \quad +\frac{1}{N} \sum_{i=1}^N \mathcal{L}_i(\theta) + \lambda \lvert \lvert \hat{w} \rvert \rvert_2^2 += \frac{1}{N} \sum_{i=1}^N \mathcal{L}(\theta) + \lambda \sum_{ij} w_{ij}^2,$$ + +i.e. we sum up all the weights squared. The factor $\lambda$ is known as a regularization parameter. + + +In order to train the model, we need to calculate the derivative of +the cost function with respect to every bias and weight in the +network. In total our network has $(64 + 1)\times 50=3250$ weights in +the hidden layer and $(50 + 1)\times 10=510$ weights to the output +layer ($+1$ for the bias), and the gradient must be calculated for +every parameter. We use the *backpropagation* algorithm discussed +above. This is a clever use of the chain rule that allows us to +calculate the gradient efficently. + + +!split +===== Matrix multiplication ===== + +To more efficently train our network these equations are implemented using matrix operations. +The error in the output layer is calculated simply as, with $\hat{t}$ being our targets, + +$$ \delta_L = \hat{t} - \hat{y} = (n_{inputs}, n_{categories}) .$$ + +The gradient for the output weights is calculated as + +$$ \nabla W_{L} = \hat{a}^T \delta_L = (n_{hidden}, n_{categories}) ,$$ + +where $\hat{a} = (n_{inputs}, n_{hidden})$. This simply means that we are summing up the gradients for each input. +Since we are going backwards we have to transpose the activation matrix. + +The gradient with respect to the output bias is then + +$$ \nabla \hat{b}_{L} = \sum_{i=1}^{n_{inputs}} \delta_L = (n_{categories}) .$$ + +The error in the hidden layer is + +$$ \Delta_h = \delta_L W_{L}^T \circ f'(z_{h}) = \delta_L W_{L}^T \circ a_{h} \circ (1 - a_{h}) = (n_{inputs}, n_{hidden}) ,$$ + +where $f'(a_{h})$ is the derivative of the activation in the hidden layer. The matrix products mean +that we are summing up the products for each neuron in the output layer. The symbol $\circ$ denotes +the *Hadamard product*, meaning element-wise multiplication. + +This again gives us the gradients in the hidden layer: + +$$ \nabla W_{h} = X^T \delta_h = (n_{features}, n_{hidden}) ,$$ + +$$ \nabla b_{h} = \sum_{i=1}^{n_{inputs}} \delta_h = (n_{hidden}) .$$ + + +!bc pycod +# to categorical turns our integer vector into a onehot representation +from sklearn.metrics import accuracy_score + +# one-hot in numpy +def to_categorical_numpy(integer_vector): + n_inputs = len(integer_vector) + n_categories = np.max(integer_vector) + 1 + onehot_vector = np.zeros((n_inputs, n_categories)) + onehot_vector[range(n_inputs), integer_vector] = 1 + + return onehot_vector + +#Y_train_onehot, Y_test_onehot = to_categorical(Y_train), to_categorical(Y_test) +Y_train_onehot, Y_test_onehot = to_categorical_numpy(Y_train), to_categorical_numpy(Y_test) + +def feed_forward_train(X): + # weighted sum of inputs to the hidden layer + z_h = np.matmul(X, hidden_weights) + hidden_bias + # activation in the hidden layer + a_h = sigmoid(z_h) + + # weighted sum of inputs to the output layer + z_o = np.matmul(a_h, output_weights) + output_bias + # softmax output + # axis 0 holds each input and axis 1 the probabilities of each category + exp_term = np.exp(z_o) + probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True) + + # for backpropagation need activations in hidden and output layers + return a_h, probabilities + +def backpropagation(X, Y): + a_h, probabilities = feed_forward_train(X) + + # error in the output layer + error_output = probabilities - Y + # error in the hidden layer + error_hidden = np.matmul(error_output, output_weights.T) * a_h * (1 - a_h) + + # gradients for the output layer + output_weights_gradient = np.matmul(a_h.T, error_output) + output_bias_gradient = np.sum(error_output, axis=0) + + # gradient for the hidden layer + hidden_weights_gradient = np.matmul(X.T, error_hidden) + hidden_bias_gradient = np.sum(error_hidden, axis=0) + + return output_weights_gradient, output_bias_gradient, hidden_weights_gradient, hidden_bias_gradient + +print("Old accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train))) + +eta = 0.01 +lmbd = 0.01 +for i in range(1000): + # calculate gradients + dWo, dBo, dWh, dBh = backpropagation(X_train, Y_train_onehot) + + # regularization term gradients + dWo += lmbd * output_weights + dWh += lmbd * hidden_weights + + # update weights and biases + output_weights -= eta * dWo + output_bias -= eta * dBo + hidden_weights -= eta * dWh + hidden_bias -= eta * dBh + +print("New accuracy on training data: " + str(accuracy_score(predict(X_train), Y_train))) +!ec + +!split +===== Improving performance ===== + +As we can see the network does not seem to be learning at all. It seems to be just guessing the label for each image. +In order to obtain a network that does something useful, we will have to do a bit more work. + +The choice of *hyperparameters* such as learning rate and regularization parameter is hugely influential for the performance of the network. Typically a *grid-search* is performed, wherein we test different hyperparameters separated by orders of magnitude. For example we could test the learning rates $\eta = 10^{-6}, 10^{-5},...,10^{-1}$ with different regularization parameters $\lambda = 10^{-6},...,10^{-0}$. + +Next, we haven't implemented minibatching yet, which introduces stochasticity and is though to act as an important regularizer on the weights. We call a feed-forward + backward pass with a minibatch an *iteration*, and a full training period +going through the entire dataset ($n/M$ batches) an *epoch*. + +If this does not improve network performance, you may want to consider altering the network architecture, adding more neurons or hidden layers. +Andrew Ng goes through some of these considerations in this "video":"https://youtu.be/F1ka6a13S9I". You can find a summary of the video "here":"https://kevinzakka.github.io/2016/09/26/applying-deep-learning/". + +!split +===== Full object-oriented implementation ===== + +It is very natural to think of the network as an object, with specific instances of the network +being realizations of this object with different hyperparameters. An implementation using Python classes provides a clean structure and interface, and the full implementation of our neural network is given below. + + +!bc pycod +class NeuralNetwork: + def __init__( + self, + X_data, + Y_data, + n_hidden_neurons=50, + n_categories=10, + epochs=10, + batch_size=100, + eta=0.1, + lmbd=0.0): + + self.X_data_full = X_data + self.Y_data_full = Y_data + + self.n_inputs = X_data.shape[0] + self.n_features = X_data.shape[1] + self.n_hidden_neurons = n_hidden_neurons + self.n_categories = n_categories + + self.epochs = epochs + self.batch_size = batch_size + self.iterations = self.n_inputs // self.batch_size + self.eta = eta + self.lmbd = lmbd + + self.create_biases_and_weights() + + def create_biases_and_weights(self): + self.hidden_weights = np.random.randn(self.n_features, self.n_hidden_neurons) + self.hidden_bias = np.zeros(self.n_hidden_neurons) + 0.01 + + self.output_weights = np.random.randn(self.n_hidden_neurons, self.n_categories) + self.output_bias = np.zeros(self.n_categories) + 0.01 + + def feed_forward(self): + # feed-forward for training + self.z_h = np.matmul(self.X_data, self.hidden_weights) + self.hidden_bias + self.a_h = sigmoid(self.z_h) + + self.z_o = np.matmul(self.a_h, self.output_weights) + self.output_bias + + exp_term = np.exp(self.z_o) + self.probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True) + + def feed_forward_out(self, X): + # feed-forward for output + z_h = np.matmul(X, self.hidden_weights) + self.hidden_bias + a_h = sigmoid(z_h) + + z_o = np.matmul(a_h, self.output_weights) + self.output_bias + + exp_term = np.exp(z_o) + probabilities = exp_term / np.sum(exp_term, axis=1, keepdims=True) + return probabilities + + def backpropagation(self): + error_output = self.probabilities - self.Y_data + error_hidden = np.matmul(error_output, self.output_weights.T) * self.a_h * (1 - self.a_h) + + self.output_weights_gradient = np.matmul(self.a_h.T, error_output) + self.output_bias_gradient = np.sum(error_output, axis=0) + + self.hidden_weights_gradient = np.matmul(self.X_data.T, error_hidden) + self.hidden_bias_gradient = np.sum(error_hidden, axis=0) + + if self.lmbd > 0.0: + self.output_weights_gradient += self.lmbd * self.output_weights + self.hidden_weights_gradient += self.lmbd * self.hidden_weights + + self.output_weights -= self.eta * self.output_weights_gradient + self.output_bias -= self.eta * self.output_bias_gradient + self.hidden_weights -= self.eta * self.hidden_weights_gradient + self.hidden_bias -= self.eta * self.hidden_bias_gradient + + def predict(self, X): + probabilities = self.feed_forward_out(X) + return np.argmax(probabilities, axis=1) + + def predict_probabilities(self, X): + probabilities = self.feed_forward_out(X) + return probabilities + + def train(self): + data_indices = np.arange(self.n_inputs) + + for i in range(self.epochs): + for j in range(self.iterations): + # pick datapoints with replacement + chosen_datapoints = np.random.choice( + data_indices, size=self.batch_size, replace=False + ) + + # minibatch training data + self.X_data = self.X_data_full[chosen_datapoints] + self.Y_data = self.Y_data_full[chosen_datapoints] + + self.feed_forward() + self.backpropagation() +!ec + +!split +===== Evaluate model performance on test data ===== + +To measure the performance of our network we evaluate how well it does it data it has never seen before, i.e. the test data. +We measure the performance of the network using the *accuracy* score. +The accuracy is as you would expect just the number of images correctly labeled divided by the total number of images. A perfect classifier will have an accuracy score of $1$. + +$$ \text{Accuracy} = \frac{\sum_{i=1}^n I(\hat{y}_i = y_i)}{n} ,$$ + +where $I$ is the indicator function, $1$ if $\hat{y}_i = y_i$ and $0$ otherwise. + + +!bc pycod +epochs = 100 +batch_size = 100 + +dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size, + n_hidden_neurons=n_hidden_neurons, n_categories=n_categories) +dnn.train() +test_predict = dnn.predict(X_test) + +# accuracy score from scikit library +print("Accuracy score on test set: ", accuracy_score(Y_test, test_predict)) + +# equivalent in numpy +def accuracy_score_numpy(Y_test, Y_pred): + return np.sum(Y_test == Y_pred) / len(Y_test) + +#print("Accuracy score on test set: ", accuracy_score_numpy(Y_test, test_predict)) +!ec + +!split +===== Adjust hyperparameters ===== + +We now perform a grid search to find the optimal hyperparameters for the network. +Note that we are only using 1 layer with 50 neurons, and human performance is estimated to be around $98\%$ ($2\%$ error rate). + +!bc pycod +eta_vals = np.logspace(-5, 1, 7) +lmbd_vals = np.logspace(-5, 1, 7) +# store the models for later use +DNN_numpy = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object) + +# grid search +for i, eta in enumerate(eta_vals): + for j, lmbd in enumerate(lmbd_vals): + dnn = NeuralNetwork(X_train, Y_train_onehot, eta=eta, lmbd=lmbd, epochs=epochs, batch_size=batch_size, + n_hidden_neurons=n_hidden_neurons, n_categories=n_categories) + dnn.train() + + DNN_numpy[i][j] = dnn + + test_predict = dnn.predict(X_test) + + print("Learning rate = ", eta) + print("Lambda = ", lmbd) + print("Accuracy score on test set: ", accuracy_score(Y_test, test_predict)) + print() +!ec + +!split +===== Visualization ===== + +!bc pycod +# visual representation of grid search +# uses seaborn heatmap, you can also do this with matplotlib imshow +import seaborn as sns + +sns.set() + +train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) +test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) + +for i in range(len(eta_vals)): + for j in range(len(lmbd_vals)): + dnn = DNN_numpy[i][j] + + train_pred = dnn.predict(X_train) + test_pred = dnn.predict(X_test) + + train_accuracy[i][j] = accuracy_score(Y_train, train_pred) + test_accuracy[i][j] = accuracy_score(Y_test, test_pred) + + +fig, ax = plt.subplots(figsize = (10, 10)) +sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis") +ax.set_title("Training Accuracy") +ax.set_ylabel("$\eta$") +ax.set_xlabel("$\lambda$") +plt.show() + +fig, ax = plt.subplots(figsize = (10, 10)) +sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis") +ax.set_title("Test Accuracy") +ax.set_ylabel("$\eta$") +ax.set_xlabel("$\lambda$") +plt.show() +!ec + +!split +===== scikit-learn implementation ===== + +_scikit-learn_ focuses more +on traditional machine learning methods, such as regression, +clustering, decision trees, etc. As such, it has only two types of +neural networks: Multi Layer Perceptron outputting continuous values, +*MPLRegressor*, and Multi Layer Perceptron outputting labels, +*MLPClassifier*. We will see how simple it is to use these classes. + +_scikit-learn_ implements a few improvements from our neural network, +such as early stopping, a varying learning rate, different +optimization methods, etc. We would therefore expect a better +performance overall. + +!bc pycod +from sklearn.neural_network import MLPClassifier +# store models for later use +DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object) + +for i, eta in enumerate(eta_vals): + for j, lmbd in enumerate(lmbd_vals): + dnn = MLPClassifier(hidden_layer_sizes=(n_hidden_neurons), activation='logistic', + alpha=lmbd, learning_rate_init=eta, max_iter=epochs) + dnn.fit(X_train, Y_train) + + DNN_scikit[i][j] = dnn + + print("Learning rate = ", eta) + print("Lambda = ", lmbd) + print("Accuracy score on test set: ", dnn.score(X_test, Y_test)) + print() +!ec + + +!split +===== Visualization ===== +!bc pycod +# optional +# visual representation of grid search +# uses seaborn heatmap, could probably do this in matplotlib +import seaborn as sns + +sns.set() + +train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) +test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) + +for i in range(len(eta_vals)): + for j in range(len(lmbd_vals)): + dnn = DNN_scikit[i][j] + + train_pred = dnn.predict(X_train) + test_pred = dnn.predict(X_test) + + train_accuracy[i][j] = accuracy_score(Y_train, train_pred) + test_accuracy[i][j] = accuracy_score(Y_test, test_pred) + + +fig, ax = plt.subplots(figsize = (10, 10)) +sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis") +ax.set_title("Training Accuracy") +ax.set_ylabel("$\eta$") +ax.set_xlabel("$\lambda$") +plt.show() + +fig, ax = plt.subplots(figsize = (10, 10)) +sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis") +ax.set_title("Test Accuracy") +ax.set_ylabel("$\eta$") +ax.set_xlabel("$\lambda$") +plt.show() +!ec + + +!split +===== Building neural networks in Tensorflow and Keras ===== + +Now we want to build on the experience gained from our neural network implementation in NumPy and scikit-learn +and use it to construct a neural network in Tensorflow. Once we have constructed a neural network in NumPy +and Tensorflow, building one in Keras is really quite trivial, though the performance may suffer. + +In our previous example we used only one hidden layer, and in this we will use two. From this it should be quite +clear how to build one using an arbitrary number of hidden layers, using data structures such as Python lists or +NumPy arrays. + +!split +===== Tensorflow ===== + +Tensorflow is an open source library machine learning library +developed by the Google Brain team for internal use. It was released +under the Apache 2.0 open source license in November 9, 2015. + +Tensorflow is a computational framework that allows you to construct +machine learning models at different levels of abstraction, from +high-level, object-oriented APIs like Keras, down to the C++ kernels +that Tensorflow is built upon. The higher levels of abstraction are +simpler to use, but less flexible, and our choice of implementation +should reflect the problems we are trying to solve. + +"Tensorflow uses":"https://www.tensorflow.org/guide/graphs" so-called graphs to represent your computation +in terms of the dependencies between individual operations, such that you first build a Tensorflow *graph* +to represent your model, and then create a Tensorflow *session* to run the graph. + +In this guide we will analyze the same data as we did in our NumPy and +scikit-learn tutorial, gathered from the MNIST database of images. We +will give an introduction to the lower level Python Application +Program Interfaces (APIs), and see how we use them to build our graph. +Then we will build (effectively) the same graph in Keras, to see just +how simple solving a machine learning problem can be. + +To install tensorflow on Unix/Linux systems, use pip as +!bc pycod +pip3 install tensorflow +!ec +and/or if you use _anaconda_, just write (or install from the graphical user interface) +!bc pycod +conda install tensorflow +!ec + +!split +===== Collect and pre-process data ===== + +!bc pycod +# import necessary packages +import numpy as np +import matplotlib.pyplot as plt +from sklearn import datasets + + +# ensure the same random numbers appear every time +np.random.seed(0) + +# display images in notebook +%matplotlib inline +plt.rcParams['figure.figsize'] = (12,12) + + +# download MNIST dataset +digits = datasets.load_digits() + +# define inputs and labels +inputs = digits.images +labels = digits.target + +print("inputs = (n_inputs, pixel_width, pixel_height) = " + str(inputs.shape)) +print("labels = (n_inputs) = " + str(labels.shape)) + + +# flatten the image +# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64 +n_inputs = len(inputs) +inputs = inputs.reshape(n_inputs, -1) +print("X = (n_inputs, n_features) = " + str(inputs.shape)) + + +# choose some random images to display +indices = np.arange(n_inputs) +random_indices = np.random.choice(indices, size=5) + +for i, image in enumerate(digits.images[random_indices]): + plt.subplot(1, 5, i+1) + plt.axis('off') + plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest') + plt.title("Label: %d" % digits.target[random_indices[i]]) +plt.show() +!ec + +!bc pycod +from keras.utils import to_categorical +from sklearn.model_selection import train_test_split + +# one-hot representation of labels +labels = to_categorical(labels) + +# split into train and test data +train_size = 0.8 +test_size = 1 - train_size +X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size, + test_size=test_size) +!ec + +!split +===== Using TensorFlow backend ===== + +o Define model and architecture +o Choose cost function and optimizer + +!bc pycod +import tensorflow as tf + +class NeuralNetworkTensorflow: + def __init__( + self, + X_train, + Y_train, + X_test, + Y_test, + n_neurons_layer1=100, + n_neurons_layer2=50, + n_categories=2, + epochs=10, + batch_size=100, + eta=0.1, + lmbd=0.0): + + # keep track of number of steps + self.global_step = tf.Variable(0, dtype=tf.int32, trainable=False, name='global_step') + + self.X_train = X_train + self.Y_train = Y_train + self.X_test = X_test + self.Y_test = Y_test + + self.n_inputs = X_train.shape[0] + self.n_features = X_train.shape[1] + self.n_neurons_layer1 = n_neurons_layer1 + self.n_neurons_layer2 = n_neurons_layer2 + self.n_categories = n_categories + + self.epochs = epochs + self.batch_size = batch_size + self.iterations = self.n_inputs // self.batch_size + self.eta = eta + self.lmbd = lmbd + + # build network piece by piece + # name scopes (with) are used to enforce creation of new variables + # https://www.tensorflow.org/guide/variables + self.create_placeholders() + self.create_DNN() + self.create_loss() + self.create_optimiser() + self.create_accuracy() + + def create_placeholders(self): + # placeholders are fine here, but "Datasets" are the preferred method + # of streaming data into a model + with tf.name_scope('data'): + self.X = tf.placeholder(tf.float32, shape=(None, self.n_features), name='X_data') + self.Y = tf.placeholder(tf.float32, shape=(None, self.n_categories), name='Y_data') + + def create_DNN(self): + with tf.name_scope('DNN'): + # the weights are stored to calculate regularization loss later + + # Fully connected layer 1 + self.W_fc1 = self.weight_variable([self.n_features, self.n_neurons_layer1], name='fc1', dtype=tf.float32) + b_fc1 = self.bias_variable([self.n_neurons_layer1], name='fc1', dtype=tf.float32) + a_fc1 = tf.nn.sigmoid(tf.matmul(self.X, self.W_fc1) + b_fc1) + + # Fully connected layer 2 + self.W_fc2 = self.weight_variable([self.n_neurons_layer1, self.n_neurons_layer2], name='fc2', dtype=tf.float32) + b_fc2 = self.bias_variable([self.n_neurons_layer2], name='fc2', dtype=tf.float32) + a_fc2 = tf.nn.sigmoid(tf.matmul(a_fc1, self.W_fc2) + b_fc2) + + # Output layer + self.W_out = self.weight_variable([self.n_neurons_layer2, self.n_categories], name='out', dtype=tf.float32) + b_out = self.bias_variable([self.n_categories], name='out', dtype=tf.float32) + self.z_out = tf.matmul(a_fc2, self.W_out) + b_out + + def create_loss(self): + with tf.name_scope('loss'): + softmax_loss = tf.reduce_mean(tf.nn.softmax_cross_entropy_with_logits_v2(labels=self.Y, logits=self.z_out)) + + regularizer_loss_fc1 = tf.nn.l2_loss(self.W_fc1) + regularizer_loss_fc2 = tf.nn.l2_loss(self.W_fc2) + regularizer_loss_out = tf.nn.l2_loss(self.W_out) + regularizer_loss = self.lmbd*(regularizer_loss_fc1 + regularizer_loss_fc2 + regularizer_loss_out) + + self.loss = softmax_loss + regularizer_loss + + def create_accuracy(self): + with tf.name_scope('accuracy'): + probabilities = tf.nn.softmax(self.z_out) + predictions = tf.argmax(probabilities, axis=1) + labels = tf.argmax(self.Y, axis=1) + + correct_predictions = tf.equal(predictions, labels) + correct_predictions = tf.cast(correct_predictions, tf.float32) + self.accuracy = tf.reduce_mean(correct_predictions) + + def create_optimiser(self): + with tf.name_scope('optimizer'): + self.optimizer = tf.train.GradientDescentOptimizer(learning_rate=self.eta).minimize(self.loss, global_step=self.global_step) + + def weight_variable(self, shape, name='', dtype=tf.float32): + initial = tf.truncated_normal(shape, stddev=0.1) + return tf.Variable(initial, name=name, dtype=dtype) + + def bias_variable(self, shape, name='', dtype=tf.float32): + initial = tf.constant(0.1, shape=shape) + return tf.Variable(initial, name=name, dtype=dtype) + + def fit(self): + data_indices = np.arange(self.n_inputs) + + with tf.Session() as sess: + sess.run(tf.global_variables_initializer()) + for i in range(self.epochs): + for j in range(self.iterations): + chosen_datapoints = np.random.choice(data_indices, size=self.batch_size, replace=False) + batch_X, batch_Y = self.X_train[chosen_datapoints], self.Y_train[chosen_datapoints] + + sess.run([DNN.loss, DNN.optimizer], + feed_dict={DNN.X: batch_X, + DNN.Y: batch_Y}) + accuracy = sess.run(DNN.accuracy, + feed_dict={DNN.X: batch_X, + DNN.Y: batch_Y}) + step = sess.run(DNN.global_step) + + self.train_loss, self.train_accuracy = sess.run([DNN.loss, DNN.accuracy], + feed_dict={DNN.X: self.X_train, + DNN.Y: self.Y_train}) + + self.test_loss, self.test_accuracy = sess.run([DNN.loss, DNN.accuracy], + feed_dict={DNN.X: self.X_test, + DNN.Y: self.Y_test}) +!ec + + +!split +===== Optimizing and using gradient descent ===== + +!bc pycod +epochs = 100 +batch_size = 100 +n_neurons_layer1 = 100 +n_neurons_layer2 = 50 +n_categories = 10 +eta_vals = np.logspace(-5, 1, 7) +lmbd_vals = np.logspace(-5, 1, 7) +!ec + + +!bc pycod +DNN_tf = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object) + +for i, eta in enumerate(eta_vals): + for j, lmbd in enumerate(lmbd_vals): + DNN = NeuralNetworkTensorflow(X_train, Y_train, X_test, Y_test, + n_neurons_layer1, n_neurons_layer2, n_categories, + epochs=epochs, batch_size=batch_size, eta=eta, lmbd=lmbd) + DNN.fit() + + DNN_tf[i][j] = DNN + + print("Learning rate = ", eta) + print("Lambda = ", lmbd) + print("Test accuracy: %.3f" % DNN.test_accuracy) + print() +!ec + +!bc pycod +# optional +# visual representation of grid search +# uses seaborn heatmap, could probably do this in matplotlib +import seaborn as sns + +sns.set() + +train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) +test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) + +for i in range(len(eta_vals)): + for j in range(len(lmbd_vals)): + DNN = DNN_tf[i][j] + + train_accuracy[i][j] = DNN.train_accuracy + test_accuracy[i][j] = DNN.test_accuracy + + +fig, ax = plt.subplots(figsize = (10, 10)) +sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis") +ax.set_title("Training Accuracy") +ax.set_ylabel("$\eta$") +ax.set_xlabel("$\lambda$") +plt.show() + +fig, ax = plt.subplots(figsize = (10, 10)) +sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis") +ax.set_title("Test Accuracy") +ax.set_ylabel("$\eta$") +ax.set_xlabel("$\lambda$") +plt.show() +!ec + +!bc pycod +# optional +# we can use log files to visualize our graph in Tensorboard +writer = tf.summary.FileWriter('logs/') +writer.add_graph(tf.get_default_graph()) +!ec + + +!split +===== Using Keras ===== + +Keras is a high level "neural network":"https://en.wikipedia.org/wiki/Application_programming_interface" +that supports Tensorflow, CTNK and Theano as backends. +If you have Tensorflow installed Keras is available through the *tf.keras* module. +If you have Anaconda installed you may run the following command +!bc pycod +conda install keras +!ec + +Alternatively, if you have Tensorflow or one of the other supported backends install you may use the pip package manager: + +!bc pycod +pip3 install keras +!ec +or look up the "instructions here":"https://keras.io/". + +!bc pycod +from keras.models import Sequential +from keras.layers import Dense +from keras.regularizers import l2 +from keras.optimizers import SGD + +def create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories, eta, lmbd): + model = Sequential() + model.add(Dense(n_neurons_layer1, activation='sigmoid', kernel_regularizer=l2(lmbd))) + model.add(Dense(n_neurons_layer2, activation='sigmoid', kernel_regularizer=l2(lmbd))) + model.add(Dense(n_categories, activation='softmax')) + + sgd = SGD(lr=eta) + model.compile(loss='categorical_crossentropy', optimizer=sgd, metrics=['accuracy']) + + return model +!ec + +!bc pycod +DNN_keras = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object) + +for i, eta in enumerate(eta_vals): + for j, lmbd in enumerate(lmbd_vals): + DNN = create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories, + eta=eta, lmbd=lmbd) + DNN.fit(X_train, Y_train, epochs=epochs, batch_size=batch_size, verbose=0) + scores = DNN.evaluate(X_test, Y_test) + + DNN_keras[i][j] = DNN + + print("Learning rate = ", eta) + print("Lambda = ", lmbd) + print("Test accuracy: %.3f" % scores[1]) + print() +!ec + +!bc pycod +# optional +# visual representation of grid search +# uses seaborn heatmap, could probably do this in matplotlib +import seaborn as sns + +sns.set() + +train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) +test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) + +for i in range(len(eta_vals)): + for j in range(len(lmbd_vals)): + DNN = DNN_keras[i][j] + + train_accuracy[i][j] = DNN.evaluate(X_train, Y_train)[1] + test_accuracy[i][j] = DNN.evaluate(X_test, Y_test)[1] + + +fig, ax = plt.subplots(figsize = (10, 10)) +sns.heatmap(train_accuracy, annot=True, ax=ax, cmap="viridis") +ax.set_title("Training Accuracy") +ax.set_ylabel("$\eta$") +ax.set_xlabel("$\lambda$") +plt.show() + +fig, ax = plt.subplots(figsize = (10, 10)) +sns.heatmap(test_accuracy, annot=True, ax=ax, cmap="viridis") +ax.set_title("Test Accuracy") +ax.set_ylabel("$\eta$") +ax.set_xlabel("$\lambda$") +plt.show() +!ec + + + + +!split +===== Which activation function should I use? ===== + +The Back propagation algorithm we derived above works by going from +the output layer to the input layer, propagating the error gradient on +the way. Once the algorithm has computed the gradient of the cost +function with regards to each parameter in the network, it uses these +gradients to update each parameter with a Gradient Descent (GD) step. + + +Unfortunately for us, the gradients often get smaller and smaller as the +algorithm progresses down to the first hidden layers. As a result, the +GD update leaves the lower layer connection weights +virtually unchanged, and training never converges to a good +solution. This is known in the literature as +_the vanishing gradients problem_. + +In other cases, the opposite can happen, namely the the gradients can grow bigger and +bigger. The result is that many of the layers get large updates of the +weights the +algorithm diverges. This is the _exploding gradients problem_, which is +mostly encountered in recurrent neural networks. More generally, deep +neural networks suffer from unstable gradients, different layers may +learn at widely different speeds + +!split +===== Is the Logistic activation function (Sigmoid) our choice? ===== + +Although this unfortunate behavior has been empirically observed for +quite a while (it was one of the reasons why deep neural networks were +mostly abandoned for a long time), it is only around 2010 that +significant progress was made in understanding it. + +A paper titled "Understanding the Difficulty of Training Deep +Feedforward Neural Networks by Xavier Glorot and Yoshua Bengio":"http://proceedings.mlr.press/v9/glorot10a.html" found that +the problems with the popular logistic +sigmoid activation function and the weight initialization technique +that was most popular at the time, namely random initialization using +a normal distribution with a mean of 0 and a standard deviation of +1. + +They showed that with this activation function and this +initialization scheme, the variance of the outputs of each layer is +much greater than the variance of its inputs. Going forward in the +network, the variance keeps increasing after each layer until the +activation function saturates at the top layers. This is actually made +worse by the fact that the logistic function has a mean of 0.5, not 0 +(the hyperbolic tangent function has a mean of 0 and behaves slightly +better than the logistic function in deep networks). + + +!split +===== The derivative of the Logistic funtion ===== + +Looking at the logistic activation function, when inputs become large +(negative or positive), the function saturates at 0 or 1, with a +derivative extremely close to 0. Thus when backpropagation kicks in, +it has virtually no gradient to propagate back through the network, +and what little gradient exists keeps getting diluted as +backpropagation progresses down through the top layers, so there is +really nothing left for the lower layers. + +In their paper, Glorot and Bengio propose a way to significantly +alleviate this problem. We need the signal to flow properly in both +directions: in the forward direction when making predictions, and in +the reverse direction when backpropagating gradients. We don’t want +the signal to die out, nor do we want it to explode and saturate. For +the signal to flow properly, the authors argue that we need the +variance of the outputs of each layer to be equal to the variance of +its inputs, and we also need the gradients to have equal variance +before and after flowing through a layer in the reverse direction. + + + +One of the insights in the 2010 paper by Glorot and Bengio was that +the vanishing/exploding gradients problems were in part due to a poor +choice of activation function. Until then most people had assumed that +if Nature had chosen to use roughly sigmoid activation functions in +biological neurons, they must be an excellent choice. But it turns out +that other activation functions behave much better in deep neural +networks, in particular the ReLU activation function, mostly because +it does not saturate for positive values (and also because it is quite +fast to compute). + + +!split +===== The RELU function family ===== + +The ReLU activation function suffers from a problem known as the dying +ReLUs: during training, some neurons effectively die, meaning they +stop outputting anything other than 0. + +In some cases, you may find that half of your network’s neurons are +dead, especially if you used a large learning rate. During training, +if a neuron’s weights get updated such that the weighted sum of the +neuron’s inputs is negative, it will start outputting 0. When this +happen, the neuron is unlikely to come back to life since the gradient +of the ReLU function is 0 when its input is negative. + +To solve this problem, nowadays practitioners use a variant of the ReLU +function, such as the leaky ReLU discussed above or the so-called +exponential linear unit (ELU) function + + +!bt +\[ +ELU(z) = \left\{\begin{array}{cc} \alpha\left( \exp{(z)}-1\right) & z < 0,\\ z & z \ge 0.\end{array}\right. +\] +!et + +!split +===== Which activation function should we use? ===== + +In general it seems that the ELU activation function is better than +the leaky ReLU function (and its variants), which is better than +ReLU. ReLU performs better than $\tanh$ which in turn performs better +than the logistic function. + +If runtime +performance is an issue, then you may opt for the leaky ReLU function over the +ELU function If you don’t +want to tweak yet another hyperparameter, you may just use the default +$\alpha$ of $0.01$ for the leaky ReLU, and $1$ for ELU. If you have +spare time and computing power, you can use cross-validation or +bootstrap to evaluate other activation functions. + + +!split +===== A top-down perspective on Neural networks ===== + + +The first thing we would like to do is divide the data into two or three +parts. A training set, a validation or dev (development) set, and a +test set. The test set is the data on which we want to make +predictions. The dev set is a subset of the training data we use to +check how well we are doing out-of-sample, after training the model on +the training dataset. We use the validation error as a proxy for the +test error in order to make tweaks to our model. It is crucial that we +do not use any of the test data to train the algorithm. This is a +cardinal sin in ML. Then: + + +* Estimate optimal error rate + +* Minimize underfitting (bias) on training data set. + +* Make sure you are not overfitting. + +If the validation and test sets are drawn from the same distributions, +then a good performance on the validation set should lead to similarly +good performance on the test set. + +However, sometimes +the training data and test data differ in subtle ways because, for +example, they are collected using slightly different methods, or +because it is cheaper to collect data in one way versus another. In +this case, there can be a mismatch between the training and test +data. This can lead to the neural network overfitting these small +differences between the test and training sets, and a poor performance +on the test set despite having a good performance on the validation +set. To rectify this, Andrew Ng suggests making two validation or dev +sets, one constructed from the training data and one constructed from +the test data. The difference between the performance of the algorithm +on these two validation sets quantifies the train-test mismatch. This +can serve as another important diagnostic when using DNNs for +supervised learning. + +!split +===== Limitations of supervised learning with deep networks ===== + +Like all statistical methods, supervised learning using neural +networks has important limitations. This is especially important when +one seeks to apply these methods, especially to physics problems. Like +all tools, DNNs are not a universal solution. Often, the same or +better performance on a task can be achieved by using a few +hand-engineered features (or even a collection of random +features). + +Here we list some of the important limitations of supervised neural network based models. + + + +* _Need labeled data_. All supervised learning methods, DNNs for supervised learning require labeled data. Often, labeled data is harder to acquire than unlabeled data (e.g. one must pay for human experts to label images). +* _Supervised neural networks are extremely data intensive._ DNNs are data hungry. They perform best when data is plentiful. This is doubly so for supervised methods where the data must also be labeled. The utility of DNNs is extremely limited if data is hard to acquire or the datasets are small (hundreds to a few thousand samples). In this case, the performance of other methods that utilize hand-engineered features can exceed that of DNNs. +* _Homogeneous data._ Almost all DNNs deal with homogeneous data of one type. It is very hard to design architectures that mix and match data types (i.e.~some continuous variables, some discrete variables, some time series). In applications beyond images, video, and language, this is often what is required. In contrast, ensemble models like random forests or gradient-boosted trees have no difficulty handling mixed data types. +* _Many problems are not about prediction._ In natural science we are often interested in learning something about the underlying distribution that generates the data. In this case, it is often difficult to cast these ideas in a supervised learning setting. While the problems are related, it is possible to make good predictions with a *wrong* model. The model might or might not be useful for understanding the underlying science. + +Some of these remarks are particular to DNNs, others are shared by all supervised learning methods. This motivates the use of unsupervised methods which in part circumvent these problems. + + + + + + !split ===== Convolutional Neural Networks (recognizing images) =====