.. _machine-learning:

Machine learning tutorial
#########################

This tutorial guides you through installing and using a Jupyter\* notebook to
set up and execute a TensorFlow\* machine learning example using the MNIST
data for handwriting recognition using the |CLOSIA|. The initial steps will
have you set up a Jupyter kernel and run a notebook on a bare-metal |CL|
system.

Install and configure a Clear Linux Host OS on bare metal
=========================================================

First, follow our instructions to install
:ref:`Clear Linux on bare metal<bare-metal-install>`.

Once the bare metal installation and initial configuration are complete, add
the following two bundles to your system:

* `machine-learning-web-ui`: This bundle contains the Jupyter application.

* `machine-learning-basic`: This bundle contains TensorFlow and other useful
  tools.

To install the bundles, run the following commands in your :file:`$HOME`
directory:

.. code-block:: console

   sudo swupd bundle-add machine-learning-web-ui

   sudo swupd bundle-add machine-learning-basic

Set up a Jupyter notebook
=========================

With all required packages and libraries installed, set up the file structure
for the Jupyter Notebook.

#. In the :file:`$HOME` directory, create a directory for the Jupyter
   Notebooks named :file:`Notebooks`.

   .. code-block:: console

      mkdir Notebooks

#. Within :file:`Notebooks`, create a directory named :file:`Handwriting`.

   .. code-block:: console

      mkdir Notebooks/Handwriting

#. Change to the new directory.

   .. code-block:: console

      cd Notebooks/Handwriting

#. Copy the :file:`MNIST_example.ipynb` file into the :file:`Handwriting`
   directory.

   .. note::
      After installing the `machine-learning basic` bundle, you can find the
      example code under
      :file:`/usr/share/doc/tensorflow/MNIST_example.ipynb`.


The example code downloads and decompresses the MNIST data directly into the
:file:`./mnist` directory. Alternatively, download the four files directly
from the Yann LeCun’s `MNIST Database website`_ and save them into a
:file:`mnist` directory within the :file:`Handwriting` directory.

The files needed are:

* `train-images-idx3-ubyte.gz`_: Training set images (9912422 bytes)

* `train-labels-idx1-ubyte.gz`_: Training set labels (28881 bytes)

* `t10k-images-idx3-ubyte.gz`_: Test set images (1648877 bytes)

* `t10k-labels-idx1-ubyte.gz`_: Test set labels (4542 bytes)

Run the Jupyter machine learning example code
=============================================

With |CL|, Jupyter, and TensorFlow installed and configured, we can
run the example code.

#. Go to the :file:`($HOME)/Notebooks` directory and start Jupyter with the
   following commands:

   .. code-block:: console

      cd ~/Notebooks

      jupyter notebook

   The Jupyter server starts and opens a web browser showing the Jupyter file
   manager with a list of files in the current directory, see figure 1.

   .. figure:: figures/machine-learning-1.png
      :alt: Jupyter file manager

      Figure 1: The Jupyter file manager shows the list of available files.

#. Click on the :file:`Handwriting` directory. The :file:`MNIST_example.ipynb`
   file created earlier should be listed there, see figure 2.

   .. figure:: figures/machine-learning-2.png
      :alt: Example file within the Jupyter file manager

      Figure 2: The example file within the Jupyter file manager.

#. To run the hand writing example, click on the :file:`MNIST_example.ipynb`
   file to load the notebook, see figure 3.

   .. figure:: figures/machine-learning-3.png
      :alt: The loaded MNIST_example notebook

      Figure 3: The loaded MNIST_example notebook within the Jupyter file
      manager.

#. Click the |run-cell| button to execute the code in the current cell and
   move to the next.

#. Select the :guilabel:`In [2]` cell and click the |run-cell| button to load
   the MNIST data. The successful output is shown on figure 4.

   .. figure:: figures/machine-learning-4.png
      :alt: Successful import of MNIST data

      Figure 4: Output after successfully importing the MNIST data.


   After the MNIST data was successfully downloaded and extracted into the
   :file:`mnist` directory within the :file:`($HOME)/Notebooks/Handwriting`
   directory, four .gz files are present and the four data sets were created:
   `trainX`, `trainY`, `testX` and `testY`.

#. To inspect the imported data, the function in :guilabel:`In [3]` first
   instructs Jupyter to reshape the data into an array of 28 x 28 images and to
   plot the area in a 28 x 28 grid. Click the |run-cell| button twice to show
   the first two digits in the `trainX` dataset, see figure 5.

   .. figure:: figures/machine-learning-5.png
      :alt: Function to reshape data.

      Figure 5: A function reshapes the data and displays the first two
      digits in the `trainX` dataset.

#. The :guilabel:`In [4]` cell defines the neural network. It provides the
   inputs, defines the hidden layers, runs the training model, and sets up
   the output layer, see figure 6. Click the |run-cell| button four times to
   perform these operations.

   .. figure:: figures/machine-learning-6.png
      :alt: Defining, building and training the neural network model

      Figure 6: Defining, building and training the neural network model.

#. To test the accuracy of the prediction the system makes, select the
   :guilabel:`In [8]` cell and click the |run-cell| button. In this example,
   the number 6 was predicted with a 99% accuracy, see figure 7.

   .. figure:: figures/machine-learning-7.png
      :alt: Prediction example

      Figure 7: The system predicts a number providing the accuracy of the
      prediction.

   .. note::

      To retest the accuracy of a random data point's prediction, run the
      cell :guilabel:`In [8]` again. It will take another random data point
      and predict its value.

#. To check the accuracy for the whole dataset, select the :guilabel:`In [10]`
   cell and click the |run-cell| button. Our example's accuracy is
   calculated as 97.17%, see figure 8.

   .. figure:: figures/machine-learning-8.png
      :alt: System's accuracy

      Figure 8: The system's accuracy for the entire data set.

For more in-depth and detailed information on the model used and the
mathematics it entails, visit the TensorFlow tutorials
`TensorFlow MNIST beginners demo`_ and `TensorFlow MNIST pros demo`_.

**Congratulations!**

You have successfully installed a Jupyter kernel on |CL|. Furthermore, you
trained a neural network to successfully predict the values contained in a
data set of hand-written number images.

Additional resources
====================

* `MNIST Database website`_
* `TensorFlow MNIST beginners demo`_
* `TensorFlow MNIST pros demo`_
* `Jupyter main website`_
* `Jupyter documentation`_
* `MNIST at Wikipedia`_

.. _MNIST Database website:
   http://yann.lecun.com/exdb/mnist/

.. _train-images-idx3-ubyte.gz:
   http://yann.lecun.com/exdb/mnist/train-images-idx3-ubyte.gz

.. _train-labels-idx1-ubyte.gz:
   http://yann.lecun.com/exdb/mnist/train-labels-idx1-ubyte.gz

.. _t10k-images-idx3-ubyte.gz:
   http://yann.lecun.com/exdb/mnist/t10k-images-idx3-ubyte.gz

.. _t10k-labels-idx1-ubyte.gz:
   http://yann.lecun.com/exdb/mnist/t10k-labels-idx1-ubyte.gz

.. _Jupyter main website: http://jupyter.org/

.. _Jupyter documentation:  https://jupyter.readthedocs.io/en/latest/index.html

.. _TensorFlow MNIST beginners demo:
   https://www.tensorflow.org/get_started/mnist/beginners

.. _TensorFlow MNIST pros demo:
   https://www.tensorflow.org/get_started/mnist/pros

.. _MNIST at Wikipedia:
   https://en.wikipedia.org/wiki/MNIST_database

.. |run-cell| image::  ./figures/run-cell-button.png
