network.py

# %load network.py

"""
network.py
~~~~~~~~~~
IT WORKS

A module to implement the stochastic gradient descent learning
algorithm for a feedforward neural network.  Gradients are calculated
using backpropagation.  Note that I have focused on making the code
simple, easily readable, and easily modifiable.  It is not optimized,
and omits many desirable features.
"""

#### Libraries
# Standard library
import random

# Third-party libraries
import numpy as np

class Network(object):

    def __init__(self, sizes):
        """The list ``sizes`` contains the number of neurons in the
        respective layers of the network.  For example, if the list
        was [2, 3, 1] then it would be a three-layer network, with the
        first layer containing 2 neurons, the second layer 3 neurons,
        and the third layer 1 neuron.  The biases and weights for the
        network are initialized randomly, using a Gaussian
        distribution with mean 0, and variance 1.  Note that the first
        layer is assumed to be an input layer, and by convention we
        won't set any biases for those neurons, since biases are only
        ever used in computing the outputs from later layers."""
        self.num_layers = len(sizes)
        self.sizes = sizes
        # mnist example biases
        # matrix size: y by 1. values: mean 0 and variance 1.
        # net.biases[0].size = 30
        # net.biases[1].size = 1
        self.biases = [np.random.randn(y, 1) for y in sizes[1:]]
        # mnist example weights
        # matrix size: y by x. values: mean 0 and variance 1.
        # net.weights[0].size = 23520 (784*30)
        # net.weights[1].size = 300 (30*10)
        self.weights = [np.random.randn(y, x)
                        for x, y in zip(sizes[:-1], sizes[1:])]


    def SGD(self, training_data, epochs, mini_batch_size, eta,
            test_data=None):
        """Train the neural network using mini-batch stochastic
        gradient descent.  The ``training_data`` is a list of tuples
        ``(x, y)`` representing the training inputs and the desired
        outputs.  The other non-optional parameters are
        self-explanatory.  If ``test_data`` is provided then the
        network will be evaluated against the test data after each
        epoch, and partial progress printed out.  This is useful for
        tracking progress, but slows things down substantially."""

        # 50k zipped list of 784*1 arrays containing the input of photos
        training_data = list(training_data)
        n = len(training_data)

        # only used for outputting progress.
        if test_data:
            test_data = list(test_data)
            n_test = len(test_data)

        # epoch is the number of mini-batches to go through (10).
        for j in range(epochs):
            random.shuffle(training_data)
            # range(0, 50k, 10), means 0, 10, 20....50k (steps of 10 to 50k)
            # training_data[k:k+10] means segment training_data in groups of 10
            mini_batches = [
                training_data[k:k+mini_batch_size]
                for k in range(0, n, mini_batch_size)]
            # each run of update_mini_batch runs stochastic gradient descent
            # on 10 training points (a mini batch).
            for mini_batch in mini_batches:
                self.update_mini_batch(mini_batch, eta)
            # for outputting progress
            if test_data:
                print("Epoch {} : {} / {}".format(j,self.evaluate(test_data),n_test));
            else:
                print("Epoch {} complete".format(j))

    def update_mini_batch(self, mini_batch, eta):
        """Update the network's weights and biases by applying
        gradient descent using backpropagation to a single mini batch.
        The ``mini_batch`` is a list of tuples ``(x, y)``, and ``eta``
        is the learning rate."""
        # essentially one run of stochastic gradient descent.
        # initialize cost gradient wrt biases.
        nabla_b = [np.zeros(b.shape) for b in self.biases]
        # initialize bias gradient wrt weights.
        nabla_w = [np.zeros(w.shape) for w in self.weights]
        # loop through each training input in batch with input x and expected output y
        # again, x is the array of shape 784*1 with values 0 to 1 for shade.
        for x, y in mini_batch:
            # warning: this backprop code actually does feedforward as well
            # so most of the SGD logic is within backprop!
            # return the delta cost gradients wrt all bias and weight for one sample.
            delta_nabla_b, delta_nabla_w = self.backprop(x, y)
            # these are used to update cost gradients after all 10 samples' are returned.
            # this is essentially the summed effect of all delta cost gradients from 10 samples.
            nabla_b = [nb+dnb for nb, dnb in zip(nabla_b, delta_nabla_b)]
            nabla_w = [nw+dnw for nw, dnw in zip(nabla_w, delta_nabla_w)]
        # update the weights and baises by multiplying by the summed effect divided by 
        # the total number of training samples in a mini batch. multiply by learning rate. 
        # then subtract this value from the current weights and biases. 
        # remember: the initial weights and baises are randomly distributed as (0,1).
        self.weights = [w-(eta/len(mini_batch))*nw
                        for w, nw in zip(self.weights, nabla_w)]
        self.biases = [b-(eta/len(mini_batch))*nb
                       for b, nb in zip(self.biases, nabla_b)]

    def backprop(self, x, y):
        """Return a tuple ``(nabla_b, nabla_w)`` representing the
        gradient for the cost function C_x.  ``nabla_b`` and
        ``nabla_w`` are layer-by-layer lists of numpy arrays, similar
        to ``self.biases`` and ``self.weights``."""

        # SETUP

        # cost gradients wrt biases and weights taking existing array shapes
        nabla_b = [np.zeros(b.shape) for b in self.biases]
        nabla_w = [np.zeros(w.shape) for w in self.weights]
        activation = x # first layer of activation are the inputs
        activations = [x] # list to store all the activations, layer by layer
        # z is wx+b, the parameter to the sigmoid activation function.
        zs = [] # list to store all the z vectors, layer by layer

        # FEEDFORWARD (aka calcualte activations layer by layer forward)

        # calculate activates for each layer, layer by layer, 
        for b, w in zip(self.biases, self.weights):
            # calculate z's elementwize for all the weights and biases
            z = np.dot(w, activation)+b
            zs.append(z)
            # sigmoid() applies elementwise
            activation = sigmoid(z)
            activations.append(activation)

        # BACKPROPAGATION

        # starting at output layer calculate errors/costs for 
        # each layer, layer by layer backwards.

        # BP1
        # multiple cost derivative (of MSE) with derivative of sigmoid.
        # it turns out these are pretty simple derivaties. for derivations,
        # see http://neuralnetworksanddeeplearning.com/chap2.html
        delta = self.cost_derivative(activations[-1], y) * \
            sigmoid_prime(zs[-1])
        nabla_b[-1] = delta
        # BP2 transpose the weight matrix
        nabla_w[-1] = np.dot(delta, activations[-2].transpose())
        # Note that the variable l in the loop below is used a little
        # differently to the notation in Chapter 2 of the book.  Here,
        # l = 1 means the last layer of neurons, l = 2 is the
        # second-last layer, and so on.  It's a renumbering of the
        # scheme in the book, used here to take advantage of the fact
        # that Python can use negative indices in lists.
        for l in range(2, self.num_layers):
            z = zs[-l]
            sp = sigmoid_prime(z)
            delta = np.dot(self.weights[-l+1].transpose(), delta) * sp
            # see derivations in http://neuralnetworksanddeeplearning.com/chap2.html
            # BP3
            nabla_b[-l] = delta
            # BP4
            nabla_w[-l] = np.dot(delta, activations[-l-1].transpose())
        return (nabla_b, nabla_w)

    # used only for printing output of progress.
    def evaluate(self, test_data):
        """Return the number of test inputs for which the neural
        network outputs the correct result. Note that the neural
        network's output is assumed to be the index of whichever
        neuron in the final layer has the highest activation."""
        test_results = [(np.argmax(self.feedforward(x)), y)
                        for (x, y) in test_data]
        return sum(int(x == y) for (x, y) in test_results)

    # derivative of MSE function.
    def cost_derivative(self, output_activations, y):
        """Return the vector of partial derivatives \partial C_x /
        \partial a for the output activations."""
        return (output_activations-y)

    # used for printing output of progress only.
    def feedforward(self, a):
        """Return the output of the network if ``a`` is input."""
        for b, w in zip(self.biases, self.weights):
            a = sigmoid(np.dot(w, a)+b)
        return a

#### Miscellaneous functions
def sigmoid(z):
    """The sigmoid function."""
    return 1.0/(1.0+np.exp(-z))

def sigmoid_prime(z):
    """Derivative of the sigmoid function."""
    return sigmoid(z)*(1-sigmoid(z))