From 44eee83482f413ecbb3f4afb9f1025ecd3cbf65a Mon Sep 17 00:00:00 2001 From: mhjensen Date: Sun, 22 Dec 2019 20:00:39 +0100 Subject: [PATCH] cleaning uo --- doc/LectureNotes/.book.copyright | 1 - doc/LectureNotes/book.dlog | 3015 ----------- doc/LectureNotes/book.do.txt | 1864 +++++++ doc/LectureNotes/book.do.txt~ | 6786 ------------------------ doc/LectureNotes/book.ipynb | 2401 --------- doc/LectureNotes/gaussian.pdf | Bin 229831 -> 0 bytes doc/LectureNotes/ipynb-book-src.tar.gz | Bin 103631 -> 0 bytes 7 files changed, 1864 insertions(+), 12203 deletions(-) delete mode 100644 doc/LectureNotes/.book.copyright delete mode 100644 doc/LectureNotes/book.dlog delete mode 100644 doc/LectureNotes/book.do.txt~ delete mode 100644 doc/LectureNotes/book.ipynb delete mode 100644 doc/LectureNotes/gaussian.pdf delete mode 100644 doc/LectureNotes/ipynb-book-src.tar.gz diff --git a/doc/LectureNotes/.book.copyright b/doc/LectureNotes/.book.copyright deleted file mode 100644 index 0507b6521..000000000 --- a/doc/LectureNotes/.book.copyright +++ /dev/null @@ -1 +0,0 @@ -{'holder': ['Morten Hjorth-Jensen'], 'year': '1999-2019', 'license': 'Released under CC Attribution-NonCommercial 4.0 license', 'cite doconce': False} \ No newline at end of file diff --git a/doc/LectureNotes/book.dlog b/doc/LectureNotes/book.dlog deleted file mode 100644 index 8409772b7..000000000 --- a/doc/LectureNotes/book.dlog +++ /dev/null @@ -1,3015 +0,0 @@ -translating doconce text in book.do.txt to ipynb -*** error: could not open the file src/plot_Hudson.py used in -@@@CODE src/plot_Hudson.py -translating doconce text in book.do.txt to ipynb -copy complete file src/plot_Hudson.py (format: pypro) -copy complete file src/Hudson_Bay.py (format: pypro) -*** error: figure file "fig/Hudson_Bay_sim" does not exist! -translating doconce text in book.do.txt to ipynb -copy complete file src/plot_Hudson.py (format: pypro) -copy complete file src/Hudson_Bay.py (format: pypro) -figure file fig/Hudson_Bay_data: - can use fig/Hudson_Bay_data.png for format ipynb -figure file fig/Hudson_Bay_sim: - can use fig/Hudson_Bay_sim.png for format ipynb -collected all required additional files in ipynb-book-src.tar.gz which must be distributed with the notebook -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -output in book.ipynb -*** error: file has a mako construction ${\bf \hat{J}' - but seemingly no definition in <%...%>' - (it is not a command-line given mako variable either). - However, if this is a variable in a Makefile or Bash script - run with --no_mako - and you cannot use mako and Makefile or Bash variables - in the same document! - -*** error: file has a mako construction ${\bf \hat{J}' - but seemingly no definition in <%...%>' - (it is not a command-line given mako variable either). - However, if this is a variable in a Makefile or Bash script - run with --no_mako - and you cannot use mako and Makefile or Bash variables - in the same document! - -translating doconce text in book.do.txt to ipynb -*** error: found multiple labels: - eq:def_covariance eq:autocorrelation_time eq:error_estimate_corr_time -translating doconce text in book.do.txt to ipynb -copy complete file src/plot_Hudson.py (format: pypro) -copy complete file src/Hudson_Bay.py (format: pypro) -figure file fig/Hudson_Bay_data: - can use fig/Hudson_Bay_data.png for format ipynb -figure file fig/Hudson_Bay_sim: - can use fig/Hudson_Bay_sim.png for format ipynb -collected all required additional files in ipynb-book-src.tar.gz which must be distributed with the notebook -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -output in book.ipynb -translating doconce text in book.do.txt to ipynb -copy complete file src/plot_Hudson.py (format: pypro) -copy complete file src/Hudson_Bay.py (format: pypro) -figure file fig/Hudson_Bay_data: - can use fig/Hudson_Bay_data.png for format ipynb -figure file fig/Hudson_Bay_sim: - can use fig/Hudson_Bay_sim.png for format ipynb -collected all required additional files in ipynb-book-src.tar.gz which must be distributed with the notebook -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -output in book.ipynb -translating doconce text in book.do.txt to ipynb -ERROR: 2 !bblock do not match 4 !eblock directives - - -Two !eblock after each other! - -!eblock - - -===== Numpy and arrays ===== -"Numpy":"http://www.numpy.org/" provides an easy way to handle arrays in Python. The standard way to import this library is as - -!bc pycod -import numpy as np -!ec -Here follows a simple example where we set up an array of ten elements, all determined by random numbers drawn according to the normal distribution, -!bc pycod -n = 10 -x = np.random.normal(size=n) -print(x) -!ec -We defined a vector $x$ with $n=10$ elements with its values given by the Normal distribution $N(0,1)$. -Another alternative is to declare a vector as follows -!bc pycod -import numpy as np -x = np.array([1, 2, 3]) -print(x) -!ec -Here we have defined a vector with three elements, with $x_0=1$, $x_1=2$ and $x_2=3$. Note that both Python and C++ -start numbering array elements from $0$ and on. This means that a vector with $n$ elements has a sequence of entities $x_0, x_1, x_2, \dots, x_{n-1}$. We could also let (recommended) Numpy to compute the logarithms of a specific array as -!bc pycod -import numpy as np -x = np.log(np.array([4, 7, 8])) -print(x) -!ec - -In the last example we used Numpy's unary function $np.log$. This function is -highly tuned to compute array elements since the code is vectorized -and does not require looping. We normaly recommend that you use the -Numpy intrinsic functions instead of the corresponding _log_ function -from Python's _math_ module. The looping is done explicitely by the -_np.log_ function. The alternative, and slower way to compute the -logarithms of a vector would be to write - -!bc pycod -import numpy as np -from math import log -x = np.array([4, 7, 8]) -for i in range(0, len(x)): - x[i] = log(x[i]) -print(x) -!ec -We note that our code is much longer already and we need to import the _log_ function from the _math_ module. -The attentive reader will also notice that the output is $[1, 1, 2]$. Python interprets automagically our numbers as integers (like the _automatic_ keyword in C++). To change this we could define our array elements to be double precision numbers as -!bc pycod -import numpy as np -x = np.log(np.array([4, 7, 8], dtype = np.float64)) -print(x) -!ec -or simply write them as double precision numbers (Python uses 64 bits as default for floating point type variables), that is -!bc pycod -import numpy as np -x = np.log(np.array([4.0, 7.0, 8.0]) -print(x) -!ec -To check the number of bytes (remember that one byte contains eight bits for double precision variables), you can use simple use the _itemsize_ functionality (the array $x$ is actually an object which inherits the functionalities defined in Numpy) as -!bc pycod -import numpy as np -x = np.log(np.array([4.0, 7.0, 8.0]) -print(x.itemsize) -!ec - - -===== Matrices in Python ===== - -Having defined vectors, we are now ready to try out matrices. We can -define a $3 \times 3 $ real matrix $\hat{A}$ as (recall that we user -lowercase letters for vectors and uppercase letters for matrices) - -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -print(A) -!ec -If we use the _shape_ function we would get $(3, 3)$ as output, that is verifying that our matrix is a $3\times 3$ matrix. We can slice the matrix and print for example the first column (Python organized matrix elements in a row-major order, see below) as -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -# print the first column, row-major order and elements start with 0 -print(A[:,0]) -!ec -We can continue this was by printing out other columns or rows. The example here prints out the second column -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -# print the first column, row-major order and elements start with 0 -print(A[1,:]) -!ec -Numpy contains many other functionalities that allow us to slice, subdivide etc etc arrays. We strongly recommend that you look up the "Numpy website for more details":"http://www.numpy.org/". Useful functions when defining a matrix are the _np.zeros_ function which declares a matrix of a given dimension and sets all elements to zero -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to zero -A = np.zeros( (n, n) ) -print(A) -!ec -or initializing all elements to -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to one -A = np.ones( (n, n) ) -print(A) -!ec -or as unitarily distributed random numbers (see the material on random number generators in the statistics part) -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to random numbers with x \in [0, 1] -A = np.random.rand(n, n) -print(A) -!ec - -As we will see throughout these lectures, there are several extremely useful functionalities in Numpy. -As an example, consider the discussion of the covariance matrix. Suppose we have defined three vectors -$\hat{x}, \hat{y}, \hat{z}$ with $n$ elements each. The covariance matrix is defined as -!bt -\[ -\hat{\Sigma} = \begin{bmatrix} \sigma_{xx} & \sigma_{xy} & \sigma_{xz} \\ - \sigma_{yx} & \sigma_{yy} & \sigma_{yz} \\ - \sigma_{zx} & \sigma_{zy} & \sigma_{zz} - \end{bmatrix}, -\] -!et -where for example -!bt -\[ -\sigma_{xy} =\frac{1}{n} \sum_{i=0}^{n-1}(x_i- \overline{x})(y_i- \overline{y}). -\] -!et -The Numpy function _np.cov_ calculates the covariance elements using the factor $1/(n-1)$ instead of $1/n$ since it assumes we do not have the exact mean values. -The following simple function uses the _np.vstack_ function which takes each vector of dimension $1\times n$ and produces a $3\times n$ matrix $\hat{W}$ -!bt -\[ -\hat{W} = \begin{bmatrix} x_0 & y_0 & z_0 \\ - x_1 & y_1 & z_1 \\ - x_2 & y_2 & z_2 \\ - \dots & \dots & \dots \\ - x_{n-2} & y_{n-2} & z_{n-2} \\ - x_{n-1} & y_{n-1} & z_{n-1} - \end{bmatrix}, -\] -!et - -which in turn is converted into into the $3\times 3$ covariance matrix -$\hat{\Sigma}$ via the Numpy function _np.cov()_. We note that we can also calculate -the mean value of each set of samples $\hat{x}$ etc using the Numpy -function _np.mean(x)_. We can also extract the eigenvalues of the -covariance matrix through the _np.linalg.eig()_ function. - -!bc pycod -# Importing various packages -import numpy as np - -n = 100 -x = np.random.normal(size=n) -print(np.mean(x)) -y = 4+3*x+np.random.normal(size=n) -print(np.mean(y)) -z = x**3+np.random.normal(size=n) -print(np.mean(z)) -W = np.vstack((x, y, z)) -Sigma = np.cov(W) -print(Sigma) -Eigvals, Eigvecs = np.linalg.eig(Sigma) -print(Eigvals) -!ec - - -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from scipy import sparse -eye = np.eye(4) -print(eye) -sparse_mtx = sparse.csr_matrix(eye) -print(sparse_mtx) -x = np.linspace(-10,10,100) -y = np.sin(x) -plt.plot(x,y,marker='x') -plt.show() -!ec - - -===== Meet the Pandas ===== - - -FIGURE: [fig/pandas.jpg, width=600 frac=0.8] - -Another useful Python package is -"pandas":"https://pandas.pydata.org/", which is an open source library -providing high-performance, easy-to-use data structures and data -analysis tools for Python. _pandas_ stands for panel data, a term borrowed from econometrics and is an efficient library for data analysis with an emphasis on tabular data. -_pandas_ has two major classes, the _DataFrame_ class with two-dimensional data objects and tabular data organized in columns and the class _Series_ with a focus on one-dimensional data objects. Both classes allow you to index data easily as we will see in the examples below. -_pandas_ allows you also to perform mathematical operations on the data, spanning from simple reshapings of vectors and matrices to statistical operations. - -The following simple example shows how we can, in an easy way make tables of our data. Here we define a data set which includes names, place of birth and date of birth, and displays the data in an easy to read way. We will see repeated use of _pandas_, in particular in connection with classification of data. - -!bc pycod -import pandas as pd -from IPython.display import display -data = {'First Name': ["Frodo", "Bilbo", "Aragorn II", "Samwise"], - 'Last Name': ["Baggins", "Baggins","Elessar","Gamgee"], - 'Place of birth': ["Shire", "Shire", "Eriador", "Shire"], - 'Date of Birth T.A.': [2968, 2890, 2931, 2980] - } -data_pandas = pd.DataFrame(data) -display(data_pandas) -!ec - -In the above we have imported _pandas_ with the shorthand _pd_, the latter has become the standard way we import _pandas_. We make then a list of various variables -and reorganize the aboves lists into a _DataFrame_ and then print out a neat table with specific column labels as *Name*, *place of birth* and *date of birth*. -Displaying these results, we see that the indices are given by the default numbers from zero to three. -_pandas_ is extremely flexible and we can easily change the above indices by defining a new type of indexing as -!bc pycod -data_pandas = pd.DataFrame(data,index=['Frodo','Bilbo','Aragorn','Sam']) -display(data_pandas) -!ec -Thereafter we display the content of the row which begins with the index _Aragorn_ -!bc pycod -display(data_pandas.loc['Aragorn']) -!ec - -We can easily append data to this, for example -!bc pycod -new_hobbit = {'First Name': ["Peregrin"], - 'Last Name': ["Took"], - 'Place of birth': ["Shire"], - 'Date of Birth T.A.': [2990] - } -data_pandas=data_pandas.append(pd.DataFrame(new_hobbit, index=['Pippin'])) -display(data_pandas) -!ec - - -Here are other examples where we use the _DataFrame_ functionality to handle arrays, now with more interesting features for us, namely numbers. We set up a matrix -of dimensionality $10\times 5$ and compute the mean value and standard deviation of each column. Similarly, we can perform mathematial operations like squaring the matrix elements and many other operations. -!bc pycod -import numpy as np -import pandas as pd -from IPython.display import display -np.random.seed(100) -# setting up a 10 x 5 matrix -rows = 10 -cols = 5 -a = np.random.randn(rows,cols) -df = pd.DataFrame(a) -display(df) -print(df.mean()) -print(df.std()) -display(df**2) -!ec - -Thereafter we can select specific columns only and plot final results -!bc pycod -df.columns = ['First', 'Second', 'Third', 'Fourth', 'Fifth'] -df.index = np.arange(10) - -display(df) -print(df['Second'].mean() ) -print(df.info()) -print(df.describe()) - -from pylab import plt, mpl -plt.style.use('seaborn') -mpl.rcParams['font.family'] = 'serif' - -df.cumsum().plot(lw=2.0, figsize=(10,6)) -plt.show() - - -df.plot.bar(figsize=(10,6), rot=15) -plt.show() -!ec -We can produce a $4\times 4$ matrix -!bc pycod -b = np.arange(16).reshape((4,4)) -print(b) -df1 = pd.DataFrame(b) -print(df1) -!ec -and many other operations. - -The _Series_ class is another important class included in -_pandas_. You can view it as a specialization of _DataFrame_ but where -we have just a single column of data. It shares many of the same features as _DataFrame. As with _DataFrame_, -most operations are vectorized, achieving thereby a high performance when dealing with computations of arrays, in particular labeled arrays. -As we will see below it leads also to a very concice code close to the mathematical operations we may be interested in. -For multidimensional arrays, we recommend strongly "xarray":"http://xarray.pydata.org/en/stable/". _xarray_ has much of the same flexibility as _pandas_, but allows for the extension to higher dimensions than two. We will see examples later of the usage of both _pandas_ and _xarray_. - - - -===== Reading Data and fitting ===== - -In order to study various Machine Learning algorithms, we need to -access data. Acccessing data is an essential step in all machine -learning algorithms. In particular, setting up the so-called _design -matrix_ (to be defined below) is often the first element we need in -order to perform our calculations. To set up the design matrix means -reading (and later, when the calculations are done, writing) data -in various formats, The formats span from reading files from disk, -loading data from databases and interacting with online sources -like web application programming interfaces (APIs). - -In handling various input formats, as discussed above, we will mainly stay with _pandas_, -a Python package which allows us, in a seamless and painless way, to -deal with a multitude of formats, from standard _csv_ (comma separated -values) files, via _excel_, _html_ to _hdf5_ formats. With _pandas_ -and the _DataFrame_ and _Series_ functionalities we are able to convert text data -into the calculational formats we need for a specific algorithm. And our code is going to be -pretty close the basic mathematical expressions. - -Our first data set is going to be a classic from nuclear physics, namely all -available data on binding energies. Don't be intimidated if you are not familiar with nuclear physics. It serves simply as an example here of a data set. - -We will show some of the -strengths of packages like _Scikit-Learn_ in fitting nuclear binding energies to -specific functions using linear regression first. Then, as a teaser, we will show you how -you can easily implement other algorithms like decision trees and random forests and neural networks. - -But before we really start with nuclear physics data, let's just look at some simpler polynomial fitting cases, such as, -(don't be offended) fitting straight lines! - - -=== Simple linear regression model using _scikit-learn_ === - -We start with perhaps our simplest possible example, using _Scikit-Learn_ to perform linear regression analysis on a data set produced by us. - -What follows is a simple Python code where we have defined a function -$y$ in terms of the variable $x$. Both are defined as vectors with $100$ entries. -The numbers in the vector $\hat{x}$ are given -by random numbers generated with a uniform distribution with entries -$x_i \in [0,1]$ (more about probability distribution functions -later). These values are then used to define a function $y(x)$ -(tabulated again as a vector) with a linear dependence on $x$ plus a -random noise added via the normal distribution. - - -The Numpy functions are imported used the _import numpy as np_ -statement and the random number generator for the uniform distribution -is called using the function _np.random.rand()_, where we specificy -that we want $100$ random variables. Using Numpy we define -automatically an array with the specified number of elements, $100$ in -our case. With the Numpy function _randn()_ we can compute random -numbers with the normal distribution (mean value $\mu$ equal to zero and -variance $\sigma^2$ set to one) and produce the values of $y$ assuming a linear -dependence as function of $x$ - -!bt -\[ -y = 2x+N(0,1), -\] -!et - -where $N(0,1)$ represents random numbers generated by the normal -distribution. From _Scikit-Learn_ we import then the -_LinearRegression_ functionality and make a prediction $\tilde{y} = -\alpha + \beta x$ using the function _fit(x,y)_. We call the set of -data $(\hat{x},\hat{y})$ for our training data. The Python package -_scikit-learn_ has also a functionality which extracts the above -fitting parameters $\alpha$ and $\beta$ (see below). Later we will -distinguish between training data and test data. - -For plotting we use the Python package -"matplotlib":"https://matplotlib.org/" which produces publication -quality figures. Feel free to explore the extensive -"gallery":"https://matplotlib.org/gallery/index.html" of examples. In -this example we plot our original values of $x$ and $y$ as well as the -prediction _ypredict_ ($\tilde{y}$), which attempts at fitting our -data with a straight line. - -The Python code follows here. -!bc pycod -# Importing various packages -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression - -x = np.random.rand(100,1) -y = 2*x+np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -xnew = np.array([[0],[1]]) -ypredict = linreg.predict(xnew) - -plt.plot(xnew, ypredict, "r-") -plt.plot(x, y ,'ro') -plt.axis([0,1.0,0, 5.0]) -plt.xlabel(r'$x$') -plt.ylabel(r'$y$') -plt.title(r'Simple Linear Regression') -plt.show() -!ec - -This example serves several aims. It allows us to demonstrate several -aspects of data analysis and later machine learning algorithms. The -immediate visualization shows that our linear fit is not -impressive. It goes through the data points, but there are many -outliers which are not reproduced by our linear regression. We could -now play around with this small program and change for example the -factor in front of $x$ and the normal distribution. Try to change the -function $y$ to - -!bt -\[ -y = 10x+0.01 \times N(0,1), -\] -!et - -where $x$ is defined as before. Does the fit look better? Indeed, by -reducing the role of the noise given by the normal distribution we see immediately that -our linear prediction seemingly reproduces better the training -set. However, this testing 'by the eye' is obviouly not satisfactory in the -long run. Here we have only defined the training data and our model, and -have not discussed a more rigorous approach to the _cost_ function. - -We need more rigorous criteria in defining whether we have succeeded or -not in modeling our training data. You will be surprised to see that -many scientists seldomly venture beyond this 'by the eye' approach. A -standard approach for the *cost* function is the so-called $\chi^2$ -function (a variant of the mean-squared error (MSE)) - -!bt -\[ \chi^2 = \frac{1}{n} -\sum_{i=0}^{n-1}\frac{(y_i-\tilde{y}_i)^2}{\sigma_i^2}, -\] -!et - -where $\sigma_i^2$ is the variance (to be defined later) of the entry -$y_i$. We may not know the explicit value of $\sigma_i^2$, it serves -however the aim of scaling the equations and make the cost function -dimensionless. - -Minimizing the cost function is a central aspect of -our discussions to come. Finding its minima as function of the model -parameters ($\alpha$ and $\beta$ in our case) will be a recurring -theme in these series of lectures. Essentially all machine learning -algorithms we will discuss center around the minimization of the -chosen cost function. This depends in turn on our specific -model for describing the data, a typical situation in supervised -learning. Automatizing the search for the minima of the cost function is a -central ingredient in all algorithms. Typical methods which are -employed are various variants of _gradient_ methods. These will be -discussed in more detail later. Again, you'll be surprised to hear that -many practitioners minimize the above function ''by the eye', popularly dubbed as -'chi by the eye'. That is, change a parameter and see (visually and numerically) that -the $\chi^2$ function becomes smaller. - -There are many ways to define the cost function. A simpler approach is to look at the relative difference between the training data and the predicted data, that is we define -the relative error (why would we prefer the MSE instead of the relative error?) as - -!bt -\[ -\epsilon_{\mathrm{relative}}= \frac{\vert \hat{y} -\hat{\tilde{y}}\vert}{\vert \hat{y}\vert}. -\] -!et -We can modify easily the above Python code and plot the relative error instead -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression - -x = np.random.rand(100,1) -y = 5*x+0.01*np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -ypredict = linreg.predict(x) - -plt.plot(x, np.abs(ypredict-y)/abs(y), "ro") -plt.axis([0,1.0,0.0, 0.5]) -plt.xlabel(r'$x$') -plt.ylabel(r'$\epsilon_{\mathrm{relative}}$') -plt.title(r'Relative error') -plt.show() -!ec - -Depending on the parameter in front of the normal distribution, we may -have a small or larger relative error. Try to play around with -different training data sets and study (graphically) the value of the -relative error. - -As mentioned above, _Scikit-Learn_ has an impressive functionality. -We can for example extract the values of $\alpha$ and $\beta$ and -their error estimates, or the variance and standard deviation and many -other properties from the statistical data analysis. - -Here we show an -example of the functionality of _Scikit-Learn_. -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression -from sklearn.metrics import mean_squared_error, r2_score, mean_squared_log_error, mean_absolute_error - -x = np.random.rand(100,1) -y = 2.0+ 5*x+0.5*np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -ypredict = linreg.predict(x) -print('The intercept alpha: \n', linreg.intercept_) -print('Coefficient beta : \n', linreg.coef_) -# The mean squared error -print("Mean squared error: %.2f" % mean_squared_error(y, ypredict)) -# Explained variance score: 1 is perfect prediction -print('Variance score: %.2f' % r2_score(y, ypredict)) -# Mean squared log error -print('Mean squared log error: %.2f' % mean_squared_log_error(y, ypredict) ) -# Mean absolute error -print('Mean absolute error: %.2f' % mean_absolute_error(y, ypredict)) -plt.plot(x, ypredict, "r-") -plt.plot(x, y ,'ro') -plt.axis([0.0,1.0,1.5, 7.0]) -plt.xlabel(r'$x$') -plt.ylabel(r'$y$') -plt.title(r'Linear Regression fit ') -plt.show() - -!ec -The function _coef_ gives us the parameter $\beta$ of our fit while _intercept_ yields -$\alpha$. Depending on the constant in front of the normal distribution, we get values near or far from $alpha =2$ and $\beta =5$. Try to play around with different parameters in front of the normal distribution. The function _meansquarederror_ gives us the mean square error, a risk metric corresponding to the expected value of the squared (quadratic) error or loss defined as -!bt -\[ MSE(\hat{y},\hat{\tilde{y}}) = \frac{1}{n} -\sum_{i=0}^{n-1}(y_i-\tilde{y}_i)^2, -\] -!et - -The smaller the value, the better the fit. Ideally we would like to -have an MSE equal zero. The attentive reader has probably recognized -this function as being similar to the $\chi^2$ function defined above. - -The _r2score_ function computes $R^2$, the coefficient of -determination. It provides a measure of how well future samples are -likely to be predicted by the model. Best possible score is 1.0 and it -can be negative (because the model can be arbitrarily worse). A -constant model that always predicts the expected value of $\hat{y}$, -disregarding the input features, would get a $R^2$ score of $0.0$. - -If $\tilde{\hat{y}}_i$ is the predicted value of the $i-th$ sample and $y_i$ is the corresponding true value, then the score $R^2$ is defined as -!bt -\[ -R^2(\hat{y}, \tilde{\hat{y}}) = 1 - \frac{\sum_{i=0}^{n - 1} (y_i - \tilde{y}_i)^2}{\sum_{i=0}^{n - 1} (y_i - \bar{y})^2}, -\] -!et -where we have defined the mean value of $\hat{y}$ as -!bt -\[ -\bar{y} = \frac{1}{n} \sum_{i=0}^{n - 1} y_i. -\] -!et -Another quantity taht we will meet again in our discussions of regression analysis is - the mean absolute error (MAE), a risk metric corresponding to the expected value of the absolute error loss or what we call the $l1$-norm loss. In our discussion above we presented the relative error. -The MAE is defined as follows -!bt -\[ -\text{MAE}(\hat{y}, \hat{\tilde{y}}) = \frac{1}{n} \sum_{i=0}^{n-1} \left| y_i - \tilde{y}_i \right|. -\] -!et -Finally we present the -squared logarithmic (quadratic) error -!bt -\[ -\text{MSLE}(\hat{y}, \hat{\tilde{y}}) = \frac{1}{n} \sum_{i=0}^{n - 1} (\log_e (1 + y_i) - \log_e (1 + \tilde{y}_i) )^2, -\] -!et - -where $\log_e (x)$ stands for the natural logarithm of $x$. This error -estimate is best to use when targets having exponential growth, such -as population counts, average sales of a commodity over a span of -years etc. - -We will discuss in more -detail these and other functions in the various lectures. We conclude this part with another example. Instead of -a linear $x$-dependence we study now a cubic polynomial and use the polynomial regression analysis tools of scikit-learn. - -!bc pycod -import matplotlib.pyplot as plt -import numpy as np -import random -from sklearn.linear_model import Ridge -from sklearn.preprocessing import PolynomialFeatures -from sklearn.pipeline import make_pipeline -from sklearn.linear_model import LinearRegression - -x=np.linspace(0.02,0.98,200) -noise = np.asarray(random.sample((range(200)),200)) -y=x**3*noise -yn=x**3*100 -poly3 = PolynomialFeatures(degree=3) -X = poly3.fit_transform(x[:,np.newaxis]) -clf3 = LinearRegression() -clf3.fit(X,y) - -Xplot=poly3.fit_transform(x[:,np.newaxis]) -poly3_plot=plt.plot(x, clf3.predict(Xplot), label='Cubic Fit') -plt.plot(x,yn, color='red', label="True Cubic") -plt.scatter(x, y, label='Data', color='orange', s=15) -plt.legend() -plt.show() - -def error(a): - for i in y: - err=(y-yn)/yn - return abs(np.sum(err))/len(err) - -print (error(y)) -!ec - - - - -=== To our real data: nuclear binding energies. Brief reminder on masses and binding energies === - -Let us now dive into nuclear physics and remind ourselves briefly about some basic features about binding -energies. A basic quantity which can be measured for the ground -states of nuclei is the atomic mass $M(N, Z)$ of the neutral atom with -atomic mass number $A$ and charge $Z$. The number of neutrons is $N$. There are indeed several sophisticated experiments worldwide which allow us to measure this quantity to high precision (parts per million even). - -Atomic masses are usually tabulated in terms of the mass excess defined by -!bt -\[ -\Delta M(N, Z) = M(N, Z) - uA, -\] -!et -where $u$ is the Atomic Mass Unit -!bt -\[ -u = M(^{12}\mathrm{C})/12 = 931.4940954(57) \hspace{0.1cm} \mathrm{MeV}/c^2. -\] -!et -The nucleon masses are -!bt -\[ -m_p = 1.00727646693(9)u, -\] -!et -and -!bt -\[ -m_n = 939.56536(8)\hspace{0.1cm} \mathrm{MeV}/c^2 = 1.0086649156(6)u. -\] -!et - -In the "2016 mass evaluation of by W.J.Huang, G.Audi, M.Wang, F.G.Kondev, S.Naimi and X.Xu":"http://nuclearmasses.org/resources_folder/Wang_2017_Chinese_Phys_C_41_030003.pdf" -there are data on masses and decays of 3437 nuclei. - -The nuclear binding energy is defined as the energy required to break -up a given nucleus into its constituent parts of $N$ neutrons and $Z$ -protons. In terms of the atomic masses $M(N, Z)$ the binding energy is -defined by - - -!bt -\[ -BE(N, Z) = ZM_H c^2 + Nm_n c^2 - M(N, Z)c^2 , -\] -!et -where $M_H$ is the mass of the hydrogen atom and $m_n$ is the mass of the neutron. -In terms of the mass excess the binding energy is given by -!bt -\[ -BE(N, Z) = Z\Delta_H c^2 + N\Delta_n c^2 -\Delta(N, Z)c^2 , -\] -!et -where $\Delta_H c^2 = 7.2890$ MeV and $\Delta_n c^2 = 8.0713$ MeV. - - -A popular and physically intuitive model which can be used to parametrize -the experimental binding energies as function of $A$, is the so-called -_liquid drop model_. The ansatz is based on the following expression - -!bt -\[ -BE(N,Z) = a_1A-a_2A^{2/3}-a_3\frac{Z^2}{A^{1/3}}-a_4\frac{(N-Z)^2}{A}, -\] -!et - -where $A$ stands for the number of nucleons and the $a_i$s are parameters which are determined by a fit -to the experimental data. - - - - -To arrive at the above expression we have assumed that we can make the following assumptions: - - * There is a volume term $a_1A$ proportional with the number of nucleons (the energy is also an extensive quantity). When an assembly of nucleons of the same size is packed together into the smallest volume, each interior nucleon has a certain number of other nucleons in contact with it. This contribution is proportional to the volume. - - * There is a surface energy term $a_2A^{2/3}$. The assumption here is that a nucleon at the surface of a nucleus interacts with fewer other nucleons than one in the interior of the nucleus and hence its binding energy is less. This surface energy term takes that into account and is therefore negative and is proportional to the surface area. - - - * There is a Coulomb energy term $a_3\frac{Z^2}{A^{1/3}}$. The electric repulsion between each pair of protons in a nucleus yields less binding. - - * There is an asymmetry term $a_4\frac{(N-Z)^2}{A}$. This term is associated with the Pauli exclusion principle and reflects the fact that the proton-neutron interaction is more attractive on the average than the neutron-neutron and proton-proton interactions. - -We could also add a so-called pairing term, which is a correction term that -arises from the tendency of proton pairs and neutron pairs to -occur. An even number of particles is more stable than an odd number. - - -=== Organizing our data === - -Let us start with reading and organizing our data. -We start with the compilation of masses and binding energies from 2016. -After having downloaded this file to our own computer, we are now ready to read the file and start structuring our data. - - -We start with preparing folders for storing our calculations and the data file over masses and binding energies. We import also various modules that we will find useful in order to present various Machine Learning methods. Here we focus mainly on the functionality of _scikit-learn_. -!bc pycod -# Common imports -import numpy as np -import pandas as pd -import matplotlib.pyplot as plt -import sklearn.linear_model as skl -from sklearn.model_selection import train_test_split -from sklearn.metrics import mean_squared_error, r2_score, mean_absolute_error -import os - -# Where to save the figures and data files -PROJECT_ROOT_DIR = "Results" -FIGURE_ID = "Results/FigureFiles" -DATA_ID = "DataFiles/" - -if not os.path.exists(PROJECT_ROOT_DIR): - os.mkdir(PROJECT_ROOT_DIR) - -if not os.path.exists(FIGURE_ID): - os.makedirs(FIGURE_ID) - -if not os.path.exists(DATA_ID): - os.makedirs(DATA_ID) - -def image_path(fig_id): - return os.path.join(FIGURE_ID, fig_id) - -def data_path(dat_id): - return os.path.join(DATA_ID, dat_id) - -def save_fig(fig_id): - plt.savefig(image_path(fig_id) + ".png", format='png') - -infile = open(data_path("MassEval2016.dat"),'r') -!ec - - -Before we proceed, we define also a function for making our plots. You can obviously avoid this and simply set up various _matplotlib_ commands every time you need them. You may however find it convenient to collect all such commands in one function and simply call this function. -!bc pycod -from pylab import plt, mpl -plt.style.use('seaborn') -mpl.rcParams['font.family'] = 'serif' - -def MakePlot(x,y, styles, labels, axlabels): - plt.figure(figsize=(10,6)) - for i in range(len(x)): - plt.plot(x[i], y[i], styles[i], label = labels[i]) - plt.xlabel(axlabels[0]) - plt.ylabel(axlabels[1]) - plt.legend(loc=0) -!ec - -Our next step is to read the data on experimental binding energies and -reorganize them as functions of the mass number $A$, the number of -protons $Z$ and neutrons $N$ using _pandas_. Before we do this it is -always useful (unless you have a binary file or other types of compressed -data) to actually open the file and simply take a look at it! - - -In particular, the program that outputs the final nuclear masses is written in Fortran with a specific format. It means that we need to figure out the format and which columns contain the data we are interested in. Pandas comes with a function that reads formatted output. After having admired the file, we are now ready to start massaging it with _pandas_. The file begins with some basic format information. -!bc pycod -""" -This is taken from the data file of the mass 2016 evaluation. -All files are 3436 lines long with 124 character per line. - Headers are 39 lines long. - col 1 : Fortran character control: 1 = page feed 0 = line feed - format : a1,i3,i5,i5,i5,1x,a3,a4,1x,f13.5,f11.5,f11.3,f9.3,1x,a2,f11.3,f9.3,1x,i3,1x,f12.5,f11.5 - These formats are reflected in the pandas widths variable below, see the statement - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - Pandas has also a variable header, with length 39 in this case. -""" -!ec - -The data we are interested in are in columns 2, 3, 4 and 11, giving us -the number of neutrons, protons, mass numbers and binding energies, -respectively. We add also for the sake of completeness the element name. The data are in fixed-width formatted lines and we will -covert them into the _pandas_ DataFrame structure. - -!bc pycod -# Read the experimental data with Pandas -Masses = pd.read_fwf(infile, usecols=(2,3,4,6,11), - names=('N', 'Z', 'A', 'Element', 'Ebinding'), - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - header=39, - index_col=False) - -# Extrapolated values are indicated by '#' in place of the decimal place, so -# the Ebinding column won't be numeric. Coerce to float and drop these entries. -Masses['Ebinding'] = pd.to_numeric(Masses['Ebinding'], errors='coerce') -Masses = Masses.dropna() -# Convert from keV to MeV. -Masses['Ebinding'] /= 1000 - -# Group the DataFrame by nucleon number, A. -Masses = Masses.groupby('A') -# Find the rows of the grouped DataFrame with the maximum binding energy. -Masses = Masses.apply(lambda t: t[t.Ebinding==t.Ebinding.max()]) -!ec - -We have now read in the data, grouped them according to the variables we are interested in. -We see how easy it is to reorganize the data using _pandas_. If we -were to do these operations in C/C++ or Fortran, we would have had to -write various functions/subroutines which perform the above -reorganizations for us. Having reorganized the data, we can now start -to make some simple fits using both the functionalities in _numpy_ and -_Scikit-Learn_ afterwards. - -Now we define five variables which contain -the number of nucleons $A$, the number of protons $Z$ and the number of neutrons $N$, the element name and finally the energies themselves. -!bc pycod -A = Masses['A'] -Z = Masses['Z'] -N = Masses['N'] -Element = Masses['Element'] -Energies = Masses['Ebinding'] -print(Masses) -!ec -The next step, and we will define this mathematically later, is to set up the so-called _design matrix_. We will throughout call this matrix $\bm{X}$. -It has dimensionality $p\times n$, where $n$ is the number of data points and $p$ are the so-called predictors. In our case here they are given by the number of polynomials in $A$ we wish to include in the fit. -!bc pycod -# Now we set up the design matrix X -X = np.zeros((len(A),5)) -X[:,0] = 1 -X[:,1] = A -X[:,2] = A**(2.0/3.0) -X[:,3] = A**(-1.0/3.0) -X[:,4] = A**(-1.0) -!ec -With _scikitlearn_ we are now ready to use linear regression and fit our data. -!bc pycod -clf = skl.LinearRegression().fit(X, Energies) -fity = clf.predict(X) -!ec -Pretty simple! -Now we can print measures of how our fit is doing, the coefficients from the fits and plot the final fit together with our data. -!bc pycod -# The mean squared error -print("Mean squared error: %.2f" % mean_squared_error(Energies, fity)) -# Explained variance score: 1 is perfect prediction -print('Variance score: %.2f' % r2_score(Energies, fity)) -# Mean absolute error -print('Mean absolute error: %.2f' % mean_absolute_error(Energies, fity)) -print(clf.coef_, clf.intercept_) - -Masses['Eapprox'] = fity -# Generate a plot comparing the experimental with the fitted values values. -fig, ax = plt.subplots() -ax.set_xlabel(r'$A = N + Z$') -ax.set_ylabel(r'$E_\mathrm{bind}\,/\mathrm{MeV}$') -ax.plot(Masses['A'], Masses['Ebinding'], alpha=0.7, lw=2, - label='Ame2016') -ax.plot(Masses['A'], Masses['Eapprox'], alpha=0.7, lw=2, c='m', - label='Fit') -ax.legend() -save_fig("Masses2016") -plt.show() -!ec - - -=== Seeing the wood for the trees === - -As a teaser, let us now see how we can do this with decision trees using _scikit-learn_. Later we will switch to so-called _random forests_! - - -!bc pycod - -#Decision Tree Regression -from sklearn.tree import DecisionTreeRegressor -regr_1=DecisionTreeRegressor(max_depth=5) -regr_2=DecisionTreeRegressor(max_depth=7) -regr_3=DecisionTreeRegressor(max_depth=9) -regr_1.fit(X, Energies) -regr_2.fit(X, Energies) -regr_3.fit(X, Energies) - - -y_1 = regr_1.predict(X) -y_2 = regr_2.predict(X) -y_3=regr_3.predict(X) -Masses['Eapprox'] = y_3 -# Plot the results -plt.figure() -plt.plot(A, Energies, color="blue", label="Data", linewidth=2) -plt.plot(A, y_1, color="red", label="max_depth=5", linewidth=2) -plt.plot(A, y_2, color="green", label="max_depth=7", linewidth=2) -plt.plot(A, y_3, color="m", label="max_depth=9", linewidth=2) - -plt.xlabel("$A$") -plt.ylabel("$E$[MeV]") -plt.title("Decision Tree Regression") -plt.legend() -save_fig("Masses2016Trees") -plt.show() -print(Masses) -print(np.mean( (Energies-y_1)**2)) -!ec - - -=== And what about using neural networks? === -The _seaborn_ package allows us to visualize data in an efficient way. Note that we use _scikit-learn_'s multi-layer perceptron (or feed forward neural network) -functionality. -!bc pycod -from sklearn.neural_network import MLPRegressor -from sklearn.metrics import accuracy_score -import seaborn as sns - -X_train = X -Y_train = Energies -n_hidden_neurons = 100 -epochs = 100 -# store models for later use -eta_vals = np.logspace(-5, 1, 7) -lmbd_vals = np.logspace(-5, 1, 7) -# store the models for later use -DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object) -train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) -sns.set() -for i, eta in enumerate(eta_vals): - for j, lmbd in enumerate(lmbd_vals): - dnn = MLPRegressor(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 - train_accuracy[i][j] = dnn.score(X_train, Y_train) - -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() - - - -!ec - - - - - - -===== A first summary ===== - -The aim behind these introductory words was to present to you various -Python libraries and their functionalities, in particular libraries like -_numpy_, _pandas_, _xarray_ and _matplotlib_ and other that make our life much easier -in handling various data sets and visualizing data. - -Furthermore, -_Scikit-Learn_ allows us with few lines of code to implement popular -Machine Learning algorithms for supervised learning. Later we will meet _Tensorflow_, a powerful library for deep learning. -Now it is time to dive more into the details of various methods. We will start with linear regression and try to take a deeper look at what it entails. - - - - - - - - -======= Why Linear Regression (aka Ordinary Least Squares and family) ======= - -Fitting a continuous function with linear parameterization in terms of the parameters $\bm{\beta}$. -* Method of choice for fitting a continuous function! -* Gives an excellent introduction to central Machine Learning features with _understandable pedagogical_ links to other methods like _Neural Networks_, _Support Vector Machines_ etc -* Analytical expression for the fitting parameters $\bm{\beta}$ -* Analytical expressions for statistical propertiers like mean values, variances, confidence intervals and more -* Analytical relation with probabilistic interpretations -* Easy to introduce basic concepts like bias-variance tradeoff, cross-validation, resampling and regularization techniques and many other ML topics -* Easy to code! And links well with classification problems and logistic regression and neural networks -* Allows for _easy_ hands-on understanding of gradient descent methods -* and many more features - -For more discussions of Ridge and Lasso regression, "Wessel van Wieringen's":"https://arxiv.org/abs/1509.09169" article is highly recommended. -Similarly, "Mehta et al's article":"https://arxiv.org/abs/1803.08823" is also recommended. - - -=== Regression analysis, overarching aims === - -Regression modeling deals with the description of the sampling distribution of a given random variable $y$ and how it varies as function of another variable or a set of such variables $\bm{x} =[x_0, x_1,\dots, x_{n-1}]^T$. -The first variable is called the _dependent_, the _outcome_ or the _response_ variable while the set of variables $\bm{x}$ is called the independent variable, or the predictor variable or the explanatory variable. - -A regression model aims at finding a likelihood function $p(\bm{y}\vert \bm{x})$, that is the conditional distribution for $\bm{y}$ with a given $\bm{x}$. The estimation of $p(\bm{y}\vert \bm{x})$ is made using a data set with -* $n$ cases $i = 0, 1, 2, \dots, n-1$ -* Response (target, dependent or outcome) variable $y_i$ with $i = 0, 1, 2, \dots, n-1$ -* $p$ so-called explanatory (independent or predictor) variables $\bm{x}_i=[x_{i0}, x_{i1}, \dots, x_{ip-1}]$ with $i = 0, 1, 2, \dots, n-1$ and explanatory variables running from $0$ to $p-1$. See below for more explicit examples. - The goal of the regression analysis is to extract/exploit relationship between $\bm{y}$ and $\bm{X}$ in or to infer causal dependencies, approximations to the likelihood functions, functional relationships and to make predictions, making fits and many other things. - - -Consider an experiment in which $p$ characteristics of $n$ samples are -measured. The data from this experiment, for various explanatory variables $p$ are normally represented by a matrix -$\mathbf{X}$. - -The matrix $\mathbf{X}$ is called the *design -matrix*. Additional information of the samples is available in the -form of $\bm{y}$ (also as above). The variable $\bm{y}$ is -generally referred to as the *response variable*. The aim of -regression analysis is to explain $\bm{y}$ in terms of -$\bm{X}$ through a functional relationship like $y_i = -f(\mathbf{X}_{i,\ast})$. When no prior knowledge on the form of -$f(\cdot)$ is available, it is common to assume a linear relationship -between $\bm{X}$ and $\bm{y}$. This assumption gives rise to -the *linear regression model* where $\bm{\beta} = [\beta_0, \ldots, -\beta_{p-1}]^{T}$ are the *regression parameters*. - -Linear regression gives us a set of analytical equations for the parameters $\beta_j$. - - -=== Examples === - -In order to understand the relation among the predictors $p$, the set of data $n$ and the target (outcome, output etc) $\bm{y}$, -consider the model we discussed for describing nuclear binding energies. - -There we assumed that we could parametrize the data using a polynomial approximation based on the liquid drop model. -Assuming -!bt -\[ -BE(A) = a_0+a_1A+a_2A^{2/3}+a_3A^{-1/3}+a_4A^{-1}, -\] -!et -we have five predictors, that is the intercept, the $A$ dependent term, the $A^{2/3}$ term and the $A^{-1/3}$ and $A^{-1}$ terms. -This gives $p=0,1,2,3,4$. Furthermore we have $n$ entries for each predictor. It means that our design matrix is a -$p\times n$ matrix $\bm{X}$. - -Here the predictors are based on a model we have made. A popular data set which is widely encountered in ML applications is the -so-called "credit card default data from Taiwan":"https://www.sciencedirect.com/science/article/pii/S0957417407006719?via%3Dihub". The data set contains data on $n=30000$ credit card holders with predictors like gender, marital status, age, profession, education, etc. In total there are $24$ such predictors or attributes leading to a design matrix of dimensionality $24 \times 30000$ - - -===== General linear models ===== - -Before we proceed let us study a case from linear algebra where we aim at fitting a set of data $\bm{y}=[y_0,y_1,\dots,y_{n-1}]$. We could think of these data as a result of an experiment or a complicated numerical experiment. These data are functions of a series of variables $\bm{x}=[x_0,x_1,\dots,x_{n-1}]$, that is $y_i = y(x_i)$ with $i=0,1,2,\dots,n-1$. The variables $x_i$ could represent physical quantities like time, temperature, position etc. We assume that $y(x)$ is a smooth function. - -Since obtaining these data points may not be trivial, we want to use these data to fit a function which can allow us to make predictions for values of $y$ which are not in the present set. The perhaps simplest approach is to assume we can parametrize our function in terms of a polynomial of degree $n-1$ with $n$ points, that is -!bt -\[ -y=y(x) \rightarrow y(x_i)=\tilde{y}_i+\epsilon_i=\sum_{j=0}^{n-1} \beta_j x_i^j+\epsilon_i, -\] -!et -where $\epsilon_i$ is the error in our approximation. - - -For every set of values $y_i,x_i$ we have thus the corresponding set of equations -!bt -\begin{align*} -y_0&=\beta_0+\beta_1x_0^1+\beta_2x_0^2+\dots+\beta_{n-1}x_0^{n-1}+\epsilon_0\\ -y_1&=\beta_0+\beta_1x_1^1+\beta_2x_1^2+\dots+\beta_{n-1}x_1^{n-1}+\epsilon_1\\ -y_2&=\beta_0+\beta_1x_2^1+\beta_2x_2^2+\dots+\beta_{n-1}x_2^{n-1}+\epsilon_2\\ -\dots & \dots \\ -y_{n-1}&=\beta_0+\beta_1x_{n-1}^1+\beta_2x_{n-1}^2+\dots+\beta_{n-1}x_{n-1}^{n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - - -Defining the vectors -!bt -\[ -\bm{y} = [y_0,y_1, y_2,\dots, y_{n-1}]^T, -\] -!et -and -!bt -\[ -\bm{\beta} = [\beta_0,\beta_1, \beta_2,\dots, \beta_{n-1}]^T, -\] -!et -and -!bt -\[ -\bm{\epsilon} = [\epsilon_0,\epsilon_1, \epsilon_2,\dots, \epsilon_{n-1}]^T, -\] -!et -and the design matrix -!bt -\[ -\bm{X}= -\begin{bmatrix} -1& x_{0}^1 &x_{0}^2& \dots & \dots &x_{0}^{n-1}\\ -1& x_{1}^1 &x_{1}^2& \dots & \dots &x_{1}^{n-1}\\ -1& x_{2}^1 &x_{2}^2& \dots & \dots &x_{2}^{n-1}\\ -\dots& \dots &\dots& \dots & \dots &\dots\\ -1& x_{n-1}^1 &x_{n-1}^2& \dots & \dots &x_{n-1}^{n-1}\\ -\end{bmatrix} -\] -!et -we can rewrite our equations as -!bt -\[ -\bm{y} = \bm{X}\bm{\beta}+\bm{\epsilon}. -\] -!et -The above design matrix is called a "Vandermonde matrix":"https://en.wikipedia.org/wiki/Vandermonde_matrix". - - - - -===== Generalizing the fitting procedure as a linear algebra problem ===== - -We are obviously not limited to the above polynomial expansions. We -could replace the various powers of $x$ with elements of Fourier -series or instead of $x_i^j$ we could have $\cos{(j x_i)}$ or $\sin{(j -x_i)}$, or time series or other orthogonal functions. For every set -of values $y_i,x_i$ we can then generalize the equations to - -!bt -\begin{align*} -y_0&=\beta_0x_{00}+\beta_1x_{01}+\beta_2x_{02}+\dots+\beta_{n-1}x_{0n-1}+\epsilon_0\\ -y_1&=\beta_0x_{10}+\beta_1x_{11}+\beta_2x_{12}+\dots+\beta_{n-1}x_{1n-1}+\epsilon_1\\ -y_2&=\beta_0x_{20}+\beta_1x_{21}+\beta_2x_{22}+\dots+\beta_{n-1}x_{2n-1}+\epsilon_2\\ -\dots & \dots \\ -y_{i}&=\beta_0x_{i0}+\beta_1x_{i1}+\beta_2x_{i2}+\dots+\beta_{n-1}x_{in-1}+\epsilon_i\\ -\dots & \dots \\ -y_{n-1}&=\beta_0x_{n-1,0}+\beta_1x_{n-1,2}+\beta_2x_{n-1,2}+\dots+\beta_{n-1}x_{n-1,n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - -_Note that we have $p=n$ here. The matrix is symmetric. This is generally not the case!_ - -We redefine in turn the matrix $\bm{X}$ as -!bt -\[ -\bm{X}= -\begin{bmatrix} -x_{00}& x_{01} &x_{02}& \dots & \dots &x_{0,n-1}\\ -x_{10}& x_{11} &x_{12}& \dots & \dots &x_{1,n-1}\\ -x_{20}& x_{21} &x_{22}& \dots & \dots &x_{2,n-1}\\ -\dots& \dots &\dots& \dots & \dots &\dots\\ -x_{n-1,0}& x_{n-1,1} &x_{n-1,2}& \dots & \dots &x_{n-1,n-1}\\ -\end{bmatrix} -\] -!et -and without loss of generality we rewrite again our equations as -!bt -\[ -\bm{y} = \bm{X}\bm{\beta}+\bm{\epsilon}. -\] -!et -The left-hand side of this equation is kwown. Our error vector $\bm{\epsilon}$ and the parameter vector $\bm{\beta}$ are our unknow quantities. How can we obtain the optimal set of $\beta_i$ values? - -We have defined the matrix $\bm{X}$ via the equations -!bt -\begin{align*} -y_0&=\beta_0x_{00}+\beta_1x_{01}+\beta_2x_{02}+\dots+\beta_{n-1}x_{0n-1}+\epsilon_0\\ -y_1&=\beta_0x_{10}+\beta_1x_{11}+\beta_2x_{12}+\dots+\beta_{n-1}x_{1n-1}+\epsilon_1\\ -y_2&=\beta_0x_{20}+\beta_1x_{21}+\beta_2x_{22}+\dots+\beta_{n-1}x_{2n-1}+\epsilon_1\\ -\dots & \dots \\ -y_{i}&=\beta_0x_{i0}+\beta_1x_{i1}+\beta_2x_{i2}+\dots+\beta_{n-1}x_{in-1}+\epsilon_1\\ -\dots & \dots \\ -y_{n-1}&=\beta_0x_{n-1,0}+\beta_1x_{n-1,2}+\beta_2x_{n-1,2}+\dots+\beta_{n-1}x_{n-1,n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - -As we noted above, we stayed with a system with the design matrix - $\bm{X}\in {\mathbb{R}}^{n\times n}$, that is we have $p=n$. For reasons to come later (algorithmic arguments) we will hereafter define -our matrix as $\bm{X}\in {\mathbb{R}}^{n\times p}$, with the predictors refering to the column numbers and the entries $n$ being the row elements. - - -===== Our model for the nuclear binding energies ===== - -In our introductory notes we looked at the so-called "liguid drop model":"https://en.wikipedia.org/wiki/Semi-empirical_mass_formula". Let us remind ourselves about what we did by looking at the code. - -We restate the parts of the code we are most interested in. -!bc pycod -# Common imports -import numpy as np -import pandas as pd -import matplotlib.pyplot as plt -from IPython.display import display -import os - -# Where to save the figures and data files -PROJECT_ROOT_DIR = "Results" -FIGURE_ID = "Results/FigureFiles" -DATA_ID = "DataFiles/" - -if not os.path.exists(PROJECT_ROOT_DIR): - os.mkdir(PROJECT_ROOT_DIR) - -if not os.path.exists(FIGURE_ID): - os.makedirs(FIGURE_ID) - -if not os.path.exists(DATA_ID): - os.makedirs(DATA_ID) - -def image_path(fig_id): - return os.path.join(FIGURE_ID, fig_id) - -def data_path(dat_id): - return os.path.join(DATA_ID, dat_id) - -def save_fig(fig_id): - plt.savefig(image_path(fig_id) + ".png", format='png') - -infile = open(data_path("MassEval2016.dat"),'r') - - -# Read the experimental data with Pandas -Masses = pd.read_fwf(infile, usecols=(2,3,4,6,11), - names=('N', 'Z', 'A', 'Element', 'Ebinding'), - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - header=39, - index_col=False) - -# Extrapolated values are indicated by '#' in place of the decimal place, so -# the Ebinding column won't be numeric. Coerce to float and drop these entries. -Masses['Ebinding'] = pd.to_numeric(Masses['Ebinding'], errors='coerce') -Masses = Masses.dropna() -# Convert from keV to MeV. -Masses['Ebinding'] /= 1000 - -# Group the DataFrame by nucleon number, A. -Masses = Masses.groupby('A') -# Find the rows of the grouped DataFrame with the maximum binding energy. -Masses = Masses.apply(lambda t: t[t.Ebinding==t.Ebinding.max()]) -A = Masses['A'] -Z = Masses['Z'] -N = Masses['N'] -Element = Masses['Element'] -Energies = Masses['Ebinding'] - -# Now we set up the design matrix X -X = np.zeros((len(A),5)) -X[:,0] = 1 -X[:,1] = A -X[:,2] = A**(2.0/3.0) -X[:,3] = A**(-1.0/3.0) -X[:,4] = A**(-1.0) -# Then nice printout using pandas -DesignMatrix = pd.DataFrame(X) -DesignMatrix.index = A -DesignMatrix.columns = ['1', 'A', 'A^(2/3)', 'A^(-1/3)', '1/A'] -display(DesignMatrix) -!ec - -With $\bm{\beta}\in {\mathbb{R}}^{p\times 1}$, it means that we will hereafter write our equations for the approximation as -!bt -\[ -\bm{\tilde{y}}= \bm{X}\bm{\beta}, -\] -!et -throughout these lectures. - - - -With the above we use the design matrix to define the approximation $\bm{\tilde{y}}$ via the unknown quantity $\bm{\beta}$ as -!bt -\[ -\bm{\tilde{y}}= \bm{X}\bm{\beta}, -\] -!et -and in order to find the optimal parameters $\beta_i$ instead of solving the above linear algebra problem, we define a function which gives a measure of the spread between the values $y_i$ (which represent hopefully the exact values) and the parameterized values $\tilde{y}_i$, namely -!bt -\[ -C(\bm{\beta})=\frac{1}{n}\sum_{i=0}^{n-1}\left(y_i-\tilde{y}_i\right)^2=\frac{1}{n}\left\{\left(\bm{y}-\bm{\tilde{y}}\right)^T\left(\bm{y}-\bm{\tilde{y}}\right)\right\}, -\] -!et -or using the matrix $\bm{X}$ and in a more compact matrix-vector notation as -!bt -\[ -C(\bm{\beta})=\frac{1}{n}\left\{\left(\bm{y}-\bm{X}^T\bm{\beta}\right)^T\left(\bm{y}-\bm{X}^T\bm{\beta}\right)\right\}. -\] -!et -This function is one possible way to define the so-called cost function. - - - -It is also common to define -the function $Q$ as - -!bt -\[ -C(\bm{\beta})=\frac{1}{2n}\sum_{i=0}^{n-1}\left(y_i-\tilde{y}_i\right)^2, -\] -!et -since when taking the first derivative with respect to the unknown parameters $\beta$, the factor of $2$ cancels out. -!eblock -translating doconce text in book.do.txt to ipynb -ERROR: 2 !bblock do not match 4 !eblock directives - - -Two !eblock after each other! - -!eblock - - -===== Numpy and arrays ===== -"Numpy":"http://www.numpy.org/" provides an easy way to handle arrays in Python. The standard way to import this library is as - -!bc pycod -import numpy as np -!ec -Here follows a simple example where we set up an array of ten elements, all determined by random numbers drawn according to the normal distribution, -!bc pycod -n = 10 -x = np.random.normal(size=n) -print(x) -!ec -We defined a vector $x$ with $n=10$ elements with its values given by the Normal distribution $N(0,1)$. -Another alternative is to declare a vector as follows -!bc pycod -import numpy as np -x = np.array([1, 2, 3]) -print(x) -!ec -Here we have defined a vector with three elements, with $x_0=1$, $x_1=2$ and $x_2=3$. Note that both Python and C++ -start numbering array elements from $0$ and on. This means that a vector with $n$ elements has a sequence of entities $x_0, x_1, x_2, \dots, x_{n-1}$. We could also let (recommended) Numpy to compute the logarithms of a specific array as -!bc pycod -import numpy as np -x = np.log(np.array([4, 7, 8])) -print(x) -!ec - -In the last example we used Numpy's unary function $np.log$. This function is -highly tuned to compute array elements since the code is vectorized -and does not require looping. We normaly recommend that you use the -Numpy intrinsic functions instead of the corresponding _log_ function -from Python's _math_ module. The looping is done explicitely by the -_np.log_ function. The alternative, and slower way to compute the -logarithms of a vector would be to write - -!bc pycod -import numpy as np -from math import log -x = np.array([4, 7, 8]) -for i in range(0, len(x)): - x[i] = log(x[i]) -print(x) -!ec -We note that our code is much longer already and we need to import the _log_ function from the _math_ module. -The attentive reader will also notice that the output is $[1, 1, 2]$. Python interprets automagically our numbers as integers (like the _automatic_ keyword in C++). To change this we could define our array elements to be double precision numbers as -!bc pycod -import numpy as np -x = np.log(np.array([4, 7, 8], dtype = np.float64)) -print(x) -!ec -or simply write them as double precision numbers (Python uses 64 bits as default for floating point type variables), that is -!bc pycod -import numpy as np -x = np.log(np.array([4.0, 7.0, 8.0]) -print(x) -!ec -To check the number of bytes (remember that one byte contains eight bits for double precision variables), you can use simple use the _itemsize_ functionality (the array $x$ is actually an object which inherits the functionalities defined in Numpy) as -!bc pycod -import numpy as np -x = np.log(np.array([4.0, 7.0, 8.0]) -print(x.itemsize) -!ec - - -===== Matrices in Python ===== - -Having defined vectors, we are now ready to try out matrices. We can -define a $3 \times 3 $ real matrix $\hat{A}$ as (recall that we user -lowercase letters for vectors and uppercase letters for matrices) - -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -print(A) -!ec -If we use the _shape_ function we would get $(3, 3)$ as output, that is verifying that our matrix is a $3\times 3$ matrix. We can slice the matrix and print for example the first column (Python organized matrix elements in a row-major order, see below) as -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -# print the first column, row-major order and elements start with 0 -print(A[:,0]) -!ec -We can continue this was by printing out other columns or rows. The example here prints out the second column -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -# print the first column, row-major order and elements start with 0 -print(A[1,:]) -!ec -Numpy contains many other functionalities that allow us to slice, subdivide etc etc arrays. We strongly recommend that you look up the "Numpy website for more details":"http://www.numpy.org/". Useful functions when defining a matrix are the _np.zeros_ function which declares a matrix of a given dimension and sets all elements to zero -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to zero -A = np.zeros( (n, n) ) -print(A) -!ec -or initializing all elements to -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to one -A = np.ones( (n, n) ) -print(A) -!ec -or as unitarily distributed random numbers (see the material on random number generators in the statistics part) -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to random numbers with x \in [0, 1] -A = np.random.rand(n, n) -print(A) -!ec - -As we will see throughout these lectures, there are several extremely useful functionalities in Numpy. -As an example, consider the discussion of the covariance matrix. Suppose we have defined three vectors -$\hat{x}, \hat{y}, \hat{z}$ with $n$ elements each. The covariance matrix is defined as -!bt -\[ -\hat{\Sigma} = \begin{bmatrix} \sigma_{xx} & \sigma_{xy} & \sigma_{xz} \\ - \sigma_{yx} & \sigma_{yy} & \sigma_{yz} \\ - \sigma_{zx} & \sigma_{zy} & \sigma_{zz} - \end{bmatrix}, -\] -!et -where for example -!bt -\[ -\sigma_{xy} =\frac{1}{n} \sum_{i=0}^{n-1}(x_i- \overline{x})(y_i- \overline{y}). -\] -!et -The Numpy function _np.cov_ calculates the covariance elements using the factor $1/(n-1)$ instead of $1/n$ since it assumes we do not have the exact mean values. -The following simple function uses the _np.vstack_ function which takes each vector of dimension $1\times n$ and produces a $3\times n$ matrix $\hat{W}$ -!bt -\[ -\hat{W} = \begin{bmatrix} x_0 & y_0 & z_0 \\ - x_1 & y_1 & z_1 \\ - x_2 & y_2 & z_2 \\ - \dots & \dots & \dots \\ - x_{n-2} & y_{n-2} & z_{n-2} \\ - x_{n-1} & y_{n-1} & z_{n-1} - \end{bmatrix}, -\] -!et - -which in turn is converted into into the $3\times 3$ covariance matrix -$\hat{\Sigma}$ via the Numpy function _np.cov()_. We note that we can also calculate -the mean value of each set of samples $\hat{x}$ etc using the Numpy -function _np.mean(x)_. We can also extract the eigenvalues of the -covariance matrix through the _np.linalg.eig()_ function. - -!bc pycod -# Importing various packages -import numpy as np - -n = 100 -x = np.random.normal(size=n) -print(np.mean(x)) -y = 4+3*x+np.random.normal(size=n) -print(np.mean(y)) -z = x**3+np.random.normal(size=n) -print(np.mean(z)) -W = np.vstack((x, y, z)) -Sigma = np.cov(W) -print(Sigma) -Eigvals, Eigvecs = np.linalg.eig(Sigma) -print(Eigvals) -!ec - - -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from scipy import sparse -eye = np.eye(4) -print(eye) -sparse_mtx = sparse.csr_matrix(eye) -print(sparse_mtx) -x = np.linspace(-10,10,100) -y = np.sin(x) -plt.plot(x,y,marker='x') -plt.show() -!ec - - -===== Meet the Pandas ===== - - -FIGURE: [fig/pandas.jpg, width=600 frac=0.8] - -Another useful Python package is -"pandas":"https://pandas.pydata.org/", which is an open source library -providing high-performance, easy-to-use data structures and data -analysis tools for Python. _pandas_ stands for panel data, a term borrowed from econometrics and is an efficient library for data analysis with an emphasis on tabular data. -_pandas_ has two major classes, the _DataFrame_ class with two-dimensional data objects and tabular data organized in columns and the class _Series_ with a focus on one-dimensional data objects. Both classes allow you to index data easily as we will see in the examples below. -_pandas_ allows you also to perform mathematical operations on the data, spanning from simple reshapings of vectors and matrices to statistical operations. - -The following simple example shows how we can, in an easy way make tables of our data. Here we define a data set which includes names, place of birth and date of birth, and displays the data in an easy to read way. We will see repeated use of _pandas_, in particular in connection with classification of data. - -!bc pycod -import pandas as pd -from IPython.display import display -data = {'First Name': ["Frodo", "Bilbo", "Aragorn II", "Samwise"], - 'Last Name': ["Baggins", "Baggins","Elessar","Gamgee"], - 'Place of birth': ["Shire", "Shire", "Eriador", "Shire"], - 'Date of Birth T.A.': [2968, 2890, 2931, 2980] - } -data_pandas = pd.DataFrame(data) -display(data_pandas) -!ec - -In the above we have imported _pandas_ with the shorthand _pd_, the latter has become the standard way we import _pandas_. We make then a list of various variables -and reorganize the aboves lists into a _DataFrame_ and then print out a neat table with specific column labels as *Name*, *place of birth* and *date of birth*. -Displaying these results, we see that the indices are given by the default numbers from zero to three. -_pandas_ is extremely flexible and we can easily change the above indices by defining a new type of indexing as -!bc pycod -data_pandas = pd.DataFrame(data,index=['Frodo','Bilbo','Aragorn','Sam']) -display(data_pandas) -!ec -Thereafter we display the content of the row which begins with the index _Aragorn_ -!bc pycod -display(data_pandas.loc['Aragorn']) -!ec - -We can easily append data to this, for example -!bc pycod -new_hobbit = {'First Name': ["Peregrin"], - 'Last Name': ["Took"], - 'Place of birth': ["Shire"], - 'Date of Birth T.A.': [2990] - } -data_pandas=data_pandas.append(pd.DataFrame(new_hobbit, index=['Pippin'])) -display(data_pandas) -!ec - - -Here are other examples where we use the _DataFrame_ functionality to handle arrays, now with more interesting features for us, namely numbers. We set up a matrix -of dimensionality $10\times 5$ and compute the mean value and standard deviation of each column. Similarly, we can perform mathematial operations like squaring the matrix elements and many other operations. -!bc pycod -import numpy as np -import pandas as pd -from IPython.display import display -np.random.seed(100) -# setting up a 10 x 5 matrix -rows = 10 -cols = 5 -a = np.random.randn(rows,cols) -df = pd.DataFrame(a) -display(df) -print(df.mean()) -print(df.std()) -display(df**2) -!ec - -Thereafter we can select specific columns only and plot final results -!bc pycod -df.columns = ['First', 'Second', 'Third', 'Fourth', 'Fifth'] -df.index = np.arange(10) - -display(df) -print(df['Second'].mean() ) -print(df.info()) -print(df.describe()) - -from pylab import plt, mpl -plt.style.use('seaborn') -mpl.rcParams['font.family'] = 'serif' - -df.cumsum().plot(lw=2.0, figsize=(10,6)) -plt.show() - - -df.plot.bar(figsize=(10,6), rot=15) -plt.show() -!ec -We can produce a $4\times 4$ matrix -!bc pycod -b = np.arange(16).reshape((4,4)) -print(b) -df1 = pd.DataFrame(b) -print(df1) -!ec -and many other operations. - -The _Series_ class is another important class included in -_pandas_. You can view it as a specialization of _DataFrame_ but where -we have just a single column of data. It shares many of the same features as _DataFrame. As with _DataFrame_, -most operations are vectorized, achieving thereby a high performance when dealing with computations of arrays, in particular labeled arrays. -As we will see below it leads also to a very concice code close to the mathematical operations we may be interested in. -For multidimensional arrays, we recommend strongly "xarray":"http://xarray.pydata.org/en/stable/". _xarray_ has much of the same flexibility as _pandas_, but allows for the extension to higher dimensions than two. We will see examples later of the usage of both _pandas_ and _xarray_. - - - -===== Reading Data and fitting ===== - -In order to study various Machine Learning algorithms, we need to -access data. Acccessing data is an essential step in all machine -learning algorithms. In particular, setting up the so-called _design -matrix_ (to be defined below) is often the first element we need in -order to perform our calculations. To set up the design matrix means -reading (and later, when the calculations are done, writing) data -in various formats, The formats span from reading files from disk, -loading data from databases and interacting with online sources -like web application programming interfaces (APIs). - -In handling various input formats, as discussed above, we will mainly stay with _pandas_, -a Python package which allows us, in a seamless and painless way, to -deal with a multitude of formats, from standard _csv_ (comma separated -values) files, via _excel_, _html_ to _hdf5_ formats. With _pandas_ -and the _DataFrame_ and _Series_ functionalities we are able to convert text data -into the calculational formats we need for a specific algorithm. And our code is going to be -pretty close the basic mathematical expressions. - -Our first data set is going to be a classic from nuclear physics, namely all -available data on binding energies. Don't be intimidated if you are not familiar with nuclear physics. It serves simply as an example here of a data set. - -We will show some of the -strengths of packages like _Scikit-Learn_ in fitting nuclear binding energies to -specific functions using linear regression first. Then, as a teaser, we will show you how -you can easily implement other algorithms like decision trees and random forests and neural networks. - -But before we really start with nuclear physics data, let's just look at some simpler polynomial fitting cases, such as, -(don't be offended) fitting straight lines! - - -=== Simple linear regression model using _scikit-learn_ === - -We start with perhaps our simplest possible example, using _Scikit-Learn_ to perform linear regression analysis on a data set produced by us. - -What follows is a simple Python code where we have defined a function -$y$ in terms of the variable $x$. Both are defined as vectors with $100$ entries. -The numbers in the vector $\hat{x}$ are given -by random numbers generated with a uniform distribution with entries -$x_i \in [0,1]$ (more about probability distribution functions -later). These values are then used to define a function $y(x)$ -(tabulated again as a vector) with a linear dependence on $x$ plus a -random noise added via the normal distribution. - - -The Numpy functions are imported used the _import numpy as np_ -statement and the random number generator for the uniform distribution -is called using the function _np.random.rand()_, where we specificy -that we want $100$ random variables. Using Numpy we define -automatically an array with the specified number of elements, $100$ in -our case. With the Numpy function _randn()_ we can compute random -numbers with the normal distribution (mean value $\mu$ equal to zero and -variance $\sigma^2$ set to one) and produce the values of $y$ assuming a linear -dependence as function of $x$ - -!bt -\[ -y = 2x+N(0,1), -\] -!et - -where $N(0,1)$ represents random numbers generated by the normal -distribution. From _Scikit-Learn_ we import then the -_LinearRegression_ functionality and make a prediction $\tilde{y} = -\alpha + \beta x$ using the function _fit(x,y)_. We call the set of -data $(\hat{x},\hat{y})$ for our training data. The Python package -_scikit-learn_ has also a functionality which extracts the above -fitting parameters $\alpha$ and $\beta$ (see below). Later we will -distinguish between training data and test data. - -For plotting we use the Python package -"matplotlib":"https://matplotlib.org/" which produces publication -quality figures. Feel free to explore the extensive -"gallery":"https://matplotlib.org/gallery/index.html" of examples. In -this example we plot our original values of $x$ and $y$ as well as the -prediction _ypredict_ ($\tilde{y}$), which attempts at fitting our -data with a straight line. - -The Python code follows here. -!bc pycod -# Importing various packages -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression - -x = np.random.rand(100,1) -y = 2*x+np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -xnew = np.array([[0],[1]]) -ypredict = linreg.predict(xnew) - -plt.plot(xnew, ypredict, "r-") -plt.plot(x, y ,'ro') -plt.axis([0,1.0,0, 5.0]) -plt.xlabel(r'$x$') -plt.ylabel(r'$y$') -plt.title(r'Simple Linear Regression') -plt.show() -!ec - -This example serves several aims. It allows us to demonstrate several -aspects of data analysis and later machine learning algorithms. The -immediate visualization shows that our linear fit is not -impressive. It goes through the data points, but there are many -outliers which are not reproduced by our linear regression. We could -now play around with this small program and change for example the -factor in front of $x$ and the normal distribution. Try to change the -function $y$ to - -!bt -\[ -y = 10x+0.01 \times N(0,1), -\] -!et - -where $x$ is defined as before. Does the fit look better? Indeed, by -reducing the role of the noise given by the normal distribution we see immediately that -our linear prediction seemingly reproduces better the training -set. However, this testing 'by the eye' is obviouly not satisfactory in the -long run. Here we have only defined the training data and our model, and -have not discussed a more rigorous approach to the _cost_ function. - -We need more rigorous criteria in defining whether we have succeeded or -not in modeling our training data. You will be surprised to see that -many scientists seldomly venture beyond this 'by the eye' approach. A -standard approach for the *cost* function is the so-called $\chi^2$ -function (a variant of the mean-squared error (MSE)) - -!bt -\[ \chi^2 = \frac{1}{n} -\sum_{i=0}^{n-1}\frac{(y_i-\tilde{y}_i)^2}{\sigma_i^2}, -\] -!et - -where $\sigma_i^2$ is the variance (to be defined later) of the entry -$y_i$. We may not know the explicit value of $\sigma_i^2$, it serves -however the aim of scaling the equations and make the cost function -dimensionless. - -Minimizing the cost function is a central aspect of -our discussions to come. Finding its minima as function of the model -parameters ($\alpha$ and $\beta$ in our case) will be a recurring -theme in these series of lectures. Essentially all machine learning -algorithms we will discuss center around the minimization of the -chosen cost function. This depends in turn on our specific -model for describing the data, a typical situation in supervised -learning. Automatizing the search for the minima of the cost function is a -central ingredient in all algorithms. Typical methods which are -employed are various variants of _gradient_ methods. These will be -discussed in more detail later. Again, you'll be surprised to hear that -many practitioners minimize the above function ''by the eye', popularly dubbed as -'chi by the eye'. That is, change a parameter and see (visually and numerically) that -the $\chi^2$ function becomes smaller. - -There are many ways to define the cost function. A simpler approach is to look at the relative difference between the training data and the predicted data, that is we define -the relative error (why would we prefer the MSE instead of the relative error?) as - -!bt -\[ -\epsilon_{\mathrm{relative}}= \frac{\vert \hat{y} -\hat{\tilde{y}}\vert}{\vert \hat{y}\vert}. -\] -!et -We can modify easily the above Python code and plot the relative error instead -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression - -x = np.random.rand(100,1) -y = 5*x+0.01*np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -ypredict = linreg.predict(x) - -plt.plot(x, np.abs(ypredict-y)/abs(y), "ro") -plt.axis([0,1.0,0.0, 0.5]) -plt.xlabel(r'$x$') -plt.ylabel(r'$\epsilon_{\mathrm{relative}}$') -plt.title(r'Relative error') -plt.show() -!ec - -Depending on the parameter in front of the normal distribution, we may -have a small or larger relative error. Try to play around with -different training data sets and study (graphically) the value of the -relative error. - -As mentioned above, _Scikit-Learn_ has an impressive functionality. -We can for example extract the values of $\alpha$ and $\beta$ and -their error estimates, or the variance and standard deviation and many -other properties from the statistical data analysis. - -Here we show an -example of the functionality of _Scikit-Learn_. -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression -from sklearn.metrics import mean_squared_error, r2_score, mean_squared_log_error, mean_absolute_error - -x = np.random.rand(100,1) -y = 2.0+ 5*x+0.5*np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -ypredict = linreg.predict(x) -print('The intercept alpha: \n', linreg.intercept_) -print('Coefficient beta : \n', linreg.coef_) -# The mean squared error -print("Mean squared error: %.2f" % mean_squared_error(y, ypredict)) -# Explained variance score: 1 is perfect prediction -print('Variance score: %.2f' % r2_score(y, ypredict)) -# Mean squared log error -print('Mean squared log error: %.2f' % mean_squared_log_error(y, ypredict) ) -# Mean absolute error -print('Mean absolute error: %.2f' % mean_absolute_error(y, ypredict)) -plt.plot(x, ypredict, "r-") -plt.plot(x, y ,'ro') -plt.axis([0.0,1.0,1.5, 7.0]) -plt.xlabel(r'$x$') -plt.ylabel(r'$y$') -plt.title(r'Linear Regression fit ') -plt.show() - -!ec -The function _coef_ gives us the parameter $\beta$ of our fit while _intercept_ yields -$\alpha$. Depending on the constant in front of the normal distribution, we get values near or far from $alpha =2$ and $\beta =5$. Try to play around with different parameters in front of the normal distribution. The function _meansquarederror_ gives us the mean square error, a risk metric corresponding to the expected value of the squared (quadratic) error or loss defined as -!bt -\[ MSE(\hat{y},\hat{\tilde{y}}) = \frac{1}{n} -\sum_{i=0}^{n-1}(y_i-\tilde{y}_i)^2, -\] -!et - -The smaller the value, the better the fit. Ideally we would like to -have an MSE equal zero. The attentive reader has probably recognized -this function as being similar to the $\chi^2$ function defined above. - -The _r2score_ function computes $R^2$, the coefficient of -determination. It provides a measure of how well future samples are -likely to be predicted by the model. Best possible score is 1.0 and it -can be negative (because the model can be arbitrarily worse). A -constant model that always predicts the expected value of $\hat{y}$, -disregarding the input features, would get a $R^2$ score of $0.0$. - -If $\tilde{\hat{y}}_i$ is the predicted value of the $i-th$ sample and $y_i$ is the corresponding true value, then the score $R^2$ is defined as -!bt -\[ -R^2(\hat{y}, \tilde{\hat{y}}) = 1 - \frac{\sum_{i=0}^{n - 1} (y_i - \tilde{y}_i)^2}{\sum_{i=0}^{n - 1} (y_i - \bar{y})^2}, -\] -!et -where we have defined the mean value of $\hat{y}$ as -!bt -\[ -\bar{y} = \frac{1}{n} \sum_{i=0}^{n - 1} y_i. -\] -!et -Another quantity taht we will meet again in our discussions of regression analysis is - the mean absolute error (MAE), a risk metric corresponding to the expected value of the absolute error loss or what we call the $l1$-norm loss. In our discussion above we presented the relative error. -The MAE is defined as follows -!bt -\[ -\text{MAE}(\hat{y}, \hat{\tilde{y}}) = \frac{1}{n} \sum_{i=0}^{n-1} \left| y_i - \tilde{y}_i \right|. -\] -!et -Finally we present the -squared logarithmic (quadratic) error -!bt -\[ -\text{MSLE}(\hat{y}, \hat{\tilde{y}}) = \frac{1}{n} \sum_{i=0}^{n - 1} (\log_e (1 + y_i) - \log_e (1 + \tilde{y}_i) )^2, -\] -!et - -where $\log_e (x)$ stands for the natural logarithm of $x$. This error -estimate is best to use when targets having exponential growth, such -as population counts, average sales of a commodity over a span of -years etc. - -We will discuss in more -detail these and other functions in the various lectures. We conclude this part with another example. Instead of -a linear $x$-dependence we study now a cubic polynomial and use the polynomial regression analysis tools of scikit-learn. - -!bc pycod -import matplotlib.pyplot as plt -import numpy as np -import random -from sklearn.linear_model import Ridge -from sklearn.preprocessing import PolynomialFeatures -from sklearn.pipeline import make_pipeline -from sklearn.linear_model import LinearRegression - -x=np.linspace(0.02,0.98,200) -noise = np.asarray(random.sample((range(200)),200)) -y=x**3*noise -yn=x**3*100 -poly3 = PolynomialFeatures(degree=3) -X = poly3.fit_transform(x[:,np.newaxis]) -clf3 = LinearRegression() -clf3.fit(X,y) - -Xplot=poly3.fit_transform(x[:,np.newaxis]) -poly3_plot=plt.plot(x, clf3.predict(Xplot), label='Cubic Fit') -plt.plot(x,yn, color='red', label="True Cubic") -plt.scatter(x, y, label='Data', color='orange', s=15) -plt.legend() -plt.show() - -def error(a): - for i in y: - err=(y-yn)/yn - return abs(np.sum(err))/len(err) - -print (error(y)) -!ec - - - - -=== To our real data: nuclear binding energies. Brief reminder on masses and binding energies === - -Let us now dive into nuclear physics and remind ourselves briefly about some basic features about binding -energies. A basic quantity which can be measured for the ground -states of nuclei is the atomic mass $M(N, Z)$ of the neutral atom with -atomic mass number $A$ and charge $Z$. The number of neutrons is $N$. There are indeed several sophisticated experiments worldwide which allow us to measure this quantity to high precision (parts per million even). - -Atomic masses are usually tabulated in terms of the mass excess defined by -!bt -\[ -\Delta M(N, Z) = M(N, Z) - uA, -\] -!et -where $u$ is the Atomic Mass Unit -!bt -\[ -u = M(^{12}\mathrm{C})/12 = 931.4940954(57) \hspace{0.1cm} \mathrm{MeV}/c^2. -\] -!et -The nucleon masses are -!bt -\[ -m_p = 1.00727646693(9)u, -\] -!et -and -!bt -\[ -m_n = 939.56536(8)\hspace{0.1cm} \mathrm{MeV}/c^2 = 1.0086649156(6)u. -\] -!et - -In the "2016 mass evaluation of by W.J.Huang, G.Audi, M.Wang, F.G.Kondev, S.Naimi and X.Xu":"http://nuclearmasses.org/resources_folder/Wang_2017_Chinese_Phys_C_41_030003.pdf" -there are data on masses and decays of 3437 nuclei. - -The nuclear binding energy is defined as the energy required to break -up a given nucleus into its constituent parts of $N$ neutrons and $Z$ -protons. In terms of the atomic masses $M(N, Z)$ the binding energy is -defined by - - -!bt -\[ -BE(N, Z) = ZM_H c^2 + Nm_n c^2 - M(N, Z)c^2 , -\] -!et -where $M_H$ is the mass of the hydrogen atom and $m_n$ is the mass of the neutron. -In terms of the mass excess the binding energy is given by -!bt -\[ -BE(N, Z) = Z\Delta_H c^2 + N\Delta_n c^2 -\Delta(N, Z)c^2 , -\] -!et -where $\Delta_H c^2 = 7.2890$ MeV and $\Delta_n c^2 = 8.0713$ MeV. - - -A popular and physically intuitive model which can be used to parametrize -the experimental binding energies as function of $A$, is the so-called -_liquid drop model_. The ansatz is based on the following expression - -!bt -\[ -BE(N,Z) = a_1A-a_2A^{2/3}-a_3\frac{Z^2}{A^{1/3}}-a_4\frac{(N-Z)^2}{A}, -\] -!et - -where $A$ stands for the number of nucleons and the $a_i$s are parameters which are determined by a fit -to the experimental data. - - - - -To arrive at the above expression we have assumed that we can make the following assumptions: - - * There is a volume term $a_1A$ proportional with the number of nucleons (the energy is also an extensive quantity). When an assembly of nucleons of the same size is packed together into the smallest volume, each interior nucleon has a certain number of other nucleons in contact with it. This contribution is proportional to the volume. - - * There is a surface energy term $a_2A^{2/3}$. The assumption here is that a nucleon at the surface of a nucleus interacts with fewer other nucleons than one in the interior of the nucleus and hence its binding energy is less. This surface energy term takes that into account and is therefore negative and is proportional to the surface area. - - - * There is a Coulomb energy term $a_3\frac{Z^2}{A^{1/3}}$. The electric repulsion between each pair of protons in a nucleus yields less binding. - - * There is an asymmetry term $a_4\frac{(N-Z)^2}{A}$. This term is associated with the Pauli exclusion principle and reflects the fact that the proton-neutron interaction is more attractive on the average than the neutron-neutron and proton-proton interactions. - -We could also add a so-called pairing term, which is a correction term that -arises from the tendency of proton pairs and neutron pairs to -occur. An even number of particles is more stable than an odd number. - - -=== Organizing our data === - -Let us start with reading and organizing our data. -We start with the compilation of masses and binding energies from 2016. -After having downloaded this file to our own computer, we are now ready to read the file and start structuring our data. - - -We start with preparing folders for storing our calculations and the data file over masses and binding energies. We import also various modules that we will find useful in order to present various Machine Learning methods. Here we focus mainly on the functionality of _scikit-learn_. -!bc pycod -# Common imports -import numpy as np -import pandas as pd -import matplotlib.pyplot as plt -import sklearn.linear_model as skl -from sklearn.model_selection import train_test_split -from sklearn.metrics import mean_squared_error, r2_score, mean_absolute_error -import os - -# Where to save the figures and data files -PROJECT_ROOT_DIR = "Results" -FIGURE_ID = "Results/FigureFiles" -DATA_ID = "DataFiles/" - -if not os.path.exists(PROJECT_ROOT_DIR): - os.mkdir(PROJECT_ROOT_DIR) - -if not os.path.exists(FIGURE_ID): - os.makedirs(FIGURE_ID) - -if not os.path.exists(DATA_ID): - os.makedirs(DATA_ID) - -def image_path(fig_id): - return os.path.join(FIGURE_ID, fig_id) - -def data_path(dat_id): - return os.path.join(DATA_ID, dat_id) - -def save_fig(fig_id): - plt.savefig(image_path(fig_id) + ".png", format='png') - -infile = open(data_path("MassEval2016.dat"),'r') -!ec - - -Before we proceed, we define also a function for making our plots. You can obviously avoid this and simply set up various _matplotlib_ commands every time you need them. You may however find it convenient to collect all such commands in one function and simply call this function. -!bc pycod -from pylab import plt, mpl -plt.style.use('seaborn') -mpl.rcParams['font.family'] = 'serif' - -def MakePlot(x,y, styles, labels, axlabels): - plt.figure(figsize=(10,6)) - for i in range(len(x)): - plt.plot(x[i], y[i], styles[i], label = labels[i]) - plt.xlabel(axlabels[0]) - plt.ylabel(axlabels[1]) - plt.legend(loc=0) -!ec - -Our next step is to read the data on experimental binding energies and -reorganize them as functions of the mass number $A$, the number of -protons $Z$ and neutrons $N$ using _pandas_. Before we do this it is -always useful (unless you have a binary file or other types of compressed -data) to actually open the file and simply take a look at it! - - -In particular, the program that outputs the final nuclear masses is written in Fortran with a specific format. It means that we need to figure out the format and which columns contain the data we are interested in. Pandas comes with a function that reads formatted output. After having admired the file, we are now ready to start massaging it with _pandas_. The file begins with some basic format information. -!bc pycod -""" -This is taken from the data file of the mass 2016 evaluation. -All files are 3436 lines long with 124 character per line. - Headers are 39 lines long. - col 1 : Fortran character control: 1 = page feed 0 = line feed - format : a1,i3,i5,i5,i5,1x,a3,a4,1x,f13.5,f11.5,f11.3,f9.3,1x,a2,f11.3,f9.3,1x,i3,1x,f12.5,f11.5 - These formats are reflected in the pandas widths variable below, see the statement - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - Pandas has also a variable header, with length 39 in this case. -""" -!ec - -The data we are interested in are in columns 2, 3, 4 and 11, giving us -the number of neutrons, protons, mass numbers and binding energies, -respectively. We add also for the sake of completeness the element name. The data are in fixed-width formatted lines and we will -covert them into the _pandas_ DataFrame structure. - -!bc pycod -# Read the experimental data with Pandas -Masses = pd.read_fwf(infile, usecols=(2,3,4,6,11), - names=('N', 'Z', 'A', 'Element', 'Ebinding'), - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - header=39, - index_col=False) - -# Extrapolated values are indicated by '#' in place of the decimal place, so -# the Ebinding column won't be numeric. Coerce to float and drop these entries. -Masses['Ebinding'] = pd.to_numeric(Masses['Ebinding'], errors='coerce') -Masses = Masses.dropna() -# Convert from keV to MeV. -Masses['Ebinding'] /= 1000 - -# Group the DataFrame by nucleon number, A. -Masses = Masses.groupby('A') -# Find the rows of the grouped DataFrame with the maximum binding energy. -Masses = Masses.apply(lambda t: t[t.Ebinding==t.Ebinding.max()]) -!ec - -We have now read in the data, grouped them according to the variables we are interested in. -We see how easy it is to reorganize the data using _pandas_. If we -were to do these operations in C/C++ or Fortran, we would have had to -write various functions/subroutines which perform the above -reorganizations for us. Having reorganized the data, we can now start -to make some simple fits using both the functionalities in _numpy_ and -_Scikit-Learn_ afterwards. - -Now we define five variables which contain -the number of nucleons $A$, the number of protons $Z$ and the number of neutrons $N$, the element name and finally the energies themselves. -!bc pycod -A = Masses['A'] -Z = Masses['Z'] -N = Masses['N'] -Element = Masses['Element'] -Energies = Masses['Ebinding'] -print(Masses) -!ec -The next step, and we will define this mathematically later, is to set up the so-called _design matrix_. We will throughout call this matrix $\bm{X}$. -It has dimensionality $p\times n$, where $n$ is the number of data points and $p$ are the so-called predictors. In our case here they are given by the number of polynomials in $A$ we wish to include in the fit. -!bc pycod -# Now we set up the design matrix X -X = np.zeros((len(A),5)) -X[:,0] = 1 -X[:,1] = A -X[:,2] = A**(2.0/3.0) -X[:,3] = A**(-1.0/3.0) -X[:,4] = A**(-1.0) -!ec -With _scikitlearn_ we are now ready to use linear regression and fit our data. -!bc pycod -clf = skl.LinearRegression().fit(X, Energies) -fity = clf.predict(X) -!ec -Pretty simple! -Now we can print measures of how our fit is doing, the coefficients from the fits and plot the final fit together with our data. -!bc pycod -# The mean squared error -print("Mean squared error: %.2f" % mean_squared_error(Energies, fity)) -# Explained variance score: 1 is perfect prediction -print('Variance score: %.2f' % r2_score(Energies, fity)) -# Mean absolute error -print('Mean absolute error: %.2f' % mean_absolute_error(Energies, fity)) -print(clf.coef_, clf.intercept_) - -Masses['Eapprox'] = fity -# Generate a plot comparing the experimental with the fitted values values. -fig, ax = plt.subplots() -ax.set_xlabel(r'$A = N + Z$') -ax.set_ylabel(r'$E_\mathrm{bind}\,/\mathrm{MeV}$') -ax.plot(Masses['A'], Masses['Ebinding'], alpha=0.7, lw=2, - label='Ame2016') -ax.plot(Masses['A'], Masses['Eapprox'], alpha=0.7, lw=2, c='m', - label='Fit') -ax.legend() -save_fig("Masses2016") -plt.show() -!ec - - -=== Seeing the wood for the trees === - -As a teaser, let us now see how we can do this with decision trees using _scikit-learn_. Later we will switch to so-called _random forests_! - - -!bc pycod - -#Decision Tree Regression -from sklearn.tree import DecisionTreeRegressor -regr_1=DecisionTreeRegressor(max_depth=5) -regr_2=DecisionTreeRegressor(max_depth=7) -regr_3=DecisionTreeRegressor(max_depth=9) -regr_1.fit(X, Energies) -regr_2.fit(X, Energies) -regr_3.fit(X, Energies) - - -y_1 = regr_1.predict(X) -y_2 = regr_2.predict(X) -y_3=regr_3.predict(X) -Masses['Eapprox'] = y_3 -# Plot the results -plt.figure() -plt.plot(A, Energies, color="blue", label="Data", linewidth=2) -plt.plot(A, y_1, color="red", label="max_depth=5", linewidth=2) -plt.plot(A, y_2, color="green", label="max_depth=7", linewidth=2) -plt.plot(A, y_3, color="m", label="max_depth=9", linewidth=2) - -plt.xlabel("$A$") -plt.ylabel("$E$[MeV]") -plt.title("Decision Tree Regression") -plt.legend() -save_fig("Masses2016Trees") -plt.show() -print(Masses) -print(np.mean( (Energies-y_1)**2)) -!ec - - -=== And what about using neural networks? === -The _seaborn_ package allows us to visualize data in an efficient way. Note that we use _scikit-learn_'s multi-layer perceptron (or feed forward neural network) -functionality. -!bc pycod -from sklearn.neural_network import MLPRegressor -from sklearn.metrics import accuracy_score -import seaborn as sns - -X_train = X -Y_train = Energies -n_hidden_neurons = 100 -epochs = 100 -# store models for later use -eta_vals = np.logspace(-5, 1, 7) -lmbd_vals = np.logspace(-5, 1, 7) -# store the models for later use -DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object) -train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) -sns.set() -for i, eta in enumerate(eta_vals): - for j, lmbd in enumerate(lmbd_vals): - dnn = MLPRegressor(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 - train_accuracy[i][j] = dnn.score(X_train, Y_train) - -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() - - - -!ec - - - - - - -===== A first summary ===== - -The aim behind these introductory words was to present to you various -Python libraries and their functionalities, in particular libraries like -_numpy_, _pandas_, _xarray_ and _matplotlib_ and other that make our life much easier -in handling various data sets and visualizing data. - -Furthermore, -_Scikit-Learn_ allows us with few lines of code to implement popular -Machine Learning algorithms for supervised learning. Later we will meet _Tensorflow_, a powerful library for deep learning. -Now it is time to dive more into the details of various methods. We will start with linear regression and try to take a deeper look at what it entails. - - - - - - - - -======= Why Linear Regression (aka Ordinary Least Squares and family) ======= - -Fitting a continuous function with linear parameterization in terms of the parameters $\bm{\beta}$. -* Method of choice for fitting a continuous function! -* Gives an excellent introduction to central Machine Learning features with _understandable pedagogical_ links to other methods like _Neural Networks_, _Support Vector Machines_ etc -* Analytical expression for the fitting parameters $\bm{\beta}$ -* Analytical expressions for statistical propertiers like mean values, variances, confidence intervals and more -* Analytical relation with probabilistic interpretations -* Easy to introduce basic concepts like bias-variance tradeoff, cross-validation, resampling and regularization techniques and many other ML topics -* Easy to code! And links well with classification problems and logistic regression and neural networks -* Allows for _easy_ hands-on understanding of gradient descent methods -* and many more features - -For more discussions of Ridge and Lasso regression, "Wessel van Wieringen's":"https://arxiv.org/abs/1509.09169" article is highly recommended. -Similarly, "Mehta et al's article":"https://arxiv.org/abs/1803.08823" is also recommended. - - -=== Regression analysis, overarching aims === - -Regression modeling deals with the description of the sampling distribution of a given random variable $y$ and how it varies as function of another variable or a set of such variables $\bm{x} =[x_0, x_1,\dots, x_{n-1}]^T$. -The first variable is called the _dependent_, the _outcome_ or the _response_ variable while the set of variables $\bm{x}$ is called the independent variable, or the predictor variable or the explanatory variable. - -A regression model aims at finding a likelihood function $p(\bm{y}\vert \bm{x})$, that is the conditional distribution for $\bm{y}$ with a given $\bm{x}$. The estimation of $p(\bm{y}\vert \bm{x})$ is made using a data set with -* $n$ cases $i = 0, 1, 2, \dots, n-1$ -* Response (target, dependent or outcome) variable $y_i$ with $i = 0, 1, 2, \dots, n-1$ -* $p$ so-called explanatory (independent or predictor) variables $\bm{x}_i=[x_{i0}, x_{i1}, \dots, x_{ip-1}]$ with $i = 0, 1, 2, \dots, n-1$ and explanatory variables running from $0$ to $p-1$. See below for more explicit examples. - The goal of the regression analysis is to extract/exploit relationship between $\bm{y}$ and $\bm{X}$ in or to infer causal dependencies, approximations to the likelihood functions, functional relationships and to make predictions, making fits and many other things. - - -Consider an experiment in which $p$ characteristics of $n$ samples are -measured. The data from this experiment, for various explanatory variables $p$ are normally represented by a matrix -$\mathbf{X}$. - -The matrix $\mathbf{X}$ is called the *design -matrix*. Additional information of the samples is available in the -form of $\bm{y}$ (also as above). The variable $\bm{y}$ is -generally referred to as the *response variable*. The aim of -regression analysis is to explain $\bm{y}$ in terms of -$\bm{X}$ through a functional relationship like $y_i = -f(\mathbf{X}_{i,\ast})$. When no prior knowledge on the form of -$f(\cdot)$ is available, it is common to assume a linear relationship -between $\bm{X}$ and $\bm{y}$. This assumption gives rise to -the *linear regression model* where $\bm{\beta} = [\beta_0, \ldots, -\beta_{p-1}]^{T}$ are the *regression parameters*. - -Linear regression gives us a set of analytical equations for the parameters $\beta_j$. - - -=== Examples === - -In order to understand the relation among the predictors $p$, the set of data $n$ and the target (outcome, output etc) $\bm{y}$, -consider the model we discussed for describing nuclear binding energies. - -There we assumed that we could parametrize the data using a polynomial approximation based on the liquid drop model. -Assuming -!bt -\[ -BE(A) = a_0+a_1A+a_2A^{2/3}+a_3A^{-1/3}+a_4A^{-1}, -\] -!et -we have five predictors, that is the intercept, the $A$ dependent term, the $A^{2/3}$ term and the $A^{-1/3}$ and $A^{-1}$ terms. -This gives $p=0,1,2,3,4$. Furthermore we have $n$ entries for each predictor. It means that our design matrix is a -$p\times n$ matrix $\bm{X}$. - -Here the predictors are based on a model we have made. A popular data set which is widely encountered in ML applications is the -so-called "credit card default data from Taiwan":"https://www.sciencedirect.com/science/article/pii/S0957417407006719?via%3Dihub". The data set contains data on $n=30000$ credit card holders with predictors like gender, marital status, age, profession, education, etc. In total there are $24$ such predictors or attributes leading to a design matrix of dimensionality $24 \times 30000$ - - -===== General linear models ===== - -Before we proceed let us study a case from linear algebra where we aim at fitting a set of data $\bm{y}=[y_0,y_1,\dots,y_{n-1}]$. We could think of these data as a result of an experiment or a complicated numerical experiment. These data are functions of a series of variables $\bm{x}=[x_0,x_1,\dots,x_{n-1}]$, that is $y_i = y(x_i)$ with $i=0,1,2,\dots,n-1$. The variables $x_i$ could represent physical quantities like time, temperature, position etc. We assume that $y(x)$ is a smooth function. - -Since obtaining these data points may not be trivial, we want to use these data to fit a function which can allow us to make predictions for values of $y$ which are not in the present set. The perhaps simplest approach is to assume we can parametrize our function in terms of a polynomial of degree $n-1$ with $n$ points, that is -!bt -\[ -y=y(x) \rightarrow y(x_i)=\tilde{y}_i+\epsilon_i=\sum_{j=0}^{n-1} \beta_j x_i^j+\epsilon_i, -\] -!et -where $\epsilon_i$ is the error in our approximation. - - -For every set of values $y_i,x_i$ we have thus the corresponding set of equations -!bt -\begin{align*} -y_0&=\beta_0+\beta_1x_0^1+\beta_2x_0^2+\dots+\beta_{n-1}x_0^{n-1}+\epsilon_0\\ -y_1&=\beta_0+\beta_1x_1^1+\beta_2x_1^2+\dots+\beta_{n-1}x_1^{n-1}+\epsilon_1\\ -y_2&=\beta_0+\beta_1x_2^1+\beta_2x_2^2+\dots+\beta_{n-1}x_2^{n-1}+\epsilon_2\\ -\dots & \dots \\ -y_{n-1}&=\beta_0+\beta_1x_{n-1}^1+\beta_2x_{n-1}^2+\dots+\beta_{n-1}x_{n-1}^{n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - - -Defining the vectors -!bt -\[ -\bm{y} = [y_0,y_1, y_2,\dots, y_{n-1}]^T, -\] -!et -and -!bt -\[ -\bm{\beta} = [\beta_0,\beta_1, \beta_2,\dots, \beta_{n-1}]^T, -\] -!et -and -!bt -\[ -\bm{\epsilon} = [\epsilon_0,\epsilon_1, \epsilon_2,\dots, \epsilon_{n-1}]^T, -\] -!et -and the design matrix -!bt -\[ -\bm{X}= -\begin{bmatrix} -1& x_{0}^1 &x_{0}^2& \dots & \dots &x_{0}^{n-1}\\ -1& x_{1}^1 &x_{1}^2& \dots & \dots &x_{1}^{n-1}\\ -1& x_{2}^1 &x_{2}^2& \dots & \dots &x_{2}^{n-1}\\ -\dots& \dots &\dots& \dots & \dots &\dots\\ -1& x_{n-1}^1 &x_{n-1}^2& \dots & \dots &x_{n-1}^{n-1}\\ -\end{bmatrix} -\] -!et -we can rewrite our equations as -!bt -\[ -\bm{y} = \bm{X}\bm{\beta}+\bm{\epsilon}. -\] -!et -The above design matrix is called a "Vandermonde matrix":"https://en.wikipedia.org/wiki/Vandermonde_matrix". - - - - -===== Generalizing the fitting procedure as a linear algebra problem ===== - -We are obviously not limited to the above polynomial expansions. We -could replace the various powers of $x$ with elements of Fourier -series or instead of $x_i^j$ we could have $\cos{(j x_i)}$ or $\sin{(j -x_i)}$, or time series or other orthogonal functions. For every set -of values $y_i,x_i$ we can then generalize the equations to - -!bt -\begin{align*} -y_0&=\beta_0x_{00}+\beta_1x_{01}+\beta_2x_{02}+\dots+\beta_{n-1}x_{0n-1}+\epsilon_0\\ -y_1&=\beta_0x_{10}+\beta_1x_{11}+\beta_2x_{12}+\dots+\beta_{n-1}x_{1n-1}+\epsilon_1\\ -y_2&=\beta_0x_{20}+\beta_1x_{21}+\beta_2x_{22}+\dots+\beta_{n-1}x_{2n-1}+\epsilon_2\\ -\dots & \dots \\ -y_{i}&=\beta_0x_{i0}+\beta_1x_{i1}+\beta_2x_{i2}+\dots+\beta_{n-1}x_{in-1}+\epsilon_i\\ -\dots & \dots \\ -y_{n-1}&=\beta_0x_{n-1,0}+\beta_1x_{n-1,2}+\beta_2x_{n-1,2}+\dots+\beta_{n-1}x_{n-1,n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - -_Note that we have $p=n$ here. The matrix is symmetric. This is generally not the case!_ - -We redefine in turn the matrix $\bm{X}$ as -!bt -\[ -\bm{X}= -\begin{bmatrix} -x_{00}& x_{01} &x_{02}& \dots & \dots &x_{0,n-1}\\ -x_{10}& x_{11} &x_{12}& \dots & \dots &x_{1,n-1}\\ -x_{20}& x_{21} &x_{22}& \dots & \dots &x_{2,n-1}\\ -\dots& \dots &\dots& \dots & \dots &\dots\\ -x_{n-1,0}& x_{n-1,1} &x_{n-1,2}& \dots & \dots &x_{n-1,n-1}\\ -\end{bmatrix} -\] -!et -and without loss of generality we rewrite again our equations as -!bt -\[ -\bm{y} = \bm{X}\bm{\beta}+\bm{\epsilon}. -\] -!et -The left-hand side of this equation is kwown. Our error vector $\bm{\epsilon}$ and the parameter vector $\bm{\beta}$ are our unknow quantities. How can we obtain the optimal set of $\beta_i$ values? - -We have defined the matrix $\bm{X}$ via the equations -!bt -\begin{align*} -y_0&=\beta_0x_{00}+\beta_1x_{01}+\beta_2x_{02}+\dots+\beta_{n-1}x_{0n-1}+\epsilon_0\\ -y_1&=\beta_0x_{10}+\beta_1x_{11}+\beta_2x_{12}+\dots+\beta_{n-1}x_{1n-1}+\epsilon_1\\ -y_2&=\beta_0x_{20}+\beta_1x_{21}+\beta_2x_{22}+\dots+\beta_{n-1}x_{2n-1}+\epsilon_1\\ -\dots & \dots \\ -y_{i}&=\beta_0x_{i0}+\beta_1x_{i1}+\beta_2x_{i2}+\dots+\beta_{n-1}x_{in-1}+\epsilon_1\\ -\dots & \dots \\ -y_{n-1}&=\beta_0x_{n-1,0}+\beta_1x_{n-1,2}+\beta_2x_{n-1,2}+\dots+\beta_{n-1}x_{n-1,n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - -As we noted above, we stayed with a system with the design matrix - $\bm{X}\in {\mathbb{R}}^{n\times n}$, that is we have $p=n$. For reasons to come later (algorithmic arguments) we will hereafter define -our matrix as $\bm{X}\in {\mathbb{R}}^{n\times p}$, with the predictors refering to the column numbers and the entries $n$ being the row elements. - - -===== Our model for the nuclear binding energies ===== - -In our introductory notes we looked at the so-called "liguid drop model":"https://en.wikipedia.org/wiki/Semi-empirical_mass_formula". Let us remind ourselves about what we did by looking at the code. - -We restate the parts of the code we are most interested in. -!bc pycod -# Common imports -import numpy as np -import pandas as pd -import matplotlib.pyplot as plt -from IPython.display import display -import os - -# Where to save the figures and data files -PROJECT_ROOT_DIR = "Results" -FIGURE_ID = "Results/FigureFiles" -DATA_ID = "DataFiles/" - -if not os.path.exists(PROJECT_ROOT_DIR): - os.mkdir(PROJECT_ROOT_DIR) - -if not os.path.exists(FIGURE_ID): - os.makedirs(FIGURE_ID) - -if not os.path.exists(DATA_ID): - os.makedirs(DATA_ID) - -def image_path(fig_id): - return os.path.join(FIGURE_ID, fig_id) - -def data_path(dat_id): - return os.path.join(DATA_ID, dat_id) - -def save_fig(fig_id): - plt.savefig(image_path(fig_id) + ".png", format='png') - -infile = open(data_path("MassEval2016.dat"),'r') - - -# Read the experimental data with Pandas -Masses = pd.read_fwf(infile, usecols=(2,3,4,6,11), - names=('N', 'Z', 'A', 'Element', 'Ebinding'), - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - header=39, - index_col=False) - -# Extrapolated values are indicated by '#' in place of the decimal place, so -# the Ebinding column won't be numeric. Coerce to float and drop these entries. -Masses['Ebinding'] = pd.to_numeric(Masses['Ebinding'], errors='coerce') -Masses = Masses.dropna() -# Convert from keV to MeV. -Masses['Ebinding'] /= 1000 - -# Group the DataFrame by nucleon number, A. -Masses = Masses.groupby('A') -# Find the rows of the grouped DataFrame with the maximum binding energy. -Masses = Masses.apply(lambda t: t[t.Ebinding==t.Ebinding.max()]) -A = Masses['A'] -Z = Masses['Z'] -N = Masses['N'] -Element = Masses['Element'] -Energies = Masses['Ebinding'] - -# Now we set up the design matrix X -X = np.zeros((len(A),5)) -X[:,0] = 1 -X[:,1] = A -X[:,2] = A**(2.0/3.0) -X[:,3] = A**(-1.0/3.0) -X[:,4] = A**(-1.0) -# Then nice printout using pandas -DesignMatrix = pd.DataFrame(X) -DesignMatrix.index = A -DesignMatrix.columns = ['1', 'A', 'A^(2/3)', 'A^(-1/3)', '1/A'] -display(DesignMatrix) -!ec - -With $\bm{\beta}\in {\mathbb{R}}^{p\times 1}$, it means that we will hereafter write our equations for the approximation as -!bt -\[ -\bm{\tilde{y}}= \bm{X}\bm{\beta}, -\] -!et -throughout these lectures. - - - -With the above we use the design matrix to define the approximation $\bm{\tilde{y}}$ via the unknown quantity $\bm{\beta}$ as -!bt -\[ -\bm{\tilde{y}}= \bm{X}\bm{\beta}, -\] -!et -and in order to find the optimal parameters $\beta_i$ instead of solving the above linear algebra problem, we define a function which gives a measure of the spread between the values $y_i$ (which represent hopefully the exact values) and the parameterized values $\tilde{y}_i$, namely -!bt -\[ -C(\bm{\beta})=\frac{1}{n}\sum_{i=0}^{n-1}\left(y_i-\tilde{y}_i\right)^2=\frac{1}{n}\left\{\left(\bm{y}-\bm{\tilde{y}}\right)^T\left(\bm{y}-\bm{\tilde{y}}\right)\right\}, -\] -!et -or using the matrix $\bm{X}$ and in a more compact matrix-vector notation as -!bt -\[ -C(\bm{\beta})=\frac{1}{n}\left\{\left(\bm{y}-\bm{X}^T\bm{\beta}\right)^T\left(\bm{y}-\bm{X}^T\bm{\beta}\right)\right\}. -\] -!et -This function is one possible way to define the so-called cost function. - - - -It is also common to define -the function $Q$ as - -!bt -\[ -C(\bm{\beta})=\frac{1}{2n}\sum_{i=0}^{n-1}\left(y_i-\tilde{y}_i\right)^2, -\] -!et -since when taking the first derivative with respect to the unknown parameters $\beta$, the factor of $2$ cancels out. -!eblock -translating doconce text in book.do.txt to ipynb -*** replacing \bm{...} by \boldsymbol{...} (\bm is not supported by MathJax) -*** error: figure file "fig/pandas.jpg" does not exist! -translating doconce text in book.do.txt to ipynb -*** replacing \bm{...} by \boldsymbol{...} (\bm is not supported by MathJax) -collected all required additional files in ipynb-book-src.tar.gz which must be distributed with the notebook -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{eqnarray*} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -output in book.ipynb -*** error: file has a mako construction ${\bf \hat{J}' - but seemingly no definition in <%...%>' - (it is not a command-line given mako variable either). - However, if this is a variable in a Makefile or Bash script - run with --no_mako - and you cannot use mako and Makefile or Bash variables - in the same document! - -*** error: file has a mako construction ${\bm{J}' - but seemingly no definition in <%...%>' - (it is not a command-line given mako variable either). - However, if this is a variable in a Makefile or Bash script - run with --no_mako - and you cannot use mako and Makefile or Bash variables - in the same document! - -translating doconce text in book.do.txt to ipynb -*** replacing \bm{...} by \boldsymbol{...} (\bm is not supported by MathJax) -collected all required additional files in ipynb-book-src.tar.gz which must be distributed with the notebook -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{eqnarray*} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -output in book.ipynb -translating doconce text in book.do.txt to ipynb -*** replacing \bm{...} by \boldsymbol{...} (\bm is not supported by MathJax) -collected all required additional files in ipynb-book-src.tar.gz which must be distributed with the notebook -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{eqnarray*} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -output in book.ipynb -translating doconce text in book.do.txt to latex -figure fig/pandas.jpg must have extension(s) .eps, .ps -*** warning: need to convert from fig/pandas.jpg to fig/pandas.eps -using ImageMagick's convert program, but the result will -be loss of quality. Generate a proper fig/pandas.eps file (if possible). -....image conversion: convert fig/pandas.jpg fig/pandas.eps -output in book.p.tex -translating doconce text in book.do.txt to ipynb -*** replacing \bm{...} by \boldsymbol{...} (\bm is not supported by MathJax) -collected all required additional files in ipynb-book-src.tar.gz which must be distributed with the notebook -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{bmatrix} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -*** warning: latex envir \begin{cases} does not work well in Markdown. - Stick to \[ ... \], equation, equation*, align, or align* - environments in math environments. - -Failed to remove ans_at_end environment -Failed to remove sol_at_end environment -output in book.ipynb diff --git a/doc/LectureNotes/book.do.txt b/doc/LectureNotes/book.do.txt index ebfd8b443..eda1009af 100644 --- a/doc/LectureNotes/book.do.txt +++ b/doc/LectureNotes/book.do.txt @@ -1657,5 +1657,1869 @@ Now it is time to dive more into the details of various methods. We will start w ======= Review of Basic Statistics ======= +===== Domains and probabilities ===== +!bblock +Consider the following simple example, namely the tossing of two dice, resulting in the following possible values +!bt +\begin{equation*} +\{2,3,4,5,6,7,8,9,10,11,12\}. +\end{equation*} +!et +These values are called the *domain*. +To this domain we have the corresponding *probabilities* +!bt +\begin{equation*} +\{1/36,2/36/,3/36,4/36,5/36,6/36,5/36,4/36,3/36,2/36,1/36\}. +\end{equation*} +!et +!eblock + + +===== Tossing the dice ===== +!bblock +The numbers in the domain are the outcomes of the physical process of tossing say two dice. +We cannot tell beforehand whether the outcome is 3 or 5 or any other number in this domain. +This defines the randomness of the outcome, or unexpectedness or any other synonimous word which +encompasses the uncertitude of the final outcome. + +The only thing we can tell beforehand +is that say the outcome 2 has a certain probability. +If our favorite hobby is to spend an hour every evening throwing dice and +registering the sequence of outcomes, we will note that the numbers in the above domain +!bt +\begin{equation*} +\{2,3,4,5,6,7,8,9,10,11,12\}, +\end{equation*} +!et +appear in a random order. After 11 throws the results may look like + +!bt +\begin{equation*} +\{10,8,6,3,6,9,11,8,12,4,5\}. +\end{equation*} +!et +!eblock + + +===== Stochastic variables ===== +!bblock + +_Random variables are characterized by a domain which contains all possible values that the random value may take. This domain has a corresponding probability distribution function(PDF)_. +!eblock + + +===== Stochastic variables and the main concepts, the discrete case ===== +!bblock +There are two main concepts associated with a stochastic variable. The +*domain* is the set $\mathbb D = \{x\}$ of all accessible values +the variable can assume, so that $X \in \mathbb D$. An example of a +discrete domain is the set of six different numbers that we may get by +throwing of a dice, $x\in\{1,\,2,\,3,\,4,\,5,\,6\}$. + +The *probability distribution function (PDF)* is a function +$p(x)$ on the domain which, in the discrete case, gives us the +probability or relative frequency with which these values of $X$ +occur +!bt +\begin{equation*} +p(x) = \mathrm{Prob}(X=x). +\end{equation*} +!et +!eblock + + + +===== Stochastic variables and the main concepts, the continuous case ===== +!bblock +In the continuous case, the PDF does not directly depict the +actual probability. Instead we define the probability for the +stochastic variable to assume any value on an infinitesimal interval +around $x$ to be $p(x)dx$. The continuous function $p(x)$ then gives us +the *density* of the probability rather than the probability +itself. The probability for a stochastic variable to assume any value +on a non-infinitesimal interval $[a,\,b]$ is then just the integral + +!bt +\begin{equation*} +\mathrm{Prob}(a\leq X\leq b) = \int_a^b p(x)dx. +\end{equation*} +!et +Qualitatively speaking, a stochastic variable represents the values of +numbers chosen as if by chance from some specified PDF so that the +selection of a large set of these numbers reproduces this PDF. +!eblock + + +===== The cumulative probability ===== +!bblock +Of interest to us is the *cumulative probability +distribution function* (_CDF_), $P(x)$, which is just the probability +for a stochastic variable $X$ to assume any value less than $x$ +!bt +\begin{equation*} +P(x)=\mathrm{Prob(}X\leq x\mathrm{)} = +\int_{-\infty}^x p(x^{\prime})dx^{\prime}. +\end{equation*} +!et +The relation between a CDF and its corresponding PDF is then + +!bt +\begin{equation*} +p(x) = \frac{d}{dx}P(x). +\end{equation*} +!et +!eblock + + +===== Properties of PDFs ===== +!bblock + +There are two properties that all PDFs must satisfy. The first one is +positivity (assuming that the PDF is normalized) + +!bt +\begin{equation*} +0 \leq p(x) \leq 1. +\end{equation*} +!et +Naturally, it would be nonsensical for any of the values of the domain +to occur with a probability greater than $1$ or less than $0$. Also, +the PDF must be normalized. That is, all the probabilities must add up +to unity. The probability of ``anything'' to happen is always unity. For +both discrete and continuous PDFs, this condition is +!bt +\begin{align*} +\sum_{x_i\in\mathbb D} p(x_i) & = 1,\\ +\int_{x\in\mathbb D} p(x)\,dx & = 1. +\end{align*} +!et +!eblock + + +===== Important distributions, the uniform distribution ===== +!bblock +The first one +is the most basic PDF; namely the uniform distribution +!bt +\begin{equation} +p(x) = \frac{1}{b-a}\theta(x-a)\theta(b-x). +label{eq:unifromPDF} +\end{equation} +!et +For $a=0$ and $b=1$ we have +!bt +\[ +\begin{array}{ll} +p(x)dx = dx & \in [0,1]. +\end{array} +\] +!et +The latter distribution is used to generate random numbers. For other PDFs, one needs normally a mapping from this distribution to say for example the exponential distribution. +!eblock + + +===== Gaussian distribution ===== +!bblock +The second one is the Gaussian Distribution +!bt +\begin{equation*} +p(x) = \frac{1}{\sigma\sqrt{2\pi}} \exp{(-\frac{(x-\mu)^2}{2\sigma^2})}, +\end{equation*} +!et +with mean value $\mu$ and standard deviation $\sigma$. If $\mu=0$ and $\sigma=1$, it is normally called the _standard normal distribution_ +!bt +\begin{equation*} +p(x) = \frac{1}{\sqrt{2\pi}} \exp{(-\frac{x^2}{2})}, +\end{equation*} +!et + +The following simple Python code plots the above distribution for different values of $\mu$ and $\sigma$. +!bc pyscpro +import numpy as np +from math import acos, exp, sqrt +from matplotlib import pyplot as plt +from matplotlib import rc, rcParams +import matplotlib.units as units +import matplotlib.ticker as ticker +rc('text',usetex=True) +rc('font',**{'family':'serif','serif':['Gaussian distribution']}) +font = {'family' : 'serif', + 'color' : 'darkred', + 'weight' : 'normal', + 'size' : 16, + } +pi = acos(-1.0) +mu0 = 0.0 +sigma0 = 1.0 +mu1= 1.0 +sigma1 = 2.0 +mu2 = 2.0 +sigma2 = 4.0 + +x = np.linspace(-20.0, 20.0) +v0 = np.exp(-(x*x-2*x*mu0+mu0*mu0)/(2*sigma0*sigma0))/sqrt(2*pi*sigma0*sigma0) +v1 = np.exp(-(x*x-2*x*mu1+mu1*mu1)/(2*sigma1*sigma1))/sqrt(2*pi*sigma1*sigma1) +v2 = np.exp(-(x*x-2*x*mu2+mu2*mu2)/(2*sigma2*sigma2))/sqrt(2*pi*sigma2*sigma2) +plt.plot(x, v0, 'b-', x, v1, 'r-', x, v2, 'g-') +plt.title(r'{\bf Gaussian distributions}', fontsize=20) +plt.text(-19, 0.3, r'Parameters: $\mu = 0$, $\sigma = 1$', fontdict=font) +plt.text(-19, 0.18, r'Parameters: $\mu = 1$, $\sigma = 2$', fontdict=font) +plt.text(-19, 0.08, r'Parameters: $\mu = 2$, $\sigma = 4$', fontdict=font) +plt.xlabel(r'$x$',fontsize=20) +plt.ylabel(r'$p(x)$ [MeV]',fontsize=20) + +# Tweak spacing to prevent clipping of ylabel +plt.subplots_adjust(left=0.15) +plt.savefig('gaussian.pdf', format='pdf') +plt.show() +!ec +!eblock + + + +===== Exponential distribution ===== +!bblock +Another important distribution in science is the exponential distribution +!bt +\begin{equation*} +p(x) = \alpha\exp{-(\alpha x)}. +\end{equation*} +!et +!eblock + + +===== Expectation values ===== +!bblock +Let $h(x)$ be an arbitrary continuous function on the domain of the stochastic +variable $X$ whose PDF is $p(x)$. We define the *expectation value* +of $h$ with respect to $p$ as follows + +!bt +\begin{equation} +\langle h \rangle_X \equiv \int\! h(x)p(x)\,dx +label{eq:expectation_value_of_h_wrt_p} +\end{equation} +!et +Whenever the PDF is known implicitly, like in this case, we will drop +the index $X$ for clarity. +A particularly useful class of special expectation values are the +*moments*. The $n$-th moment of the PDF $p$ is defined as +follows +!bt +\begin{equation*} +\langle x^n \rangle \equiv \int\! x^n p(x)\,dx +\end{equation*} +!et +!eblock + + +===== Stochastic variables and the main concepts, mean values ===== +!bblock +The zero-th moment $\langle 1\rangle$ is just the normalization condition of +$p$. The first moment, $\langle x\rangle$, is called the *mean* of $p$ +and often denoted by the letter $\mu$ +!bt +\begin{equation*} +\langle x\rangle = \mu \equiv \int x p(x)dx, +\end{equation*} +!et +for a continuous distribution and +!bt +\begin{equation*} +\langle x\rangle = \mu \equiv \sum_{i=1}^N x_i p(x_i), +\end{equation*} +!et +for a discrete distribution. +Qualitatively it represents the centroid or the average value of the +PDF and is therefore simply called the expectation value of $p(x)$. +!eblock + + +===== Stochastic variables and the main concepts, central moments, the variance ===== +!bblock + +A special version of the moments is the set of *central moments*, the n-th central moment defined as +!bt +\begin{equation*} +\langle (x-\langle x\rangle )^n\rangle \equiv \int\! (x-\langle x\rangle)^n p(x)\,dx +\end{equation*} +!et +The zero-th and first central moments are both trivial, equal $1$ and +$0$, respectively. But the second central moment, known as the +*variance* of $p$, is of particular interest. For the stochastic +variable $X$, the variance is denoted as $\sigma^2_X$ or $\mathrm{Var}(X)$ +!bt +\begin{align*} +\sigma^2_X &=\mathrm{Var}(X) = \langle (x-\langle x\rangle)^2\rangle = +\int (x-\langle x\rangle)^2 p(x)dx\\ +& = \int\left(x^2 - 2 x \langle x\rangle^{2} +\langle x\rangle^2\right)p(x)dx\\ +& = \langle x^2\rangle - 2 \langle x\rangle\langle x\rangle + \langle x\rangle^2\\ +& = \langle x^2 \rangle - \langle x\rangle^2 +\end{align*} +!et +The square root of the variance, $\sigma =\sqrt{\langle (x-\langle x\rangle)^2\rangle}$ is called the +_standard deviation_ of $p$. It is the RMS (root-mean-square) +value of the deviation of the PDF from its mean value, interpreted +qualitatively as the ``spread'' of $p$ around its mean. +!eblock + + + + +===== Probability Distribution Functions ===== +!bblock + +The following table collects properties of probability distribution functions. +In our notation we reserve the label $p(x)$ for the probability of a certain event, +while $P(x)$ is the cumulative probability. + + +|--------------------------------------------------------------------------------------------------------------------------------------| +| | Discrete PDF | Continuous PDF | +|---------------------l-------------------------------------------c-------------------------------------------c------------------------| +| Domain | $\left\{x_1, x_2, x_3, \dots, x_N\right\}$ | $[a,b]$ | +| Probability | $p(x_i)$ | $p(x)dx$ | +| Cumulative | $P_i=\sum_{l=1}^ip(x_l)$ | $P(x)=\int_a^xp(t)dt$ | +| Positivity | $0 \le p(x_i) \le 1$ | $p(x) \ge 0$ | +| Positivity | $0 \le P_i \le 1$ | $0 \le P(x) \le 1$ | +| Monotonic | $P_i \ge P_j$ if $x_i \ge x_j$ | $P(x_i) \ge P(x_j)$ if $x_i \ge x_j$ | +| Normalization | $P_N=1$ | $P(b)=1$ | +|--------------------------------------------------------------------------------------------------------------------------------------| + +!eblock + + + +===== Probability Distribution Functions ===== +!bblock +With a PDF we can compute expectation values of selected quantities such as + +!bt +\begin{equation*} + \langle x^k\rangle=\sum_{i=1}^{N}x_i^kp(x_i), +\end{equation*} +!et +if we have a discrete PDF or + +!bt +\begin{equation*} + \langle x^k\rangle=\int_a^b x^kp(x)dx, +\end{equation*} +!et +in the case of a continuous PDF. We have already defined the mean value $\mu$ +and the variance $\sigma^2$. +!eblock + + +===== The three famous Probability Distribution Functions ===== +!bblock + +There are at least three PDFs which one may encounter. These are the + +_Uniform distribution_ +!bt +\begin{equation*} +p(x)=\frac{1}{b-a}\Theta(x-a)\Theta(b-x), +\end{equation*} +!et +yielding probabilities different from zero in the interval $[a,b]$. + +_The exponential distribution_ +!bt +\begin{equation*} +p(x)=\alpha \exp{(-\alpha x)}, +\end{equation*} +!et +yielding probabilities different from zero in the interval $[0,\infty)$ and with mean value +!bt +\begin{equation*} +\mu = \int_0^{\infty}xp(x)dx=\int_0^{\infty}x\alpha \exp{(-\alpha x)}dx=\frac{1}{\alpha}, +\end{equation*} +!et +!eblock +with variance +!bt +\begin{equation*} +\sigma^2=\int_0^{\infty}x^2p(x)dx-\mu^2 = \frac{1}{\alpha^2}. +\end{equation*} +!et + + +===== Probability Distribution Functions, the normal distribution ===== +!bblock +Finally, we have the so-called univariate normal distribution, or just the _normal distribution_ +!bt +\begin{equation*} +p(x)=\frac{1}{b\sqrt{2\pi}}\exp{\left(-\frac{(x-a)^2}{2b^2}\right)} +\end{equation*} +!et +with probabilities different from zero in the interval $(-\infty,\infty)$. +The integral $\int_{-\infty}^{\infty}\exp{\left(-(x^2\right)}dx$ appears in many calculations, its value +is $\sqrt{\pi}$, a result we will need when we compute the mean value and the variance. +The mean value is +!bt +\begin{equation*} + \mu = \int_0^{\infty}xp(x)dx=\frac{1}{b\sqrt{2\pi}}\int_{-\infty}^{\infty}x \exp{\left(-\frac{(x-a)^2}{2b^2}\right)}dx, +\end{equation*} +!et +which becomes with a suitable change of variables +!bt +\begin{equation*} + \mu =\frac{1}{b\sqrt{2\pi}}\int_{-\infty}^{\infty}b\sqrt{2}(a+b\sqrt{2}y)\exp{-y^2}dy=a. +\end{equation*} +!et +!eblock + + +===== Probability Distribution Functions, the normal distribution ===== +!bblock +Similarly, the variance becomes +!bt +\begin{equation*} + \sigma^2 = \frac{1}{b\sqrt{2\pi}}\int_{-\infty}^{\infty}(x-\mu)^2 \exp{\left(-\frac{(x-a)^2}{2b^2}\right)}dx, +\end{equation*} +!et +and inserting the mean value and performing a variable change we obtain + +!bt +\begin{equation*} + \sigma^2 = \frac{1}{b\sqrt{2\pi}}\int_{-\infty}^{\infty}b\sqrt{2}(b\sqrt{2}y)^2\exp{\left(-y^2\right)}dy= +\frac{2b^2}{\sqrt{\pi}}\int_{-\infty}^{\infty}y^2\exp{\left(-y^2\right)}dy, +\end{equation*} +!et +and performing a final integration by parts we obtain the well-known result $\sigma^2=b^2$. +It is useful to introduce the standard normal distribution as well, defined by $\mu=a=0$, viz. a distribution +centered around zero and with a variance $\sigma^2=1$, leading to + +!bt +\begin{equation} + p(x)=\frac{1}{\sqrt{2\pi}}\exp{\left(-\frac{x^2}{2}\right)}. +\end{equation} +!et +!eblock + + +===== Probability Distribution Functions, the cumulative distribution ===== +!bblock + +The exponential and uniform distributions have simple cumulative functions, +whereas the normal distribution does not, being proportional to the so-called +error function $erf(x)$, given by + +!bt +\begin{equation*} +P(x) = \frac{1}{\sqrt{2\pi}}\int_{-\infty}^x\exp{\left(-\frac{t^2}{2}\right)}dt, +\end{equation*} +!et +which is difficult to evaluate in a quick way. +!eblock + + + +===== Probability Distribution Functions, other important distribution ===== +!bblock + +Some other PDFs which one encounters often in the natural sciences are the binomial distribution +!bt +\begin{equation*} + p(x) = \left(\begin{array}{c} n \\ x\end{array}\right)y^x(1-y)^{n-x} \hspace{0.5cm}x=0,1,\dots,n, +\end{equation*} +!et +where $y$ is the probability for a specific event, such as the tossing of a coin or moving left or right +in case of a random walker. Note that $x$ is a discrete stochastic variable. + +The sequence of binomial trials is characterized by the following definitions + + * Every experiment is thought to consist of $N$ independent trials. + + * In every independent trial one registers if a specific situation happens or not, such as the jump to the left or right of a random walker. + + * The probability for every outcome in a single trial has the same value, for example the outcome of tossing (either heads or tails) a coin is always $1/2$. +!eblock + + +===== Probability Distribution Functions, the binomial distribution ===== +!bblock + +In order to compute the mean and variance we need to recall Newton's binomial +formula +!bt +\begin{equation*} + (a+b)^m=\sum_{n=0}^m \left(\begin{array}{c} m \\ n\end{array}\right)a^nb^{m-n}, +\end{equation*} +!et +which can be used to show that + +!bt +\begin{equation*} +\sum_{x=0}^n\left(\begin{array}{c} n \\ x\end{array}\right)y^x(1-y)^{n-x} = (y+1-y)^n = 1, +\end{equation*} +!et +the PDF is normalized to one. +The mean value is +!bt +\begin{equation*} +\mu = \sum_{x=0}^n x\left(\begin{array}{c} n \\ x\end{array}\right)y^x(1-y)^{n-x} = +\sum_{x=0}^n x\frac{n!}{x!(n-x)!}y^x(1-y)^{n-x}, +\end{equation*} +!et +resulting in +!bt +\begin{equation*} +\mu = +\sum_{x=0}^n x\frac{(n-1)!}{(x-1)!(n-1-(x-1))!}y^{x-1}(1-y)^{n-1-(x-1)}, +\end{equation*} +!et +which we rewrite as + +!bt +\begin{equation*} +\mu=ny\sum_{\nu=0}^n\left(\begin{array}{c} n-1 \\ \nu\end{array}\right)y^{\nu}(1-y)^{n-1-\nu} =ny(y+1-y)^{n-1}=ny. +\end{equation*} +!et +!eblock +The variance is slightly trickier to get. It reads $\sigma^2=ny(1-y)$. + + +===== Probability Distribution Functions, Poisson's distribution ===== +!bblock + +Another important distribution with discrete stochastic variables $x$ is +the Poisson model, which resembles the exponential distribution and reads +!bt +\begin{equation*} + p(x) = \frac{\lambda^x}{x!} e^{-\lambda} \hspace{0.5cm}x=0,1,\dots,;\lambda > 0. +\end{equation*} +!et +In this case both the mean value and the variance are easier to calculate, + +!bt +\begin{equation*} +\mu = \sum_{x=0}^{\infty} x \frac{\lambda^x}{x!} e^{-\lambda} = \lambda e^{-\lambda}\sum_{x=1}^{\infty} +\frac{\lambda^{x-1}}{(x-1)!}=\lambda, +\end{equation*} +!et +and the variance is $\sigma^2=\lambda$. +!eblock + + + + +===== Probability Distribution Functions, Poisson's distribution ===== +!bblock +An example of applications of the Poisson distribution could be the counting +of the number of $\alpha$-particles emitted from a radioactive source in a given time interval. +In the limit of $n\rightarrow \infty$ and for small probabilities $y$, the binomial distribution +approaches the Poisson distribution. Setting $\lambda = ny$, with $y$ the probability for an event in +the binomial distribution we can show that + +!bt +\begin{equation*} +\lim_{n\rightarrow \infty}\left(\begin{array}{c} n \\ x\end{array}\right)y^x(1-y)^{n-x} e^{-\lambda}=\sum_{x=1}^{\infty}\frac{\lambda^x}{x!} e^{-\lambda}. +\end{equation*} +!et +!eblock + + + +===== Meet the covariance! ===== +!bblock +An important quantity in a statistical analysis is the so-called covariance. + +Consider the set $\{X_i\}$ of $n$ +stochastic variables (not necessarily uncorrelated) with the +multivariate PDF $P(x_1,\dots,x_n)$. The *covariance* of two +of the stochastic variables, $X_i$ and $X_j$, is defined as follows + +!bt +\begin{align} +\mathrm{Cov}(X_i,\,X_j) & = \langle (x_i-\langle x_i\rangle)(x_j-\langle x_j\rangle)\rangle \\ +&=\int\cdots\int (x_i-\langle x_i\rangle)(x_j-\langle x_j\rangle)P(x_1,\dots,x_n)\,dx_1\dots dx_n, +label{eq:def_covariance} +\end{align} +!et +with +!bt +\begin{equation*} +\langle x_i\rangle = +\int\cdots\int x_i P(x_1,\dots,x_n)\,dx_1\dots dx_n. +\end{equation*} +!et +!eblock + + + + +===== Meet the covariance in matrix disguise ===== +!bblock +If we consider the above covariance as a matrix +!bt +\[ +C_{ij} =\mathrm{Cov}(X_i,\,X_j), +\] +!et +then the diagonal elements are just the familiar +variances, $C_{ii} = \mathrm{Cov}(X_i,\,X_i) = \mathrm{Var}(X_i)$. It turns out that +all the off-diagonal elements are zero if the stochastic variables are +uncorrelated. +!eblock + + +===== Covariance ===== +!bc pycod +# Importing various packages +from math import exp, sqrt +from random import random, seed +import numpy as np +import matplotlib.pyplot as plt + +def covariance(x, y, n): + sum = 0.0 + mean_x = np.mean(x) + mean_y = np.mean(y) + for i in range(0, n): + sum += (x[(i)]-mean_x)*(y[i]-mean_y) + return sum/n + +n = 10 + +x=np.random.normal(size=n) +y = 4+3*x+np.random.normal(size=n) +covxy = covariance(x,y,n) +print(covxy) +z = np.vstack((x, y)) +c = np.cov(z.T) + +print(c) + +!ec + + + + +===== Meet the covariance, uncorrelated events ===== +!bblock + +Consider the stochastic variables $X_i$ and $X_j$, ($i\neq j$). We have +!bt +\begin{align*} +Cov(X_i,\,X_j) &= \langle (x_i-\langle x_i\rangle)(x_j-\langle x_j\rangle)\rangle\\ +&=\langle x_i x_j - x_i\langle x_j\rangle - \langle x_i\rangle x_j + \langle x_i\rangle\langle x_j\rangle\rangle\\ +&=\langle x_i x_j\rangle - \langle x_i\langle x_j\rangle\rangle - \langle \langle x_i\rangle x_j \rangle + +\langle \langle x_i\rangle\langle x_j\rangle\rangle \\ +&=\langle x_i x_j\rangle - \langle x_i\rangle\langle x_j\rangle - \langle x_i\rangle\langle x_j\rangle + +\langle x_i\rangle\langle x_j\rangle \\ +&=\langle x_i x_j\rangle - \langle x_i\rangle\langle x_j\rangle +\end{align*} +!et +If $X_i$ and $X_j$ are independent (assuming $i \neq j$), we have that +!bt +\[ +\langle x_i x_j\rangle = \langle x_i\rangle\langle x_j\rangle, +\] +!et +leading to +!bt +\[ +Cov(X_i, X_j) = 0 \hspace{0.1cm} (i\neq j). +\] +!et +!eblock + + + + +===== Numerical experiments and the covariance ===== +!bblock + +Now that we have constructed an idealized mathematical framework, let +us try to apply it to empirical observations. Examples of relevant +physical phenomena may be spontaneous decays of nuclei, or a purely +mathematical set of numbers produced by some deterministic +mechanism. It is the latter we will deal with, using so-called pseudo-random +number generators. In general our observations will contain only a limited set of +observables. We remind the reader that +a *stochastic process* is a process that produces sequentially a +chain of values +!bt +\begin{equation*} +\{x_1, x_2,\dots\,x_k,\dots\}. +\end{equation*} +!et +!eblock + + + +===== Numerical experiments and the covariance ===== +!bblock +We will call these +values our *measurements* and the entire set as our measured +*sample*. The action of measuring all the elements of a sample +we will call a stochastic *experiment* (since, operationally, +they are often associated with results of empirical observation of +some physical or mathematical phenomena; precisely an experiment). We +assume that these values are distributed according to some +PDF $p_X^{\phantom X}(x)$, where $X$ is just the formal symbol for the +stochastic variable whose PDF is $p_X^{\phantom X}(x)$. Instead of +trying to determine the full distribution $p$ we are often only +interested in finding the few lowest moments, like the mean +$\mu_X^{\phantom X}$ and the variance $\sigma_X^{\phantom X}$. +!eblock + + + +===== Numerical experiments and the covariance, actual situations ===== +!bblock +In practical situations however, a sample is always of finite size. Let that +size be $n$. The expectation value of a sample $\alpha$, the _sample mean_, is then defined as follows +!bt +\begin{equation*} +\langle x_{\alpha} \rangle \equiv \frac{1}{n}\sum_{k=1}^n x_{\alpha,k}. +\end{equation*} +!et +The *sample variance* is: +!bt +\begin{equation*} +\mathrm{Var}(x) \equiv \frac{1}{n}\sum_{k=1}^n (x_{\alpha,k} - \langle x_{\alpha} \rangle)^2, +\end{equation*} +!et +with its square root being the *standard deviation of the sample*. +!eblock + + + +===== Numerical experiments and the covariance, our observables ===== +!bblock +You can think of the above observables as a set of quantities which define +a given experiment. This experiment is then repeated several times, say $m$ times. +The total average is then +!bt +\begin{equation} +\langle X_m \rangle= \frac{1}{m}\sum_{\alpha=1}^mx_{\alpha}=\frac{1}{mn}\sum_{\alpha, k} x_{\alpha,k}, +label{eq:exptmean} +\end{equation} +!et +where the last sums end at $m$ and $n$. +The total variance is +!bt +\begin{equation*} +\sigma^2_m= \frac{1}{mn^2}\sum_{\alpha=1}^m(\langle x_{\alpha} \rangle-\langle X_m \rangle)^2, +\end{equation*} +!et +which we rewrite as +!bt +\begin{equation} +\sigma^2_m=\frac{1}{m}\sum_{\alpha=1}^m\sum_{kl=1}^n (x_{\alpha,k}-\langle X_m \rangle)(x_{\alpha,l}-\langle X_m \rangle). +label{eq:exptvariance} +\end{equation} +!et +!eblock + + +===== Numerical experiments and the covariance, the sample variance ===== +!bblock + +We define also the sample variance $\sigma^2$ of all $mn$ individual experiments as +!bt +\begin{equation} +\sigma^2=\frac{1}{mn}\sum_{\alpha=1}^m\sum_{k=1}^n (x_{\alpha,k}-\langle X_m \rangle)^2. +label{eq:sampleexptvariance} +\end{equation} +!et + + + +These quantities, being known experimental values or the results from our calculations, +may differ, in some cases +significantly, from the similarly named +exact values for the mean value $\mu_X$, the variance $\mathrm{Var}(X)$ +and the covariance $\mathrm{Cov}(X,Y)$. +!eblock + + +===== Numerical experiments and the covariance, central limit theorem ===== +!bblock + +The central limit theorem states that the PDF $\tilde{p}(z)$ of +the average of $m$ random values corresponding to a PDF $p(x)$ +is a normal distribution whose mean is the +mean value of the PDF $p(x)$ and whose variance is the variance +of the PDF $p(x)$ divided by $m$, the number of values used to compute $z$. + +The central limit theorem leads then to the well-known expression for the +standard deviation, given by +!bt +\begin{equation*} + \sigma_m= +\frac{\sigma}{\sqrt{m}}. +\end{equation*} +!et + +In many cases the above estimate for the standard deviation, in particular if correlations are strong, may be too simplistic. We need therefore a more precise defintion of the error and the variance in our results. +!eblock + + +===== Definition of Correlation Functions and Standard Deviation ===== +!bblock +Our estimate of the true average $\mu_{X}$ is the sample mean $\langle X_m \rangle$ + +!bt +\begin{equation*} +\mu_{X}^{\phantom X} \approx X_m=\frac{1}{mn}\sum_{\alpha=1}^m\sum_{k=1}^n x_{\alpha,k}. +\end{equation*} +!et + + +We can then use Eq. (ref{eq:exptvariance}) +!bt +\begin{equation*} +\sigma^2_m=\frac{1}{mn^2}\sum_{\alpha=1}^m\sum_{kl=1}^n (x_{\alpha,k}-\langle X_m \rangle)(x_{\alpha,l}-\langle X_m \rangle), +\end{equation*} +!et +and rewrite it as +!bt +\begin{equation*} +\sigma^2_m=\frac{\sigma^2}{n}+\frac{2}{mn^2}\sum_{\alpha=1}^m\sum_{k +#include +#include +#include +using namespace std; +// output file as global variable +ofstream ofile; + +// Main function begins here +int main(int argc, char* argv[]) +{ + int n; + char *outfilename; + + cin >> n; + double MCint = 0.; double MCintsqr2=0.; + double invers_period = 1./RAND_MAX; // initialise the random number generator + srand(time(NULL)); // This produces the so-called seed in MC jargon + // Compute the variance and the mean value of the uniform distribution + // Compute also the specific values x for each cycle in order to be able to + // the covariance and the correlation function + // Read in output file, abort if there are too few command-line arguments + if( argc <= 2 ){ + cout << "Bad Usage: " << argv[0] << + " read also output file and number of cycles on same line" << endl; + exit(1); + } + else{ + outfilename=argv[1]; + } + ofile.open(outfilename); + // Get the number of Monte-Carlo samples + n = atoi(argv[2]); + double *X; + X = new double[n]; + for (int i = 0; i < n; i++){ + double x = double(rand())*invers_period; + X[i] = x; + MCint += x; + MCintsqr2 += x*x; + } + double Mean = MCint/((double) n ); + MCintsqr2 = MCintsqr2/((double) n ); + double STDev = sqrt(MCintsqr2-Mean*Mean); + double Variance = MCintsqr2-Mean*Mean; +// Write mean value and standard deviation + cout << " Standard deviation= " << STDev << " Integral = " << Mean << endl; + + // Now we compute the autocorrelation function + double *autocor; autocor = new double[n]; + for (int j = 0; j < n; j++){ + double sum = 0.0; + for (int k = 0; k < (n-j); k++){ + sum += (X[k]-Mean)*(X[k+j]-Mean); + } + autocor[j] = sum/Variance/((double) n ); + ofile << setiosflags(ios::showpoint | ios::uppercase); + ofile << setw(15) << setprecision(8) << j; + ofile << setw(15) << setprecision(8) << autocor[j] << endl; + } + ofile.close(); // close output file + return 0; +} // end of main program +!ec +!eblock + + + + +======= Which RNG should I use? ======= +!bblock +* C++ has a class called _random_. The "random class":"http://www.cplusplus.com/reference/random/" contains a large selection of RNGs and is highly recommended. Some of these RNGs have very large periods making it thereby very safe to use these RNGs in case one is performing large calculations. In particular, the "Mersenne twister random number engine":"http://www.cplusplus.com/reference/random/mersenne_twister_engine/" has a period of $2^{19937}$. +* Add RNGs in Python + +!eblock + + + +===== How to use the Mersenne generator ===== +!bblock +The following part of a c++ code (from project 4) sets up the uniform distribution for $x\in [0,1]$. +!bc cppcod +/* + +// You need this +#include + +// Initialize the seed and call the Mersienne algo +std::random_device rd; +std::mt19937_64 gen(rd()); +// Set up the uniform distribution for x \in [[0, 1] +std::uniform_real_distribution RandomNumberGenerator(0.0,1.0); + +// Now use the RNG +int ix = (int) (RandomNumberGenerator(gen)*NSpins); +!ec +!eblock + + + + + +===== Why blocking? ===== +!bblock Statistical analysis + * Monte Carlo simulations can be treated as *computer experiments* + * The results can be analysed with the same statistical tools as we would use analysing experimental data. + * As in all experiments, we are looking for expectation values and an estimate of how accurate they are, i.e., possible sources for errors. + +A very good article which explains blocking is H. Flyvbjerg and H. G. Petersen, *Error estimates on averages of correlated data*, "Journal of Chemical Physics 91, 461-466 (1989)":"http://scitation.aip.org/content/aip/journal/jcp/91/1/10.1063/1.457480". + +!eblock + + + + +===== Why blocking? ===== +!bblock Statistical analysis + * As in other experiments, Monte Carlo experiments have two classes of errors: + * Statistical errors + * Systematical errors + * Statistical errors can be estimated using standard tools from statistics + * Systematical errors are method specific and must be treated differently from case to case. (In VMC a common source is the step length or time step in importance sampling) +!eblock + + + +===== Code to demonstrate the calculation of the autocorrelation function ===== +The following code computes the autocorrelation function, the covariance and the standard deviation +for standard RNG. +The "following file":"https://github.com/CompPhysics/ComputationalPhysics2/tree/gh-pages/doc/Programs/LecturePrograms/programs/Blocking/autocorrelation.cpp" gives the code. +!bc cppcod +// This function computes the autocorrelation function for +// the Mersenne random number generator with a uniform distribution +#include +#include +#include +#include +#include +#include +#include +#include +using namespace std; +using namespace arma; +// output file +ofstream ofile; + +// Main function begins here +int main(int argc, char* argv[]) +{ + int MonteCarloCycles; + string filename; + if (argc > 1) { + filename=argv[1]; + MonteCarloCycles = atoi(argv[2]); + string fileout = filename; + string argument = to_string(MonteCarloCycles); + fileout.append(argument); + ofile.open(fileout); + } + + // Compute the variance and the mean value of the uniform distribution + // Compute also the specific values x for each cycle in order to be able to + // compute the covariance and the correlation function + + vec X = zeros(MonteCarloCycles); + double MCint = 0.; double MCintsqr2=0.; + std::random_device rd; + std::mt19937_64 gen(rd()); + // Set up the uniform distribution for x \in [[0, 1] + std::uniform_real_distribution RandomNumberGenerator(0.0,1.0); + for (int i = 0; i < MonteCarloCycles; i++){ + double x = RandomNumberGenerator(gen); + X(i) = x; + MCint += x; + MCintsqr2 += x*x; + } + double Mean = MCint/((double) MonteCarloCycles ); + MCintsqr2 = MCintsqr2/((double) MonteCarloCycles ); + double STDev = sqrt(MCintsqr2-Mean*Mean); + double Variance = MCintsqr2-Mean*Mean; + // Write mean value and variance + cout << " Sample variance= " << Variance << " Mean value = " << Mean << endl; + // Now we compute the autocorrelation function + vec autocorrelation = zeros(MonteCarloCycles); + for (int j = 0; j < MonteCarloCycles; j++){ + double sum = 0.0; + for (int k = 0; k < (MonteCarloCycles-j); k++){ + sum += (X(k)-Mean)*(X(k+j)-Mean); + } + autocorrelation(j) = sum/Variance/((double) MonteCarloCycles ); + ofile << setiosflags(ios::showpoint | ios::uppercase); + ofile << setw(15) << setprecision(8) << j; + ofile << setw(15) << setprecision(8) << autocorrelation(j) << endl; + } + // Now compute the exact covariance using the autocorrelation function + double Covariance = 0.0; + for (int j = 0; j < MonteCarloCycles; j++){ + Covariance += autocorrelation(j); + } + Covariance *= 2.0/((double) MonteCarloCycles); + // Compute now the total variance, including the covariance, and obtain the standard deviation + double TotalVariance = (Variance/((double) MonteCarloCycles ))+Covariance; + cout << "Covariance =" << Covariance << "Totalvariance= " << TotalVariance << "Sample Variance/n= " << (Variance/((double) MonteCarloCycles )) << endl; + cout << " STD from sample variance= " << sqrt(Variance/((double) MonteCarloCycles )) << " STD with covariance = " << sqrt(TotalVariance) << endl; + + ofile.close(); // close output file + return 0; +} // end of main program + + +!ec + + + +===== What is blocking? ===== +!bblock Blocking + * Say that we have a set of samples from a Monte Carlo experiment + * Assuming (wrongly) that our samples are uncorrelated our best estimate of the standard deviation of the mean $\langle \mathbf{M}\rangle$ is given by +!bt +\[ +\sigma=\sqrt{\frac{1}{n}\left(\langle \mathbf{M}^2\rangle-\langle \mathbf{M}\rangle^2\right)} +\] +!et + * If the samples are correlated we can rewrite our results to show that +!bt +\[ +\sigma=\sqrt{\frac{1+2\tau/\Delta t}{n}\left(\langle \mathbf{M}^2\rangle-\langle \mathbf{M}\rangle^2\right)} +\] +!et + where $\tau$ is the correlation time (the time between a sample and the next uncorrelated sample) and $\Delta t$ is time between each sample +!eblock + + +===== What is blocking? ===== +!bblock Blocking + * If $\Delta t\gg\tau$ our first estimate of $\sigma$ still holds + * Much more common that $\Delta t<\tau$ + * In the method of data blocking we divide the sequence of samples into blocks + * We then take the mean $\langle \mathbf{M}_i\rangle$ of block $i=1\ldots n_{blocks}$ to calculate the total mean and variance + * The size of each block must be so large that sample $j$ of block $i$ is not correlated with sample $j$ of block $i+1$ + * The correlation time $\tau$ would be a good choice +!eblock + + +===== What is blocking? ===== +!bblock Blocking + * Problem: We don't know $\tau$ or it is too expensive to compute + * Solution: Make a plot of std. dev. as a function of blocksize + * The estimate of std. dev. of correlated data is too low $\to$ the error will increase with increasing block size until the blocks are uncorrelated, where we reach a plateau + * When the std. dev. stops increasing the blocks are uncorrelated +!eblock + + +===== Implementation ===== +!bblock + * Do a Monte Carlo simulation, storing all samples to file + * Do the statistical analysis on this file, independently of your Monte Carlo program + * Read the file into an array + * Loop over various block sizes + * For each block size $n_b$, loop over the array in steps of $n_b$ taking the mean of elements $i n_b,\ldots,(i+1) n_b$ + * Take the mean and variance of the resulting array + * Write the results for each block size to file for later + analysis +!eblock + + + + + + +===== Actual implementation with code, main function ===== +When the file gets large, it can be useful to write your data in binary mode instead of ascii characters. +The "following python file":"https://github.com/CompPhysics/MachineLearning/blob/master/doc/Programs/Sampling/analysis.py" reads data from file with the output from every Monte Carlo cycle. +!bc pycod +# Blocking + @timeFunction + def blocking(self, blockSizeMax = 500): + blockSizeMin = 1 + + self.blockSizes = [] + self.meanVec = [] + self.varVec = [] + + for i in range(blockSizeMin, blockSizeMax): + if(len(self.data) % i != 0): + pass#continue + blockSize = i + meanTempVec = [] + varTempVec = [] + startPoint = 0 + endPoint = blockSize + + while endPoint <= len(self.data): + meanTempVec.append(np.average(self.data[startPoint:endPoint])) + startPoint = endPoint + endPoint += blockSize + mean, var = np.average(meanTempVec), np.var(meanTempVec)/len(meanTempVec) + self.meanVec.append(mean) + self.varVec.append(var) + self.blockSizes.append(blockSize) + + self.blockingAvg = np.average(self.meanVec[-200:]) + self.blockingVar = (np.average(self.varVec[-200:])) + self.blockingStd = np.sqrt(self.blockingVar) + +!ec + + + + + +===== The Bootstrap method ===== + +The Bootstrap resampling method is also very popular. It is very simple: + +o Start with your sample of measurements and compute the sample variance and the mean values +o Then start again but pick in a random way the numbers in the sample and recalculate the mean and the sample variance. +o Repeat this $K$ times. + +It can be shown, see the article by "Efron":"https://projecteuclid.org/download/pdf_1/euclid.aos/1176344552" +that it produces the correct standard deviation. + +This method is very useful for small ensembles of data points. + + +===== Bootstrapping ===== +Given a set of $N$ data, assume that we are interested in some +observable $\theta$ which may be estimated from that set. This observable can also be for example the result of a fit based on all $N$ raw data. +Let us call the value of the observable obtained from the original +data set $\hat{\theta}$. One recreates from the sample repeatedly +other samples by choosing randomly $N$ data out of the original set. +This costs essentially nothing, since we just recycle the original data set for the building of new sets. + + +===== Bootstrapping, recipe ===== +Let us assume we have done this $K$ times and thus have $K$ sets of $N$ +data values each. +Of course some values will enter more than once in the new sets. For each of these sets one computes the observable $\theta$ resulting in values $\theta_k$ with $k = 1,...,K$. Then one determines +!bt +\[ +\tilde{\theta} = \frac{1}{K} \sum_{k=1}^K \theta_k, +\] +!et +and +!bt +\[ +sigma^2_{\tilde{\theta}} = \frac{1}{K} \sum_{k=1}^K \left(\theta_k-\tilde{\theta}\right)^2. +\] +!et + +These are estimators for $\angle\theta\rangle$ and its variance. They are not unbiased and therefore +$\tilde{\theta}\neq\hat{\theta}$ for finite K. + +The difference is called bias and gives an idea on how far away the result may be from +the true $\angle\theta\rangle$. As final result for the observable one quotes $\angle\theta\rangle = \tilde{\theta} \pm \sigma_{\tilde{\theta}}$ . + + + +===== Bootstrapping, "code":"https://github.com/CompPhysics/MachineLearning/blob/master/doc/Programs/Sampling/analysis.py" ===== +!bc +# Bootstrap + @timeFunction + def bootstrap(self, nBoots = 1000): + bootVec = np.zeros(nBoots) + for k in range(0,nBoots): + bootVec[k] = np.average(np.random.choice(self.data, len(self.data))) + self.bootAvg = np.average(bootVec) + self.bootVar = np.var(bootVec) + self.bootStd = np.std(bootVec) +!ec + + +===== Jackknife, "code":"https://github.com/CompPhysics/MachineLearning/blob/master/doc/Programs/Sampling/analysis.py" ===== +!bc +# Jackknife + @timeFunction + def jackknife(self): + jackknVec = np.zeros(len(self.data)) + for k in range(0,len(self.data)): + jackknVec[k] = np.average(np.delete(self.data, k)) + self.jackknAvg = self.avg - (len(self.data) - 1) * (np.average(jackknVec) - self.avg) + self.jackknVar = float(len(self.data) - 1) * np.var(jackknVec) + self.jackknStd = np.sqrt(self.jackknVar) +!ec + + + + + diff --git a/doc/LectureNotes/book.do.txt~ b/doc/LectureNotes/book.do.txt~ deleted file mode 100644 index b7565e3cd..000000000 --- a/doc/LectureNotes/book.do.txt~ +++ /dev/null @@ -1,6786 +0,0 @@ -TITLE: Data Analysis and Machine Learning -AUTHOR: Morten Hjorth-Jensen {copyright, 1999-present|CC BY-NC} at Department of Physics, University of Oslo & Department of Physics and Astronomy and National Superconducting Cyclotron Laboratory, Michigan State University -DATE: today - -TOC: on - - -======= Introduction ======= - -During the last two decades there has been a swift and amazing -development of Machine Learning techniques and algorithms that impact -many areas in not only Science and Technology but also the Humanities, -Social Sciences, Medicine, Law, indeed, almost all possible -disciplines. The applications are incredibly many, from self-driving -cars to solving high-dimensional differential equations or complicated -quantum mechanical many-body problems. Machine Learning is perceived -by many as one of the main disruptive techniques nowadays. - -Statistics, Data science and Machine Learning form important -fields of research in modern science. They describe how to learn and -make predictions from data, as well as allowing us to extract -important correlations about physical process and the underlying laws -of motion in large data sets. The latter, big data sets, appear -frequently in essentially all disciplines, from the traditional -Science, Technology, Mathematics and Engineering fields to Life -Science, Law, education research, the Humanities and the Social -Sciences. - -It has become more -and more common to see research projects on big data in for example -the Social Sciences where extracting patterns from complicated survey -data is one of many research directions. Having a solid grasp of data -analysis and machine learning is thus becoming central to scientific -computing in many fields, and competences and skills within the fields -of machine learning and scientific computing are nowadays strongly -requested by many potential employers. The latter cannot be -overstated, familiarity with machine learning has almost become a -prerequisite for many of the most exciting employment opportunities, -whether they are in bioinformatics, life science, physics or finance, -in the private or the public sector. This author has had several -students or met students who have been hired recently based on their -skills and competences in scientific computing and data science, often -with marginal knowledge of machine learning. - -Machine learning is a subfield of computer science, and is closely -related to computational statistics. It evolved from the study of -pattern recognition in artificial intelligence (AI) research, and has -made contributions to AI tasks like computer vision, natural language -processing and speech recognition. Many of the methods we will study are also -strongly rooted in basic mathematics and physics research. - -Ideally, machine learning represents the science of giving computers -the ability to learn without being explicitly programmed. The idea is -that there exist generic algorithms which can be used to find patterns -in a broad class of data sets without having to write code -specifically for each problem. The algorithm will build its own logic -based on the data. You should however always keep in mind that -machines and algorithms are to a large extent developed by humans. The -insights and knowledge we have about a specific system, play a central -role when we develop a specific machine learning algorithm. - -Machine learning is an extremely rich field, in spite of its young -age. The increases we have seen during the last three decades in -computational capabilities have been followed by developments of -methods and techniques for analyzing and handling large date sets, -relying heavily on statistics, computer science and mathematics. The -field is rather new and developing rapidly. Popular software packages -written in Python for machine learning like -"Scikit-learn":"http://scikit-learn.org/stable/", -"Tensorflow":"https://www.tensorflow.org/", -"PyTorch":"http://pytorch.org/" and "Keras":"https://keras.io/", all -freely available at their respective GitHub sites, encompass -communities of developers in the thousands or more. And the number of -code developers and contributors keeps increasing. Not all the -algorithms and methods can be given a rigorous mathematical -justification, opening up thereby large rooms for experimenting and -trial and error and thereby exciting new developments. However, a -solid command of linear algebra, multivariate theory, probability -theory, statistical data analysis, understanding errors and Monte -Carlo methods are central elements in a proper understanding of many -of algorithms and methods we will discuss. - - - -===== Learning outcomes ===== - -These sets of lectures aim at giving you an overview of central aspects of -statistical data analysis as well as some of the central algorithms -used in machine learning. We will introduce a variety of central -algorithms and methods essential for studies of data analysis and -machine learning. - -Hands-on projects and experimenting with data and algorithms plays a central role in -these lectures, and our hope is, through the various -projects and exercises, to expose you to fundamental -research problems in these fields, with the aim to reproduce state of -the art scientific results. You will learn to develop and -structure codes for studying these systems, get acquainted with -computing facilities and learn to handle large scientific projects. A -good scientific and ethical conduct is emphasized throughout the -course. More specifically, you will - -o Learn about basic data analysis, Bayesian statistics, Monte Carlo methods, data optimization and machine learning; -o Be capable of extending the acquired knowledge to other systems and cases; -o Have an understanding of central algorithms used in data analysis and machine learning; -o Gain knowledge of central aspects of Monte Carlo methods, Markov chains, Gibbs samplers and their possible applications, from numerical integration to simulation of stock markets; -o Understand methods for regression and classification; -o Learn about neural network, genetic algorithms and Boltzmann machines; -o Work on numerical projects to illustrate the theory. The projects play a central role and you are expected to know modern programming languages like Python or C++, in addition to a basic knowledge of linear algebra (typically taught during the first one or two years of undergraduate studies). - -There are several topics we will cover here, spanning from -statistical data analysis and its basic concepts such as expectation -values, variance, covariance, correlation functions and errors, via -well-known probability distribution functions like the uniform -distribution, the binomial distribution, the Poisson distribution and -simple and multivariate normal distributions to central elements of -Bayesian statistics and modeling. We will also remind the reader about -central elements from linear algebra and standard methods based on -linear algebra used to optimize (minimize) functions (the family of gradient descent methods) -and the Singular-value decomposition and -least square methods for parameterizing data. - -We will also cover Monte Carlo methods, Markov chains, well-known -algorithms for sampling stochastic events like the Metropolis-Hastings -and Gibbs sampling methods. An important aspect of all our -calculations is a proper estimation of errors. Here we will also -discuss famous resampling techniques like the blocking, the bootstrapping -and the jackknife methods and the infamous bias-variance tradeoff. - -The second part of the material covers several algorithms used in -machine learning. - - - - - - -===== Types of Machine Learning ===== - - -The approaches to machine learning are many, but are often split into -two main categories. In *supervised learning* we know the answer to a -problem, and let the computer deduce the logic behind it. On the other -hand, *unsupervised learning* is a method for finding patterns and -relationship in data sets without any prior knowledge of the system. -Some authours also operate with a third category, namely -*reinforcement learning*. This is a paradigm of learning inspired by -behavioral psychology, where learning is achieved by trial-and-error, -solely from rewards and punishment. - -Another way to categorize machine learning tasks is to consider the -desired output of a system. Some of the most common tasks are: - - * Classification: Outputs are divided into two or more classes. The goal is to produce a model that assigns inputs into one of these classes. An example is to identify digits based on pictures of hand-written ones. Classification is typically supervised learning. - - * Regression: Finding a functional relationship between an input data set and a reference data set. The goal is to construct a function that maps input data to continuous output values. - - * Clustering: Data are divided into groups with certain common traits, without knowing the different groups beforehand. It is thus a form of unsupervised learning. - - -The methods we cover have three main topics in common, irrespective of -whether we deal with supervised or unsupervised learning. The first -ingredient is normally our data set (which can be subdivided into -training and test data), the second item is a model which is normally -a function of some parameters. The model reflects our knowledge of -the system (or lack thereof). As an example, if we know that our data -show a behavior similar to what would be predicted by a polynomial, -fitting our data to a polynomial of some degree would then determin -our model. - -The last ingredient is a so-called _cost_ -function which allows us to present an estimate on how good our model -is in reproducing the data it is supposed to train. - -Here we will build our machine learning approach on elements of the -statistical foundation discussed above, with elements from data -analysis, stochastic processes etc. We will discuss the following -machine learning algorithms - -o Linear regression and its variants -o Decision tree algorithms, from single trees to random forests -o Bayesian statistics and regression -o Support vector machines and finally various variants of -o Artifical neural networks and deep learning, including convolutional neural networks and Bayesian neural networks -o Networks for unsupervised learning using for example reduced Boltzmann machines. - - - -===== Choice of programming language ===== - -Python plays nowadays a central role in the development of machine -learning techniques and tools for data analysis. In particular, seen -the wealth of machine learning and data analysis libraries written in -Python, easy to use libraries with immediate visualization(and not the -least impressive galleries of existing examples), the popularity of the -Jupyter notebook framework with the possibility to run _R_ codes or -compiled programs written in C++, and much more made our choice of -programming language for this series of lectures easy. However, -since the focus here is not only on using existing Python libraries such -as _Scikit-Learn_ or _Tensorflow_, but also on developing your own -algorithms and codes, we will as far as possible present many of these -algorithms either as a Python codes or C++ or Fortran (or other languages) codes. - -The reason we also focus on compiled languages like C++ (or -Fortran), is that Python is still notoriously slow when we do not -utilize highly streamlined computational libraries like -"Lapack":"http://www.netlib.org/lapack/" or other numerical libraries -written in compiled languages (many of these libraries are written in -Fortran). Although a project like "Numba":"https://numba.pydata.org/" -holds great promise for speeding up the unrolling of lengthy loops, C++ -and Fortran are presently still the performance winners. Numba gives -you potentially the power to speed up your applications with high -performance functions written directly in Python. In particular, -array-oriented and math-heavy Python code can achieve similar -performance to C, C++ and Fortran. However, even with these speed-ups, -for codes involving heavy Markov Chain Monte Carlo analyses and -optimizations of cost functions, C++/C or Fortran codes tend to -outperform Python codes. - -Presently thus, the community tends to let -code written in C++/C or Fortran do the heavy duty numerical -number crunching and leave the post-analysis of the data to the above -mentioned Python modules or software packages. However, with the developments taking place in for example the Python community, and seen -the changes during the last decade, the above situation may change swiftly in the not too distant future. - -Many of the examples we discuss in this series of lectures come with -existing data files or provide code examples which produce the data to -be analyzed. Most of the applications we will discuss deal with -small data sets (less than a terabyte of information) and can easily -be analyzed and tested on standard off the shelf laptops you find in general -stores. - -===== Data handling, machine learning and ethical aspects ===== - -In most of the cases we will study, we will either generate the data -to analyze ourselves (both for supervised learning and unsupervised -learning) or we will recur again and again to data present in say -_Scikit-Learn_ or _Tensorflow_. Many of the examples we end up -dealing with are from a privacy and data protection point of view, -rather inoccuous and boring results of numerical -calculations. However, this does not hinder us from developing a sound -ethical attitude to the data we use, how we analyze the data and how -we handle the data. - -The most immediate and simplest possible ethical aspects deal with our -approach to the scientific process. Nowadays, with version control -software like "Git":"https://git-scm.com/" and various online -repositories like "Github":"https://github.com/", -"Gitlab":"https://about.gitlab.com/" etc, we can easily make our codes -and data sets we have used, freely and easily accessible to a wider -community. This helps us almost automagically in making our science -reproducible. The large open-source development communities involved -in say "Scikit-Learn":"http://scikit-learn.org/stable/", -"Tensorflow":"https://www.tensorflow.org/", -"PyTorch":"http://pytorch.org/" and "Keras":"https://keras.io/", are -all excellent examples of this. The codes can be tested and improved -upon continuosly, helping thereby our scientific community at large in -developing data analysis and machine learning tools. It is much -easier today to gain traction and acceptance for making your science -reproducible. From a societal stand, this is an important element -since many of the developers are employees of large public institutions like -universities and research labs. Our fellow taxpayers do deserve to get -something back for their bucks. - -However, this more mechanical aspect of the ethics of science (in -particular the reproducibility of scientific results) is something -which is obvious and everybody should do so as part of the dialectics of -science. The fact that many scientists are not willing to share their codes or -data is detrimental to the scientific discourse. - -Before we proceed, we should add a disclaimer. Even though -we may dream of computers developing some kind of higher learning -capabilities, at the end (even if the artificial intelligence -community keeps touting our ears full of fancy futuristic avenues), it is we, yes you reading these lines, -who end up constructing and instructing, via various algorithms, the -machine learning approaches. Self-driving cars for example, rely on sofisticated -programs which take into account all possible situations a car can -encounter. In addition, extensive usage of training data from GPS -information, maps etc, are typically fed into the software for -self-driving cars. Adding to this various sensors and cameras that -feed information to the programs, there are zillions of ethical issues -which arise from this. - -For self-driving cars, where basically many of the standard machine -learning algorithms discussed here enter into the codes, at a certain -stage we have to make choices. Yes, we , the lads and lasses who wrote -a program for a specific brand of a self-driving car. As an example, -all carmakers have as their utmost priority the security of the -driver and the accompanying passengers. A famous European carmaker, which is -one of the leaders in the market of self-driving cars, had _if_ -statements of the following type: suppose there are two obstacles in -front of you and you cannot avoid to collide with one of them. One of -the obstacles is a monstertruck while the other one is a kindergarten -class trying to cross the road. The self-driving car algo would then -opt for the hitting the small folks instead of the monstertruck, since -the likelihood of surving a collision with our future citizens, is -much higher. - -This leads to serious ethical aspects. Why should we -opt for such an option? Who decides and who is entitled to make such -choices? Keep in mind that many of the algorithms you will encounter in -this series of lectures or hear about later, are indeed based on -simple programming instructions. And you are very likely to be one of -the people who may end up writing such a code. Thus, developing a -sound ethical attitude to what we do, an approach well beyond the -simple mechanistic one of making our science available and -reproducible, is much needed. The example of the self-driving cars is -just one of infinitely many cases where we have to make choices. When -you analyze data on economic inequalities, who guarantees that you are -not weighting some data in a particular way, perhaps because you dearly want a -specific conclusion which may support your political views? - -We do not have the answers here, nor will we venture into a deeper -discussions of these aspects, but we want you think over these topics -in a more overarching way. A statistical data analysis with its dry -numbers and graphs meant to guide the eye, does not necessarily -reflect the truth, whatever that is. As a scientist, and after a -university education, you are supposedly a better citizen, with an -improved critical view and understanding of the scientific method, and -perhaps some deeper understanding of the ethics of science at -large. Use these insights. Be a critical citizen. You owe it to our -society. - - - - -======= Getting started with Machine Learning ======= - -Our emphasis throughout this series of lectures -is on understanding the mathematical aspects of -different algorithms used in the fields of data analysis and machine learning. - -However, where possible we will emphasize the -importance of using available software. We start thus with a hands-on -and top-down approach to machine learning. The aim is thus to start with -relevant data or data we have produced -and use these to introduce statistical data analysis -concepts and machine learning algorithms before we delve into the -algorithms themselves. The examples we will use in the beginning, start with simple -polynomials with random noise added. We will use the Python -software package "Scikit-Learn":"http://scikit-learn.org/stable/" and -introduce various machine learning algorithms to make fits of -the data and predictions. We move thereafter to more interesting -cases such as data from say experiments (below we will look at experimental nuclear binding energies as an example). -These are examples where we can easily set up the data and -then use machine learning algorithms included in for example -_Scikit-Learn_. - -These examples will serve us the purpose of getting -started. Furthermore, they allow us to catch more than two birds with -a stone. They will allow us to bring in some programming specific -topics and tools as well as showing the power of various Python -libraries for machine learning and statistical data analysis. - -Here, we will mainly focus on two -specific Python packages for Machine Learning, Scikit-Learn and -Tensorflow (see below for links etc). Moreover, the examples we -introduce will serve as inputs to many of our discussions later, as -well as allowing you to set up models and produce your own data and -get started with programming. - - - -===== What is Machine Learning? ===== - -Statistics, data science and machine learning form important fields of -research in modern science. They describe how to learn and make -predictions from data, as well as allowing us to extract important -correlations about physical process and the underlying laws of motion -in large data sets. The latter, big data sets, appear frequently in -essentially all disciplines, from the traditional Science, Technology, -Mathematics and Engineering fields to Life Science, Law, education -research, the Humanities and the Social Sciences. - -It has become more -and more common to see research projects on big data in for example -the Social Sciences where extracting patterns from complicated survey -data is one of many research directions. Having a solid grasp of data -analysis and machine learning is thus becoming central to scientific -computing in many fields, and competences and skills within the fields -of machine learning and scientific computing are nowadays strongly -requested by many potential employers. The latter cannot be -overstated, familiarity with machine learning has almost become a -prerequisite for many of the most exciting employment opportunities, -whether they are in bioinformatics, life science, physics or finance, -in the private or the public sector. This author has had several -students or met students who have been hired recently based on their -skills and competences in scientific computing and data science, often -with marginal knowledge of machine learning. - -Machine learning is a subfield of computer science, and is closely -related to computational statistics. It evolved from the study of -pattern recognition in artificial intelligence (AI) research, and has -made contributions to AI tasks like computer vision, natural language -processing and speech recognition. Many of the methods we will study are also -strongly rooted in basic mathematics and physics research. - -Ideally, machine learning represents the science of giving computers -the ability to learn without being explicitly programmed. The idea is -that there exist generic algorithms which can be used to find patterns -in a broad class of data sets without having to write code -specifically for each problem. The algorithm will build its own logic -based on the data. You should however always keep in mind that -machines and algorithms are to a large extent developed by humans. The -insights and knowledge we have about a specific system, play a central -role when we develop a specific machine learning algorithm. - -Machine learning is an extremely rich field, in spite of its young -age. The increases we have seen during the last three decades in -computational capabilities have been followed by developments of -methods and techniques for analyzing and handling large date sets, -relying heavily on statistics, computer science and mathematics. The -field is rather new and developing rapidly. Popular software packages -written in Python for machine learning like -"Scikit-learn":"http://scikit-learn.org/stable/", -"Tensorflow":"https://www.tensorflow.org/", -"PyTorch":"http://pytorch.org/" and "Keras":"https://keras.io/", all -freely available at their respective GitHub sites, encompass -communities of developers in the thousands or more. And the number of -code developers and contributors keeps increasing. Not all the -algorithms and methods can be given a rigorous mathematical -justification, opening up thereby large rooms for experimenting and -trial and error and thereby exciting new developments. However, a -solid command of linear algebra, multivariate theory, probability -theory, statistical data analysis, understanding errors and Monte -Carlo methods are central elements in a proper understanding of many -of algorithms and methods we will discuss. - - - -===== Types of Machine Learning ===== - - -The approaches to machine learning are many, but are often split into -two main categories. In *supervised learning* we know the answer to a -problem, and let the computer deduce the logic behind it. On the other -hand, *unsupervised learning* is a method for finding patterns and -relationship in data sets without any prior knowledge of the system. -Some authours also operate with a third category, namely -*reinforcement learning*. This is a paradigm of learning inspired by -behavioral psychology, where learning is achieved by trial-and-error, -solely from rewards and punishment. - -Another way to categorize machine learning tasks is to consider the -desired output of a system. Some of the most common tasks are: - - * Classification: Outputs are divided into two or more classes. The goal is to produce a model that assigns inputs into one of these classes. An example is to identify digits based on pictures of hand-written ones. Classification is typically supervised learning. - - * Regression: Finding a functional relationship between an input data set and a reference data set. The goal is to construct a function that maps input data to continuous output values. - - * Clustering: Data are divided into groups with certain common traits, without knowing the different groups beforehand. It is thus a form of unsupervised learning. - - -The methods we cover have three main topics in common, irrespective of -whether we deal with supervised or unsupervised learning. The first -ingredient is normally our data set (which can be subdivided into -training and test data), the second item is a model which is normally a -function of some parameters. The model reflects our knowledge of the system (or lack thereof). As an example, if we know that our data show a behavior similar to what would be predicted by a polynomial, fitting our data to a polynomial of some degree would then determin our model. - -The last ingredient is a so-called _cost_ -function which allows us to present an estimate on how good our model -is in reproducing the data it is supposed to train. -At the heart of basically all ML algorithms there are so-called minimization algorithms, often we end up with various variants of _gradient_ methods. - - - - - - - -===== Software and needed installations ===== - -We will make extensive use of Python as programming language and its -myriad of available libraries. You will find -Jupyter notebooks invaluable in your work. You can run _R_ -codes in the Jupyter/IPython notebooks, with the immediate benefit of -visualizing your data. You can also use compiled languages like C++, -Rust, Julia, Fortran etc if you prefer. The focus in these lectures will be -on Python. - - -If you have Python installed (we strongly recommend Python3) and you feel -pretty familiar with installing different packages, we recommend that -you install the following Python packages via _pip_ as - -o pip install numpy scipy matplotlib ipython scikit-learn mglearn sympy pandas pillow - -For Python3, replace _pip_ with _pip3_. - -For OSX users we recommend, after having installed Xcode, to -install _brew_. Brew allows for a seamless installation of additional -software via for example - -o brew install python3 - -For Linux users, with its variety of distributions like for example the widely popular Ubuntu distribution, -you can use _pip_ as well and simply install Python as - -o sudo apt-get install python3 (or python for pyhton2.7) - -etc etc. - - - -===== Python installers ===== - -If you don't want to perform these operations separately and venture -into the hassle of exploring how to set up dependencies and paths, we -recommend two widely used distrubutions which set up all relevant -dependencies for Python, namely - -* "Anaconda":"https://docs.anaconda.com/", - -which is an open source -distribution of the Python and R programming languages for large-scale -data processing, predictive analytics, and scientific computing, that -aims to simplify package management and deployment. Package versions -are managed by the package management system _conda_. - -* "Enthought canopy":"https://www.enthought.com/product/canopy/" - -is a Python -distribution for scientific and analytic computing distribution and -analysis environment, available for free and under a commercial -license. - -Furthermore, "Google's Colab":"https://colab.research.google.com/notebooks/welcome.ipynb" is a free Jupyter notebook environment that requires -no setup and runs entirely in the cloud. Try it out! - -===== Useful Python libraries ===== -Here we list several useful Python libraries we strongly recommend (if you use anaconda many of these are already there) - -* "NumPy":"https://www.numpy.org/" is a highly popular library for large, multi-dimensional arrays and matrices, along with a large collection of high-level mathematical functions to operate on these arrays -* "The pandas":"https://pandas.pydata.org/" library provides high-performance, easy-to-use data structures and data analysis tools -* "Xarray":"http://xarray.pydata.org/en/stable/" is a Python package that makes working with labelled multi-dimensional arrays simple, efficient, and fun! -* "Scipy":"https://www.scipy.org/" (pronounced “Sigh Pie”) is a Python-based ecosystem of open-source software for mathematics, science, and engineering. -* "Matplotlib":"https://matplotlib.org/" is a Python 2D plotting library which produces publication quality figures in a variety of hardcopy formats and interactive environments across platforms. -* "Autograd":"https://github.com/HIPS/autograd" can automatically differentiate native Python and Numpy code. It can handle a large subset of Python's features, including loops, ifs, recursion and closures, and it can even take derivatives of derivatives of derivatives -* "SymPy":"https://www.sympy.org/en/index.html" is a Python library for symbolic mathematics. -* "scikit-learn":"https://scikit-learn.org/stable/" has simple and efficient tools for machine learning, data mining and data analysis -* "TensorFlow":"https://www.tensorflow.org/" is a Python library for fast numerical computing created and released by Google -* "Keras":"https://keras.io/" is a high-level neural networks API, written in Python and capable of running on top of TensorFlow, CNTK, or Theano -* And many more such as "pytorch":"https://pytorch.org/", "Theano":"https://pypi.org/project/Theano/" etc - -===== Installing R, C++, cython or Julia ===== - -You will also find it convenient to utilize _R_. We will mainly -use Python during our lectures and in various projects and exercises. -Those of you -already familiar with _R_ should feel free to continue using _R_, keeping -however an eye on the parallel Python set ups. Similarly, if you are a -Python afecionado, feel free to explore _R_ as well. Jupyter/Ipython -notebook allows you to run _R_ codes interactively in your -browser. The software library _R_ is really tailored for statistical data analysis -and allows for an easy usage of the tools and algorithms we will discuss in these -lectures. - -To install _R_ with Jupyter notebook -"follow the link here":"https://mpacer.org/maths/r-kernel-for-ipython-notebook" - - - - -===== Installing R, C++, cython, Numba etc ===== - - -For the C++ aficionados, Jupyter/IPython notebook allows you also to -install C++ and run codes written in this language interactively in -the browser. Since we will emphasize writing many of the algorithms -yourself, you can thus opt for either Python or C++ (or Fortran or other compiled languages) as programming -languages. - -To add more entropy, _cython_ can also be used when running your -notebooks. It means that Python with the jupyter notebook -setup allows you to integrate widely popular softwares and tools for -scientific computing. Similarly, the -"Numba Python package":"https://numba.pydata.org/" delivers increased performance -capabilities with minimal rewrites of your codes. With its -versatility, including symbolic operations, Python offers a unique -computational environment. Your jupyter notebook can easily be -converted into a nicely rendered _PDF_ file or a Latex file for -further processing. For example, convert to latex as - -!bc -pycod jupyter nbconvert filename.ipynb --to latex -!ec - -And to add more versatility, the Python package "SymPy":"http://www.sympy.org/en/index.html" is a Python library for symbolic mathematics. It aims to become a full-featured computer algebra system (CAS) and is entirely written in Python. - -Finally, if you wish to use the light mark-up language -"doconce":"https://github.com/hplgit/doconce" you can convert a standard ascii text file into various HTML -formats, ipython notebooks, latex files, pdf files etc with minimal edits. These lectures were generated using _doconce_. - - - -===== Numpy examples and Important Matrix and vector handling packages ===== - -There are several central software libraries for linear algebra and eigenvalue problems. Several of the more -popular ones have been wrapped into ofter software packages like those from the widely used text _Numerical Recipes_. The original source codes in many of the available packages are often taken from the widely used -software package LAPACK, which follows two other popular packages -developed in the 1970s, namely EISPACK and LINPACK. We describe them shortly here. - - * LINPACK: package for linear equations and least square problems. - * LAPACK:package for solving symmetric, unsymmetric and generalized eigenvalue problems. From LAPACK's website URL: "http://www.netlib.org" it is possible to download for free all source codes from this library. Both C/C++ and Fortran versions are available. - * BLAS (I, II and III): (Basic Linear Algebra Subprograms) are routines that provide standard building blocks for performing basic vector and matrix operations. Blas I is vector operations, II vector-matrix operations and III matrix-matrix operations. Highly parallelized and efficient codes, all available for download from URL: "http://www.netlib.org". - - -===== Basic Matrix Features ===== - - -!bt -\[ - \mathbf{A} = - \begin{bmatrix} a_{11} & a_{12} & a_{13} & a_{14} \\ - a_{21} & a_{22} & a_{23} & a_{24} \\ - a_{31} & a_{32} & a_{33} & a_{34} \\ - a_{41} & a_{42} & a_{43} & a_{44} - \end{bmatrix}\qquad -\mathbf{I} = - \begin{bmatrix} 1 & 0 & 0 & 0 \\ - 0 & 1 & 0 & 0 \\ - 0 & 0 & 1 & 0 \\ - 0 & 0 & 0 & 1 - \end{bmatrix} -\] -!et - - - -The inverse of a matrix is defined by - -!bt -\[ -\mathbf{A}^{-1} \cdot \mathbf{A} = I -\] -!et - - -|----------------------------------------------------------------------| -| Relations | Name | matrix elements | -|----------------------------------------------------------------------| -| $A = A^{T}$ | symmetric | $a_{ij} = a_{ji}$ | -| $A = \left (A^{T} \right )^{-1}$ | real orthogonal | $\sum_k a_{ik} a_{jk} = \sum_k a_{ki} a_{kj} = \delta_{ij}$ | -| $A = A^{ * }$ | real matrix | $a_{ij} = a_{ij}^{ * }$ | -| $A = A^{\dagger}$ | hermitian | $a_{ij} = a_{ji}^{ * }$ | -| $A = \left (A^{\dagger} \right )^{-1}$ | unitary | $\sum_k a_{ik} a_{jk}^{ * } = \sum_k a_{ki}^{ * } a_{kj} = \delta_{ij}$ | -|----------------------------------------------------------------------| - - - - -=== Some famous Matrices === - - * Diagonal if $a_{ij}=0$ for $i\ne j$ - * Upper triangular if $a_{ij}=0$ for $i > j$ - * Lower triangular if $a_{ij}=0$ for $i < j$ - * Upper Hessenberg if $a_{ij}=0$ for $i > j+1$ - * Lower Hessenberg if $a_{ij}=0$ for $i < j+1$ - * Tridiagonal if $a_{ij}=0$ for $|i -j| > 1$ - * Lower banded with bandwidth $p$: $a_{ij}=0$ for $i > j+p$ - * Upper banded with bandwidth $p$: $a_{ij}=0$ for $i < j+p$ - * Banded, block upper triangular, block lower triangular.... - - -=== More Basic Matrix Features === - -Some Equivalent Statements -For an $N\times N$ matrix $\mathbf{A}$ the following properties are all equivalent - - * If the inverse of $\mathbf{A}$ exists, $\mathbf{A}$ is nonsingular. - * The equation $\mathbf{Ax}=0$ implies $\mathbf{x}=0$. - * The rows of $\mathbf{A}$ form a basis of $R^N$. - * The columns of $\mathbf{A}$ form a basis of $R^N$. - * $\mathbf{A}$ is a product of elementary matrices. - * $0$ is not eigenvalue of $\mathbf{A}$. - - - -===== Numpy and arrays ===== -"Numpy":"http://www.numpy.org/" provides an easy way to handle arrays in Python. The standard way to import this library is as - -!bc pycod -import numpy as np -!ec -Here follows a simple example where we set up an array of ten elements, all determined by random numbers drawn according to the normal distribution, -!bc pycod -n = 10 -x = np.random.normal(size=n) -print(x) -!ec -We defined a vector $x$ with $n=10$ elements with its values given by the Normal distribution $N(0,1)$. -Another alternative is to declare a vector as follows -!bc pycod -import numpy as np -x = np.array([1, 2, 3]) -print(x) -!ec -Here we have defined a vector with three elements, with $x_0=1$, $x_1=2$ and $x_2=3$. Note that both Python and C++ -start numbering array elements from $0$ and on. This means that a vector with $n$ elements has a sequence of entities $x_0, x_1, x_2, \dots, x_{n-1}$. We could also let (recommended) Numpy to compute the logarithms of a specific array as -!bc pycod -import numpy as np -x = np.log(np.array([4, 7, 8])) -print(x) -!ec - -In the last example we used Numpy's unary function $np.log$. This function is -highly tuned to compute array elements since the code is vectorized -and does not require looping. We normaly recommend that you use the -Numpy intrinsic functions instead of the corresponding _log_ function -from Python's _math_ module. The looping is done explicitely by the -_np.log_ function. The alternative, and slower way to compute the -logarithms of a vector would be to write - -!bc pycod -import numpy as np -from math import log -x = np.array([4, 7, 8]) -for i in range(0, len(x)): - x[i] = log(x[i]) -print(x) -!ec -We note that our code is much longer already and we need to import the _log_ function from the _math_ module. -The attentive reader will also notice that the output is $[1, 1, 2]$. Python interprets automagically our numbers as integers (like the _automatic_ keyword in C++). To change this we could define our array elements to be double precision numbers as -!bc pycod -import numpy as np -x = np.log(np.array([4, 7, 8], dtype = np.float64)) -print(x) -!ec -or simply write them as double precision numbers (Python uses 64 bits as default for floating point type variables), that is -!bc pycod -import numpy as np -x = np.log(np.array([4.0, 7.0, 8.0]) -print(x) -!ec -To check the number of bytes (remember that one byte contains eight bits for double precision variables), you can use simple use the _itemsize_ functionality (the array $x$ is actually an object which inherits the functionalities defined in Numpy) as -!bc pycod -import numpy as np -x = np.log(np.array([4.0, 7.0, 8.0]) -print(x.itemsize) -!ec - - -===== Matrices in Python ===== - -Having defined vectors, we are now ready to try out matrices. We can -define a $3 \times 3 $ real matrix $\hat{A}$ as (recall that we user -lowercase letters for vectors and uppercase letters for matrices) - -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -print(A) -!ec -If we use the _shape_ function we would get $(3, 3)$ as output, that is verifying that our matrix is a $3\times 3$ matrix. We can slice the matrix and print for example the first column (Python organized matrix elements in a row-major order, see below) as -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -# print the first column, row-major order and elements start with 0 -print(A[:,0]) -!ec -We can continue this was by printing out other columns or rows. The example here prints out the second column -!bc pycod -import numpy as np -A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ])) -# print the first column, row-major order and elements start with 0 -print(A[1,:]) -!ec -Numpy contains many other functionalities that allow us to slice, subdivide etc etc arrays. We strongly recommend that you look up the "Numpy website for more details":"http://www.numpy.org/". Useful functions when defining a matrix are the _np.zeros_ function which declares a matrix of a given dimension and sets all elements to zero -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to zero -A = np.zeros( (n, n) ) -print(A) -!ec -or initializing all elements to -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to one -A = np.ones( (n, n) ) -print(A) -!ec -or as unitarily distributed random numbers (see the material on random number generators in the statistics part) -!bc pycod -import numpy as np -n = 10 -# define a matrix of dimension 10 x 10 and set all elements to random numbers with x \in [0, 1] -A = np.random.rand(n, n) -print(A) -!ec - -As we will see throughout these lectures, there are several extremely useful functionalities in Numpy. -As an example, consider the discussion of the covariance matrix. Suppose we have defined three vectors -$\hat{x}, \hat{y}, \hat{z}$ with $n$ elements each. The covariance matrix is defined as -!bt -\[ -\hat{\Sigma} = \begin{bmatrix} \sigma_{xx} & \sigma_{xy} & \sigma_{xz} \\ - \sigma_{yx} & \sigma_{yy} & \sigma_{yz} \\ - \sigma_{zx} & \sigma_{zy} & \sigma_{zz} - \end{bmatrix}, -\] -!et -where for example -!bt -\[ -\sigma_{xy} =\frac{1}{n} \sum_{i=0}^{n-1}(x_i- \overline{x})(y_i- \overline{y}). -\] -!et -The Numpy function _np.cov_ calculates the covariance elements using the factor $1/(n-1)$ instead of $1/n$ since it assumes we do not have the exact mean values. -The following simple function uses the _np.vstack_ function which takes each vector of dimension $1\times n$ and produces a $3\times n$ matrix $\hat{W}$ -!bt -\[ -\hat{W} = \begin{bmatrix} x_0 & y_0 & z_0 \\ - x_1 & y_1 & z_1 \\ - x_2 & y_2 & z_2 \\ - \dots & \dots & \dots \\ - x_{n-2} & y_{n-2} & z_{n-2} \\ - x_{n-1} & y_{n-1} & z_{n-1} - \end{bmatrix}, -\] -!et - -which in turn is converted into into the $3\times 3$ covariance matrix -$\hat{\Sigma}$ via the Numpy function _np.cov()_. We note that we can also calculate -the mean value of each set of samples $\hat{x}$ etc using the Numpy -function _np.mean(x)_. We can also extract the eigenvalues of the -covariance matrix through the _np.linalg.eig()_ function. - -!bc pycod -# Importing various packages -import numpy as np - -n = 100 -x = np.random.normal(size=n) -print(np.mean(x)) -y = 4+3*x+np.random.normal(size=n) -print(np.mean(y)) -z = x**3+np.random.normal(size=n) -print(np.mean(z)) -W = np.vstack((x, y, z)) -Sigma = np.cov(W) -print(Sigma) -Eigvals, Eigvecs = np.linalg.eig(Sigma) -print(Eigvals) -!ec - - -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from scipy import sparse -eye = np.eye(4) -print(eye) -sparse_mtx = sparse.csr_matrix(eye) -print(sparse_mtx) -x = np.linspace(-10,10,100) -y = np.sin(x) -plt.plot(x,y,marker='x') -plt.show() -!ec - - -===== Meet the Pandas ===== - - -FIGURE: [fig/pandas.jpg, width=600 frac=0.8] - -Another useful Python package is -"pandas":"https://pandas.pydata.org/", which is an open source library -providing high-performance, easy-to-use data structures and data -analysis tools for Python. _pandas_ stands for panel data, a term borrowed from econometrics and is an efficient library for data analysis with an emphasis on tabular data. -_pandas_ has two major classes, the _DataFrame_ class with two-dimensional data objects and tabular data organized in columns and the class _Series_ with a focus on one-dimensional data objects. Both classes allow you to index data easily as we will see in the examples below. -_pandas_ allows you also to perform mathematical operations on the data, spanning from simple reshapings of vectors and matrices to statistical operations. - -The following simple example shows how we can, in an easy way make tables of our data. Here we define a data set which includes names, place of birth and date of birth, and displays the data in an easy to read way. We will see repeated use of _pandas_, in particular in connection with classification of data. - -!bc pycod -import pandas as pd -from IPython.display import display -data = {'First Name': ["Frodo", "Bilbo", "Aragorn II", "Samwise"], - 'Last Name': ["Baggins", "Baggins","Elessar","Gamgee"], - 'Place of birth': ["Shire", "Shire", "Eriador", "Shire"], - 'Date of Birth T.A.': [2968, 2890, 2931, 2980] - } -data_pandas = pd.DataFrame(data) -display(data_pandas) -!ec - -In the above we have imported _pandas_ with the shorthand _pd_, the latter has become the standard way we import _pandas_. We make then a list of various variables -and reorganize the aboves lists into a _DataFrame_ and then print out a neat table with specific column labels as *Name*, *place of birth* and *date of birth*. -Displaying these results, we see that the indices are given by the default numbers from zero to three. -_pandas_ is extremely flexible and we can easily change the above indices by defining a new type of indexing as -!bc pycod -data_pandas = pd.DataFrame(data,index=['Frodo','Bilbo','Aragorn','Sam']) -display(data_pandas) -!ec -Thereafter we display the content of the row which begins with the index _Aragorn_ -!bc pycod -display(data_pandas.loc['Aragorn']) -!ec - -We can easily append data to this, for example -!bc pycod -new_hobbit = {'First Name': ["Peregrin"], - 'Last Name': ["Took"], - 'Place of birth': ["Shire"], - 'Date of Birth T.A.': [2990] - } -data_pandas=data_pandas.append(pd.DataFrame(new_hobbit, index=['Pippin'])) -display(data_pandas) -!ec - - -Here are other examples where we use the _DataFrame_ functionality to handle arrays, now with more interesting features for us, namely numbers. We set up a matrix -of dimensionality $10\times 5$ and compute the mean value and standard deviation of each column. Similarly, we can perform mathematial operations like squaring the matrix elements and many other operations. -!bc pycod -import numpy as np -import pandas as pd -from IPython.display import display -np.random.seed(100) -# setting up a 10 x 5 matrix -rows = 10 -cols = 5 -a = np.random.randn(rows,cols) -df = pd.DataFrame(a) -display(df) -print(df.mean()) -print(df.std()) -display(df**2) -!ec - -Thereafter we can select specific columns only and plot final results -!bc pycod -df.columns = ['First', 'Second', 'Third', 'Fourth', 'Fifth'] -df.index = np.arange(10) - -display(df) -print(df['Second'].mean() ) -print(df.info()) -print(df.describe()) - -from pylab import plt, mpl -plt.style.use('seaborn') -mpl.rcParams['font.family'] = 'serif' - -df.cumsum().plot(lw=2.0, figsize=(10,6)) -plt.show() - - -df.plot.bar(figsize=(10,6), rot=15) -plt.show() -!ec -We can produce a $4\times 4$ matrix -!bc pycod -b = np.arange(16).reshape((4,4)) -print(b) -df1 = pd.DataFrame(b) -print(df1) -!ec -and many other operations. - -The _Series_ class is another important class included in -_pandas_. You can view it as a specialization of _DataFrame_ but where -we have just a single column of data. It shares many of the same features as _DataFrame. As with _DataFrame_, -most operations are vectorized, achieving thereby a high performance when dealing with computations of arrays, in particular labeled arrays. -As we will see below it leads also to a very concice code close to the mathematical operations we may be interested in. -For multidimensional arrays, we recommend strongly "xarray":"http://xarray.pydata.org/en/stable/". _xarray_ has much of the same flexibility as _pandas_, but allows for the extension to higher dimensions than two. We will see examples later of the usage of both _pandas_ and _xarray_. - - - -===== Reading Data and fitting ===== - -In order to study various Machine Learning algorithms, we need to -access data. Acccessing data is an essential step in all machine -learning algorithms. In particular, setting up the so-called _design -matrix_ (to be defined below) is often the first element we need in -order to perform our calculations. To set up the design matrix means -reading (and later, when the calculations are done, writing) data -in various formats, The formats span from reading files from disk, -loading data from databases and interacting with online sources -like web application programming interfaces (APIs). - -In handling various input formats, as discussed above, we will mainly stay with _pandas_, -a Python package which allows us, in a seamless and painless way, to -deal with a multitude of formats, from standard _csv_ (comma separated -values) files, via _excel_, _html_ to _hdf5_ formats. With _pandas_ -and the _DataFrame_ and _Series_ functionalities we are able to convert text data -into the calculational formats we need for a specific algorithm. And our code is going to be -pretty close the basic mathematical expressions. - -Our first data set is going to be a classic from nuclear physics, namely all -available data on binding energies. Don't be intimidated if you are not familiar with nuclear physics. It serves simply as an example here of a data set. - -We will show some of the -strengths of packages like _Scikit-Learn_ in fitting nuclear binding energies to -specific functions using linear regression first. Then, as a teaser, we will show you how -you can easily implement other algorithms like decision trees and random forests and neural networks. - -But before we really start with nuclear physics data, let's just look at some simpler polynomial fitting cases, such as, -(don't be offended) fitting straight lines! - - -=== Simple linear regression model using _scikit-learn_ === - -We start with perhaps our simplest possible example, using _Scikit-Learn_ to perform linear regression analysis on a data set produced by us. - -What follows is a simple Python code where we have defined a function -$y$ in terms of the variable $x$. Both are defined as vectors with $100$ entries. -The numbers in the vector $\hat{x}$ are given -by random numbers generated with a uniform distribution with entries -$x_i \in [0,1]$ (more about probability distribution functions -later). These values are then used to define a function $y(x)$ -(tabulated again as a vector) with a linear dependence on $x$ plus a -random noise added via the normal distribution. - - -The Numpy functions are imported used the _import numpy as np_ -statement and the random number generator for the uniform distribution -is called using the function _np.random.rand()_, where we specificy -that we want $100$ random variables. Using Numpy we define -automatically an array with the specified number of elements, $100$ in -our case. With the Numpy function _randn()_ we can compute random -numbers with the normal distribution (mean value $\mu$ equal to zero and -variance $\sigma^2$ set to one) and produce the values of $y$ assuming a linear -dependence as function of $x$ - -!bt -\[ -y = 2x+N(0,1), -\] -!et - -where $N(0,1)$ represents random numbers generated by the normal -distribution. From _Scikit-Learn_ we import then the -_LinearRegression_ functionality and make a prediction $\tilde{y} = -\alpha + \beta x$ using the function _fit(x,y)_. We call the set of -data $(\hat{x},\hat{y})$ for our training data. The Python package -_scikit-learn_ has also a functionality which extracts the above -fitting parameters $\alpha$ and $\beta$ (see below). Later we will -distinguish between training data and test data. - -For plotting we use the Python package -"matplotlib":"https://matplotlib.org/" which produces publication -quality figures. Feel free to explore the extensive -"gallery":"https://matplotlib.org/gallery/index.html" of examples. In -this example we plot our original values of $x$ and $y$ as well as the -prediction _ypredict_ ($\tilde{y}$), which attempts at fitting our -data with a straight line. - -The Python code follows here. -!bc pycod -# Importing various packages -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression - -x = np.random.rand(100,1) -y = 2*x+np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -xnew = np.array([[0],[1]]) -ypredict = linreg.predict(xnew) - -plt.plot(xnew, ypredict, "r-") -plt.plot(x, y ,'ro') -plt.axis([0,1.0,0, 5.0]) -plt.xlabel(r'$x$') -plt.ylabel(r'$y$') -plt.title(r'Simple Linear Regression') -plt.show() -!ec - -This example serves several aims. It allows us to demonstrate several -aspects of data analysis and later machine learning algorithms. The -immediate visualization shows that our linear fit is not -impressive. It goes through the data points, but there are many -outliers which are not reproduced by our linear regression. We could -now play around with this small program and change for example the -factor in front of $x$ and the normal distribution. Try to change the -function $y$ to - -!bt -\[ -y = 10x+0.01 \times N(0,1), -\] -!et - -where $x$ is defined as before. Does the fit look better? Indeed, by -reducing the role of the noise given by the normal distribution we see immediately that -our linear prediction seemingly reproduces better the training -set. However, this testing 'by the eye' is obviouly not satisfactory in the -long run. Here we have only defined the training data and our model, and -have not discussed a more rigorous approach to the _cost_ function. - -We need more rigorous criteria in defining whether we have succeeded or -not in modeling our training data. You will be surprised to see that -many scientists seldomly venture beyond this 'by the eye' approach. A -standard approach for the *cost* function is the so-called $\chi^2$ -function (a variant of the mean-squared error (MSE)) - -!bt -\[ \chi^2 = \frac{1}{n} -\sum_{i=0}^{n-1}\frac{(y_i-\tilde{y}_i)^2}{\sigma_i^2}, -\] -!et - -where $\sigma_i^2$ is the variance (to be defined later) of the entry -$y_i$. We may not know the explicit value of $\sigma_i^2$, it serves -however the aim of scaling the equations and make the cost function -dimensionless. - -Minimizing the cost function is a central aspect of -our discussions to come. Finding its minima as function of the model -parameters ($\alpha$ and $\beta$ in our case) will be a recurring -theme in these series of lectures. Essentially all machine learning -algorithms we will discuss center around the minimization of the -chosen cost function. This depends in turn on our specific -model for describing the data, a typical situation in supervised -learning. Automatizing the search for the minima of the cost function is a -central ingredient in all algorithms. Typical methods which are -employed are various variants of _gradient_ methods. These will be -discussed in more detail later. Again, you'll be surprised to hear that -many practitioners minimize the above function ''by the eye', popularly dubbed as -'chi by the eye'. That is, change a parameter and see (visually and numerically) that -the $\chi^2$ function becomes smaller. - -There are many ways to define the cost function. A simpler approach is to look at the relative difference between the training data and the predicted data, that is we define -the relative error (why would we prefer the MSE instead of the relative error?) as - -!bt -\[ -\epsilon_{\mathrm{relative}}= \frac{\vert \hat{y} -\hat{\tilde{y}}\vert}{\vert \hat{y}\vert}. -\] -!et -We can modify easily the above Python code and plot the relative error instead -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression - -x = np.random.rand(100,1) -y = 5*x+0.01*np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -ypredict = linreg.predict(x) - -plt.plot(x, np.abs(ypredict-y)/abs(y), "ro") -plt.axis([0,1.0,0.0, 0.5]) -plt.xlabel(r'$x$') -plt.ylabel(r'$\epsilon_{\mathrm{relative}}$') -plt.title(r'Relative error') -plt.show() -!ec - -Depending on the parameter in front of the normal distribution, we may -have a small or larger relative error. Try to play around with -different training data sets and study (graphically) the value of the -relative error. - -As mentioned above, _Scikit-Learn_ has an impressive functionality. -We can for example extract the values of $\alpha$ and $\beta$ and -their error estimates, or the variance and standard deviation and many -other properties from the statistical data analysis. - -Here we show an -example of the functionality of _Scikit-Learn_. -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import LinearRegression -from sklearn.metrics import mean_squared_error, r2_score, mean_squared_log_error, mean_absolute_error - -x = np.random.rand(100,1) -y = 2.0+ 5*x+0.5*np.random.randn(100,1) -linreg = LinearRegression() -linreg.fit(x,y) -ypredict = linreg.predict(x) -print('The intercept alpha: \n', linreg.intercept_) -print('Coefficient beta : \n', linreg.coef_) -# The mean squared error -print("Mean squared error: %.2f" % mean_squared_error(y, ypredict)) -# Explained variance score: 1 is perfect prediction -print('Variance score: %.2f' % r2_score(y, ypredict)) -# Mean squared log error -print('Mean squared log error: %.2f' % mean_squared_log_error(y, ypredict) ) -# Mean absolute error -print('Mean absolute error: %.2f' % mean_absolute_error(y, ypredict)) -plt.plot(x, ypredict, "r-") -plt.plot(x, y ,'ro') -plt.axis([0.0,1.0,1.5, 7.0]) -plt.xlabel(r'$x$') -plt.ylabel(r'$y$') -plt.title(r'Linear Regression fit ') -plt.show() - -!ec -The function _coef_ gives us the parameter $\beta$ of our fit while _intercept_ yields -$\alpha$. Depending on the constant in front of the normal distribution, we get values near or far from $alpha =2$ and $\beta =5$. Try to play around with different parameters in front of the normal distribution. The function _meansquarederror_ gives us the mean square error, a risk metric corresponding to the expected value of the squared (quadratic) error or loss defined as -!bt -\[ MSE(\hat{y},\hat{\tilde{y}}) = \frac{1}{n} -\sum_{i=0}^{n-1}(y_i-\tilde{y}_i)^2, -\] -!et - -The smaller the value, the better the fit. Ideally we would like to -have an MSE equal zero. The attentive reader has probably recognized -this function as being similar to the $\chi^2$ function defined above. - -The _r2score_ function computes $R^2$, the coefficient of -determination. It provides a measure of how well future samples are -likely to be predicted by the model. Best possible score is 1.0 and it -can be negative (because the model can be arbitrarily worse). A -constant model that always predicts the expected value of $\hat{y}$, -disregarding the input features, would get a $R^2$ score of $0.0$. - -If $\tilde{\hat{y}}_i$ is the predicted value of the $i-th$ sample and $y_i$ is the corresponding true value, then the score $R^2$ is defined as -!bt -\[ -R^2(\hat{y}, \tilde{\hat{y}}) = 1 - \frac{\sum_{i=0}^{n - 1} (y_i - \tilde{y}_i)^2}{\sum_{i=0}^{n - 1} (y_i - \bar{y})^2}, -\] -!et -where we have defined the mean value of $\hat{y}$ as -!bt -\[ -\bar{y} = \frac{1}{n} \sum_{i=0}^{n - 1} y_i. -\] -!et -Another quantity taht we will meet again in our discussions of regression analysis is - the mean absolute error (MAE), a risk metric corresponding to the expected value of the absolute error loss or what we call the $l1$-norm loss. In our discussion above we presented the relative error. -The MAE is defined as follows -!bt -\[ -\text{MAE}(\hat{y}, \hat{\tilde{y}}) = \frac{1}{n} \sum_{i=0}^{n-1} \left| y_i - \tilde{y}_i \right|. -\] -!et -Finally we present the -squared logarithmic (quadratic) error -!bt -\[ -\text{MSLE}(\hat{y}, \hat{\tilde{y}}) = \frac{1}{n} \sum_{i=0}^{n - 1} (\log_e (1 + y_i) - \log_e (1 + \tilde{y}_i) )^2, -\] -!et - -where $\log_e (x)$ stands for the natural logarithm of $x$. This error -estimate is best to use when targets having exponential growth, such -as population counts, average sales of a commodity over a span of -years etc. - -We will discuss in more -detail these and other functions in the various lectures. We conclude this part with another example. Instead of -a linear $x$-dependence we study now a cubic polynomial and use the polynomial regression analysis tools of scikit-learn. - -!bc pycod -import matplotlib.pyplot as plt -import numpy as np -import random -from sklearn.linear_model import Ridge -from sklearn.preprocessing import PolynomialFeatures -from sklearn.pipeline import make_pipeline -from sklearn.linear_model import LinearRegression - -x=np.linspace(0.02,0.98,200) -noise = np.asarray(random.sample((range(200)),200)) -y=x**3*noise -yn=x**3*100 -poly3 = PolynomialFeatures(degree=3) -X = poly3.fit_transform(x[:,np.newaxis]) -clf3 = LinearRegression() -clf3.fit(X,y) - -Xplot=poly3.fit_transform(x[:,np.newaxis]) -poly3_plot=plt.plot(x, clf3.predict(Xplot), label='Cubic Fit') -plt.plot(x,yn, color='red', label="True Cubic") -plt.scatter(x, y, label='Data', color='orange', s=15) -plt.legend() -plt.show() - -def error(a): - for i in y: - err=(y-yn)/yn - return abs(np.sum(err))/len(err) - -print (error(y)) -!ec - - - - -=== To our real data: nuclear binding energies. Brief reminder on masses and binding energies === - -Let us now dive into nuclear physics and remind ourselves briefly about some basic features about binding -energies. A basic quantity which can be measured for the ground -states of nuclei is the atomic mass $M(N, Z)$ of the neutral atom with -atomic mass number $A$ and charge $Z$. The number of neutrons is $N$. There are indeed several sophisticated experiments worldwide which allow us to measure this quantity to high precision (parts per million even). - -Atomic masses are usually tabulated in terms of the mass excess defined by -!bt -\[ -\Delta M(N, Z) = M(N, Z) - uA, -\] -!et -where $u$ is the Atomic Mass Unit -!bt -\[ -u = M(^{12}\mathrm{C})/12 = 931.4940954(57) \hspace{0.1cm} \mathrm{MeV}/c^2. -\] -!et -The nucleon masses are -!bt -\[ -m_p = 1.00727646693(9)u, -\] -!et -and -!bt -\[ -m_n = 939.56536(8)\hspace{0.1cm} \mathrm{MeV}/c^2 = 1.0086649156(6)u. -\] -!et - -In the "2016 mass evaluation of by W.J.Huang, G.Audi, M.Wang, F.G.Kondev, S.Naimi and X.Xu":"http://nuclearmasses.org/resources_folder/Wang_2017_Chinese_Phys_C_41_030003.pdf" -there are data on masses and decays of 3437 nuclei. - -The nuclear binding energy is defined as the energy required to break -up a given nucleus into its constituent parts of $N$ neutrons and $Z$ -protons. In terms of the atomic masses $M(N, Z)$ the binding energy is -defined by - - -!bt -\[ -BE(N, Z) = ZM_H c^2 + Nm_n c^2 - M(N, Z)c^2 , -\] -!et -where $M_H$ is the mass of the hydrogen atom and $m_n$ is the mass of the neutron. -In terms of the mass excess the binding energy is given by -!bt -\[ -BE(N, Z) = Z\Delta_H c^2 + N\Delta_n c^2 -\Delta(N, Z)c^2 , -\] -!et -where $\Delta_H c^2 = 7.2890$ MeV and $\Delta_n c^2 = 8.0713$ MeV. - - -A popular and physically intuitive model which can be used to parametrize -the experimental binding energies as function of $A$, is the so-called -_liquid drop model_. The ansatz is based on the following expression - -!bt -\[ -BE(N,Z) = a_1A-a_2A^{2/3}-a_3\frac{Z^2}{A^{1/3}}-a_4\frac{(N-Z)^2}{A}, -\] -!et - -where $A$ stands for the number of nucleons and the $a_i$s are parameters which are determined by a fit -to the experimental data. - - - - -To arrive at the above expression we have assumed that we can make the following assumptions: - - * There is a volume term $a_1A$ proportional with the number of nucleons (the energy is also an extensive quantity). When an assembly of nucleons of the same size is packed together into the smallest volume, each interior nucleon has a certain number of other nucleons in contact with it. This contribution is proportional to the volume. - - * There is a surface energy term $a_2A^{2/3}$. The assumption here is that a nucleon at the surface of a nucleus interacts with fewer other nucleons than one in the interior of the nucleus and hence its binding energy is less. This surface energy term takes that into account and is therefore negative and is proportional to the surface area. - - - * There is a Coulomb energy term $a_3\frac{Z^2}{A^{1/3}}$. The electric repulsion between each pair of protons in a nucleus yields less binding. - - * There is an asymmetry term $a_4\frac{(N-Z)^2}{A}$. This term is associated with the Pauli exclusion principle and reflects the fact that the proton-neutron interaction is more attractive on the average than the neutron-neutron and proton-proton interactions. - -We could also add a so-called pairing term, which is a correction term that -arises from the tendency of proton pairs and neutron pairs to -occur. An even number of particles is more stable than an odd number. - - -=== Organizing our data === - -Let us start with reading and organizing our data. -We start with the compilation of masses and binding energies from 2016. -After having downloaded this file to our own computer, we are now ready to read the file and start structuring our data. - - -We start with preparing folders for storing our calculations and the data file over masses and binding energies. We import also various modules that we will find useful in order to present various Machine Learning methods. Here we focus mainly on the functionality of _scikit-learn_. -!bc pycod -# Common imports -import numpy as np -import pandas as pd -import matplotlib.pyplot as plt -import sklearn.linear_model as skl -from sklearn.model_selection import train_test_split -from sklearn.metrics import mean_squared_error, r2_score, mean_absolute_error -import os - -# Where to save the figures and data files -PROJECT_ROOT_DIR = "Results" -FIGURE_ID = "Results/FigureFiles" -DATA_ID = "DataFiles/" - -if not os.path.exists(PROJECT_ROOT_DIR): - os.mkdir(PROJECT_ROOT_DIR) - -if not os.path.exists(FIGURE_ID): - os.makedirs(FIGURE_ID) - -if not os.path.exists(DATA_ID): - os.makedirs(DATA_ID) - -def image_path(fig_id): - return os.path.join(FIGURE_ID, fig_id) - -def data_path(dat_id): - return os.path.join(DATA_ID, dat_id) - -def save_fig(fig_id): - plt.savefig(image_path(fig_id) + ".png", format='png') - -infile = open(data_path("MassEval2016.dat"),'r') -!ec - - -Before we proceed, we define also a function for making our plots. You can obviously avoid this and simply set up various _matplotlib_ commands every time you need them. You may however find it convenient to collect all such commands in one function and simply call this function. -!bc pycod -from pylab import plt, mpl -plt.style.use('seaborn') -mpl.rcParams['font.family'] = 'serif' - -def MakePlot(x,y, styles, labels, axlabels): - plt.figure(figsize=(10,6)) - for i in range(len(x)): - plt.plot(x[i], y[i], styles[i], label = labels[i]) - plt.xlabel(axlabels[0]) - plt.ylabel(axlabels[1]) - plt.legend(loc=0) -!ec - -Our next step is to read the data on experimental binding energies and -reorganize them as functions of the mass number $A$, the number of -protons $Z$ and neutrons $N$ using _pandas_. Before we do this it is -always useful (unless you have a binary file or other types of compressed -data) to actually open the file and simply take a look at it! - - -In particular, the program that outputs the final nuclear masses is written in Fortran with a specific format. It means that we need to figure out the format and which columns contain the data we are interested in. Pandas comes with a function that reads formatted output. After having admired the file, we are now ready to start massaging it with _pandas_. The file begins with some basic format information. -!bc pycod -""" -This is taken from the data file of the mass 2016 evaluation. -All files are 3436 lines long with 124 character per line. - Headers are 39 lines long. - col 1 : Fortran character control: 1 = page feed 0 = line feed - format : a1,i3,i5,i5,i5,1x,a3,a4,1x,f13.5,f11.5,f11.3,f9.3,1x,a2,f11.3,f9.3,1x,i3,1x,f12.5,f11.5 - These formats are reflected in the pandas widths variable below, see the statement - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - Pandas has also a variable header, with length 39 in this case. -""" -!ec - -The data we are interested in are in columns 2, 3, 4 and 11, giving us -the number of neutrons, protons, mass numbers and binding energies, -respectively. We add also for the sake of completeness the element name. The data are in fixed-width formatted lines and we will -covert them into the _pandas_ DataFrame structure. - -!bc pycod -# Read the experimental data with Pandas -Masses = pd.read_fwf(infile, usecols=(2,3,4,6,11), - names=('N', 'Z', 'A', 'Element', 'Ebinding'), - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - header=39, - index_col=False) - -# Extrapolated values are indicated by '#' in place of the decimal place, so -# the Ebinding column won't be numeric. Coerce to float and drop these entries. -Masses['Ebinding'] = pd.to_numeric(Masses['Ebinding'], errors='coerce') -Masses = Masses.dropna() -# Convert from keV to MeV. -Masses['Ebinding'] /= 1000 - -# Group the DataFrame by nucleon number, A. -Masses = Masses.groupby('A') -# Find the rows of the grouped DataFrame with the maximum binding energy. -Masses = Masses.apply(lambda t: t[t.Ebinding==t.Ebinding.max()]) -!ec - -We have now read in the data, grouped them according to the variables we are interested in. -We see how easy it is to reorganize the data using _pandas_. If we -were to do these operations in C/C++ or Fortran, we would have had to -write various functions/subroutines which perform the above -reorganizations for us. Having reorganized the data, we can now start -to make some simple fits using both the functionalities in _numpy_ and -_Scikit-Learn_ afterwards. - -Now we define five variables which contain -the number of nucleons $A$, the number of protons $Z$ and the number of neutrons $N$, the element name and finally the energies themselves. -!bc pycod -A = Masses['A'] -Z = Masses['Z'] -N = Masses['N'] -Element = Masses['Element'] -Energies = Masses['Ebinding'] -print(Masses) -!ec -The next step, and we will define this mathematically later, is to set up the so-called _design matrix_. We will throughout call this matrix $\bm{X}$. -It has dimensionality $p\times n$, where $n$ is the number of data points and $p$ are the so-called predictors. In our case here they are given by the number of polynomials in $A$ we wish to include in the fit. -!bc pycod -# Now we set up the design matrix X -X = np.zeros((len(A),5)) -X[:,0] = 1 -X[:,1] = A -X[:,2] = A**(2.0/3.0) -X[:,3] = A**(-1.0/3.0) -X[:,4] = A**(-1.0) -!ec -With _scikitlearn_ we are now ready to use linear regression and fit our data. -!bc pycod -clf = skl.LinearRegression().fit(X, Energies) -fity = clf.predict(X) -!ec -Pretty simple! -Now we can print measures of how our fit is doing, the coefficients from the fits and plot the final fit together with our data. -!bc pycod -# The mean squared error -print("Mean squared error: %.2f" % mean_squared_error(Energies, fity)) -# Explained variance score: 1 is perfect prediction -print('Variance score: %.2f' % r2_score(Energies, fity)) -# Mean absolute error -print('Mean absolute error: %.2f' % mean_absolute_error(Energies, fity)) -print(clf.coef_, clf.intercept_) - -Masses['Eapprox'] = fity -# Generate a plot comparing the experimental with the fitted values values. -fig, ax = plt.subplots() -ax.set_xlabel(r'$A = N + Z$') -ax.set_ylabel(r'$E_\mathrm{bind}\,/\mathrm{MeV}$') -ax.plot(Masses['A'], Masses['Ebinding'], alpha=0.7, lw=2, - label='Ame2016') -ax.plot(Masses['A'], Masses['Eapprox'], alpha=0.7, lw=2, c='m', - label='Fit') -ax.legend() -save_fig("Masses2016") -plt.show() -!ec - - -=== Seeing the wood for the trees === - -As a teaser, let us now see how we can do this with decision trees using _scikit-learn_. Later we will switch to so-called _random forests_! - - -!bc pycod - -#Decision Tree Regression -from sklearn.tree import DecisionTreeRegressor -regr_1=DecisionTreeRegressor(max_depth=5) -regr_2=DecisionTreeRegressor(max_depth=7) -regr_3=DecisionTreeRegressor(max_depth=9) -regr_1.fit(X, Energies) -regr_2.fit(X, Energies) -regr_3.fit(X, Energies) - - -y_1 = regr_1.predict(X) -y_2 = regr_2.predict(X) -y_3=regr_3.predict(X) -Masses['Eapprox'] = y_3 -# Plot the results -plt.figure() -plt.plot(A, Energies, color="blue", label="Data", linewidth=2) -plt.plot(A, y_1, color="red", label="max_depth=5", linewidth=2) -plt.plot(A, y_2, color="green", label="max_depth=7", linewidth=2) -plt.plot(A, y_3, color="m", label="max_depth=9", linewidth=2) - -plt.xlabel("$A$") -plt.ylabel("$E$[MeV]") -plt.title("Decision Tree Regression") -plt.legend() -save_fig("Masses2016Trees") -plt.show() -print(Masses) -print(np.mean( (Energies-y_1)**2)) -!ec - - -=== And what about using neural networks? === -The _seaborn_ package allows us to visualize data in an efficient way. Note that we use _scikit-learn_'s multi-layer perceptron (or feed forward neural network) -functionality. -!bc pycod -from sklearn.neural_network import MLPRegressor -from sklearn.metrics import accuracy_score -import seaborn as sns - -X_train = X -Y_train = Energies -n_hidden_neurons = 100 -epochs = 100 -# store models for later use -eta_vals = np.logspace(-5, 1, 7) -lmbd_vals = np.logspace(-5, 1, 7) -# store the models for later use -DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object) -train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals))) -sns.set() -for i, eta in enumerate(eta_vals): - for j, lmbd in enumerate(lmbd_vals): - dnn = MLPRegressor(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 - train_accuracy[i][j] = dnn.score(X_train, Y_train) - -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() - - - -!ec - - - - - - -===== A first summary ===== - -The aim behind these introductory words was to present to you various -Python libraries and their functionalities, in particular libraries like -_numpy_, _pandas_, _xarray_ and _matplotlib_ and other that make our life much easier -in handling various data sets and visualizing data. - -Furthermore, -_Scikit-Learn_ allows us with few lines of code to implement popular -Machine Learning algorithms for supervised learning. Later we will meet _Tensorflow_, a powerful library for deep learning. -Now it is time to dive more into the details of various methods. We will start with linear regression and try to take a deeper look at what it entails. - - - - - - - - -======= Why Linear Regression (aka Ordinary Least Squares and family) ======= - -Fitting a continuous function with linear parameterization in terms of the parameters $\bm{\beta}$. -* Method of choice for fitting a continuous function! -* Gives an excellent introduction to central Machine Learning features with _understandable pedagogical_ links to other methods like _Neural Networks_, _Support Vector Machines_ etc -* Analytical expression for the fitting parameters $\bm{\beta}$ -* Analytical expressions for statistical propertiers like mean values, variances, confidence intervals and more -* Analytical relation with probabilistic interpretations -* Easy to introduce basic concepts like bias-variance tradeoff, cross-validation, resampling and regularization techniques and many other ML topics -* Easy to code! And links well with classification problems and logistic regression and neural networks -* Allows for _easy_ hands-on understanding of gradient descent methods -* and many more features - -For more discussions of Ridge and Lasso regression, "Wessel van Wieringen's":"https://arxiv.org/abs/1509.09169" article is highly recommended. -Similarly, "Mehta et al's article":"https://arxiv.org/abs/1803.08823" is also recommended. - - -=== Regression analysis, overarching aims === - -Regression modeling deals with the description of the sampling distribution of a given random variable $y$ and how it varies as function of another variable or a set of such variables $\bm{x} =[x_0, x_1,\dots, x_{n-1}]^T$. -The first variable is called the _dependent_, the _outcome_ or the _response_ variable while the set of variables $\bm{x}$ is called the independent variable, or the predictor variable or the explanatory variable. - -A regression model aims at finding a likelihood function $p(\bm{y}\vert \bm{x})$, that is the conditional distribution for $\bm{y}$ with a given $\bm{x}$. The estimation of $p(\bm{y}\vert \bm{x})$ is made using a data set with -* $n$ cases $i = 0, 1, 2, \dots, n-1$ -* Response (target, dependent or outcome) variable $y_i$ with $i = 0, 1, 2, \dots, n-1$ -* $p$ so-called explanatory (independent or predictor) variables $\bm{x}_i=[x_{i0}, x_{i1}, \dots, x_{ip-1}]$ with $i = 0, 1, 2, \dots, n-1$ and explanatory variables running from $0$ to $p-1$. See below for more explicit examples. - The goal of the regression analysis is to extract/exploit relationship between $\bm{y}$ and $\bm{X}$ in or to infer causal dependencies, approximations to the likelihood functions, functional relationships and to make predictions, making fits and many other things. - - -Consider an experiment in which $p$ characteristics of $n$ samples are -measured. The data from this experiment, for various explanatory variables $p$ are normally represented by a matrix -$\mathbf{X}$. - -The matrix $\mathbf{X}$ is called the *design -matrix*. Additional information of the samples is available in the -form of $\bm{y}$ (also as above). The variable $\bm{y}$ is -generally referred to as the *response variable*. The aim of -regression analysis is to explain $\bm{y}$ in terms of -$\bm{X}$ through a functional relationship like $y_i = -f(\mathbf{X}_{i,\ast})$. When no prior knowledge on the form of -$f(\cdot)$ is available, it is common to assume a linear relationship -between $\bm{X}$ and $\bm{y}$. This assumption gives rise to -the *linear regression model* where $\bm{\beta} = [\beta_0, \ldots, -\beta_{p-1}]^{T}$ are the *regression parameters*. - -Linear regression gives us a set of analytical equations for the parameters $\beta_j$. - - -=== Examples === - -In order to understand the relation among the predictors $p$, the set of data $n$ and the target (outcome, output etc) $\bm{y}$, -consider the model we discussed for describing nuclear binding energies. - -There we assumed that we could parametrize the data using a polynomial approximation based on the liquid drop model. -Assuming -!bt -\[ -BE(A) = a_0+a_1A+a_2A^{2/3}+a_3A^{-1/3}+a_4A^{-1}, -\] -!et -we have five predictors, that is the intercept, the $A$ dependent term, the $A^{2/3}$ term and the $A^{-1/3}$ and $A^{-1}$ terms. -This gives $p=0,1,2,3,4$. Furthermore we have $n$ entries for each predictor. It means that our design matrix is a -$p\times n$ matrix $\bm{X}$. - -Here the predictors are based on a model we have made. A popular data set which is widely encountered in ML applications is the -so-called "credit card default data from Taiwan":"https://www.sciencedirect.com/science/article/pii/S0957417407006719?via%3Dihub". The data set contains data on $n=30000$ credit card holders with predictors like gender, marital status, age, profession, education, etc. In total there are $24$ such predictors or attributes leading to a design matrix of dimensionality $24 \times 30000$ - - -===== General linear models ===== - -Before we proceed let us study a case from linear algebra where we aim at fitting a set of data $\bm{y}=[y_0,y_1,\dots,y_{n-1}]$. We could think of these data as a result of an experiment or a complicated numerical experiment. These data are functions of a series of variables $\bm{x}=[x_0,x_1,\dots,x_{n-1}]$, that is $y_i = y(x_i)$ with $i=0,1,2,\dots,n-1$. The variables $x_i$ could represent physical quantities like time, temperature, position etc. We assume that $y(x)$ is a smooth function. - -Since obtaining these data points may not be trivial, we want to use these data to fit a function which can allow us to make predictions for values of $y$ which are not in the present set. The perhaps simplest approach is to assume we can parametrize our function in terms of a polynomial of degree $n-1$ with $n$ points, that is -!bt -\[ -y=y(x) \rightarrow y(x_i)=\tilde{y}_i+\epsilon_i=\sum_{j=0}^{n-1} \beta_j x_i^j+\epsilon_i, -\] -!et -where $\epsilon_i$ is the error in our approximation. - - -For every set of values $y_i,x_i$ we have thus the corresponding set of equations -!bt -\begin{align*} -y_0&=\beta_0+\beta_1x_0^1+\beta_2x_0^2+\dots+\beta_{n-1}x_0^{n-1}+\epsilon_0\\ -y_1&=\beta_0+\beta_1x_1^1+\beta_2x_1^2+\dots+\beta_{n-1}x_1^{n-1}+\epsilon_1\\ -y_2&=\beta_0+\beta_1x_2^1+\beta_2x_2^2+\dots+\beta_{n-1}x_2^{n-1}+\epsilon_2\\ -\dots & \dots \\ -y_{n-1}&=\beta_0+\beta_1x_{n-1}^1+\beta_2x_{n-1}^2+\dots+\beta_{n-1}x_{n-1}^{n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - - -Defining the vectors -!bt -\[ -\bm{y} = [y_0,y_1, y_2,\dots, y_{n-1}]^T, -\] -!et -and -!bt -\[ -\bm{\beta} = [\beta_0,\beta_1, \beta_2,\dots, \beta_{n-1}]^T, -\] -!et -and -!bt -\[ -\bm{\epsilon} = [\epsilon_0,\epsilon_1, \epsilon_2,\dots, \epsilon_{n-1}]^T, -\] -!et -and the design matrix -!bt -\[ -\bm{X}= -\begin{bmatrix} -1& x_{0}^1 &x_{0}^2& \dots & \dots &x_{0}^{n-1}\\ -1& x_{1}^1 &x_{1}^2& \dots & \dots &x_{1}^{n-1}\\ -1& x_{2}^1 &x_{2}^2& \dots & \dots &x_{2}^{n-1}\\ -\dots& \dots &\dots& \dots & \dots &\dots\\ -1& x_{n-1}^1 &x_{n-1}^2& \dots & \dots &x_{n-1}^{n-1}\\ -\end{bmatrix} -\] -!et -we can rewrite our equations as -!bt -\[ -\bm{y} = \bm{X}\bm{\beta}+\bm{\epsilon}. -\] -!et -The above design matrix is called a "Vandermonde matrix":"https://en.wikipedia.org/wiki/Vandermonde_matrix". - - - - -===== Generalizing the fitting procedure as a linear algebra problem ===== - -We are obviously not limited to the above polynomial expansions. We -could replace the various powers of $x$ with elements of Fourier -series or instead of $x_i^j$ we could have $\cos{(j x_i)}$ or $\sin{(j -x_i)}$, or time series or other orthogonal functions. For every set -of values $y_i,x_i$ we can then generalize the equations to - -!bt -\begin{align*} -y_0&=\beta_0x_{00}+\beta_1x_{01}+\beta_2x_{02}+\dots+\beta_{n-1}x_{0n-1}+\epsilon_0\\ -y_1&=\beta_0x_{10}+\beta_1x_{11}+\beta_2x_{12}+\dots+\beta_{n-1}x_{1n-1}+\epsilon_1\\ -y_2&=\beta_0x_{20}+\beta_1x_{21}+\beta_2x_{22}+\dots+\beta_{n-1}x_{2n-1}+\epsilon_2\\ -\dots & \dots \\ -y_{i}&=\beta_0x_{i0}+\beta_1x_{i1}+\beta_2x_{i2}+\dots+\beta_{n-1}x_{in-1}+\epsilon_i\\ -\dots & \dots \\ -y_{n-1}&=\beta_0x_{n-1,0}+\beta_1x_{n-1,2}+\beta_2x_{n-1,2}+\dots+\beta_{n-1}x_{n-1,n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - -_Note that we have $p=n$ here. The matrix is symmetric. This is generally not the case!_ - -We redefine in turn the matrix $\bm{X}$ as -!bt -\[ -\bm{X}= -\begin{bmatrix} -x_{00}& x_{01} &x_{02}& \dots & \dots &x_{0,n-1}\\ -x_{10}& x_{11} &x_{12}& \dots & \dots &x_{1,n-1}\\ -x_{20}& x_{21} &x_{22}& \dots & \dots &x_{2,n-1}\\ -\dots& \dots &\dots& \dots & \dots &\dots\\ -x_{n-1,0}& x_{n-1,1} &x_{n-1,2}& \dots & \dots &x_{n-1,n-1}\\ -\end{bmatrix} -\] -!et -and without loss of generality we rewrite again our equations as -!bt -\[ -\bm{y} = \bm{X}\bm{\beta}+\bm{\epsilon}. -\] -!et -The left-hand side of this equation is kwown. Our error vector $\bm{\epsilon}$ and the parameter vector $\bm{\beta}$ are our unknow quantities. How can we obtain the optimal set of $\beta_i$ values? - -We have defined the matrix $\bm{X}$ via the equations -!bt -\begin{align*} -y_0&=\beta_0x_{00}+\beta_1x_{01}+\beta_2x_{02}+\dots+\beta_{n-1}x_{0n-1}+\epsilon_0\\ -y_1&=\beta_0x_{10}+\beta_1x_{11}+\beta_2x_{12}+\dots+\beta_{n-1}x_{1n-1}+\epsilon_1\\ -y_2&=\beta_0x_{20}+\beta_1x_{21}+\beta_2x_{22}+\dots+\beta_{n-1}x_{2n-1}+\epsilon_1\\ -\dots & \dots \\ -y_{i}&=\beta_0x_{i0}+\beta_1x_{i1}+\beta_2x_{i2}+\dots+\beta_{n-1}x_{in-1}+\epsilon_1\\ -\dots & \dots \\ -y_{n-1}&=\beta_0x_{n-1,0}+\beta_1x_{n-1,2}+\beta_2x_{n-1,2}+\dots+\beta_{n-1}x_{n-1,n-1}+\epsilon_{n-1}.\\ -\end{align*} -!et - -As we noted above, we stayed with a system with the design matrix - $\bm{X}\in {\mathbb{R}}^{n\times n}$, that is we have $p=n$. For reasons to come later (algorithmic arguments) we will hereafter define -our matrix as $\bm{X}\in {\mathbb{R}}^{n\times p}$, with the predictors refering to the column numbers and the entries $n$ being the row elements. - - -===== Our model for the nuclear binding energies ===== - -In our introductory notes we looked at the so-called "liguid drop model":"https://en.wikipedia.org/wiki/Semi-empirical_mass_formula". Let us remind ourselves about what we did by looking at the code. - -We restate the parts of the code we are most interested in. -!bc pycod -# Common imports -import numpy as np -import pandas as pd -import matplotlib.pyplot as plt -from IPython.display import display -import os - -# Where to save the figures and data files -PROJECT_ROOT_DIR = "Results" -FIGURE_ID = "Results/FigureFiles" -DATA_ID = "DataFiles/" - -if not os.path.exists(PROJECT_ROOT_DIR): - os.mkdir(PROJECT_ROOT_DIR) - -if not os.path.exists(FIGURE_ID): - os.makedirs(FIGURE_ID) - -if not os.path.exists(DATA_ID): - os.makedirs(DATA_ID) - -def image_path(fig_id): - return os.path.join(FIGURE_ID, fig_id) - -def data_path(dat_id): - return os.path.join(DATA_ID, dat_id) - -def save_fig(fig_id): - plt.savefig(image_path(fig_id) + ".png", format='png') - -infile = open(data_path("MassEval2016.dat"),'r') - - -# Read the experimental data with Pandas -Masses = pd.read_fwf(infile, usecols=(2,3,4,6,11), - names=('N', 'Z', 'A', 'Element', 'Ebinding'), - widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), - header=39, - index_col=False) - -# Extrapolated values are indicated by '#' in place of the decimal place, so -# the Ebinding column won't be numeric. Coerce to float and drop these entries. -Masses['Ebinding'] = pd.to_numeric(Masses['Ebinding'], errors='coerce') -Masses = Masses.dropna() -# Convert from keV to MeV. -Masses['Ebinding'] /= 1000 - -# Group the DataFrame by nucleon number, A. -Masses = Masses.groupby('A') -# Find the rows of the grouped DataFrame with the maximum binding energy. -Masses = Masses.apply(lambda t: t[t.Ebinding==t.Ebinding.max()]) -A = Masses['A'] -Z = Masses['Z'] -N = Masses['N'] -Element = Masses['Element'] -Energies = Masses['Ebinding'] - -# Now we set up the design matrix X -X = np.zeros((len(A),5)) -X[:,0] = 1 -X[:,1] = A -X[:,2] = A**(2.0/3.0) -X[:,3] = A**(-1.0/3.0) -X[:,4] = A**(-1.0) -# Then nice printout using pandas -DesignMatrix = pd.DataFrame(X) -DesignMatrix.index = A -DesignMatrix.columns = ['1', 'A', 'A^(2/3)', 'A^(-1/3)', '1/A'] -display(DesignMatrix) -!ec - -With $\bm{\beta}\in {\mathbb{R}}^{p\times 1}$, it means that we will hereafter write our equations for the approximation as -!bt -\[ -\bm{\tilde{y}}= \bm{X}\bm{\beta}, -\] -!et -throughout these lectures. - - - -With the above we use the design matrix to define the approximation $\bm{\tilde{y}}$ via the unknown quantity $\bm{\beta}$ as -!bt -\[ -\bm{\tilde{y}}= \bm{X}\bm{\beta}, -\] -!et -and in order to find the optimal parameters $\beta_i$ instead of solving the above linear algebra problem, we define a function which gives a measure of the spread between the values $y_i$ (which represent hopefully the exact values) and the parameterized values $\tilde{y}_i$, namely -!bt -\[ -C(\bm{\beta})=\frac{1}{n}\sum_{i=0}^{n-1}\left(y_i-\tilde{y}_i\right)^2=\frac{1}{n}\left\{\left(\bm{y}-\bm{\tilde{y}}\right)^T\left(\bm{y}-\bm{\tilde{y}}\right)\right\}, -\] -!et -or using the matrix $\bm{X}$ and in a more compact matrix-vector notation as -!bt -\[ -C(\bm{\beta})=\frac{1}{n}\left\{\left(\bm{y}-\bm{X}^T\bm{\beta}\right)^T\left(\bm{y}-\bm{X}^T\bm{\beta}\right)\right\}. -\] -!et -This function is one possible way to define the so-called cost function. - - - -It is also common to define -the function $Q$ as - -!bt -\[ -C(\bm{\beta})=\frac{1}{2n}\sum_{i=0}^{n-1}\left(y_i-\tilde{y}_i\right)^2, -\] -!et -since when taking the first derivative with respect to the unknown parameters $\beta$, the factor of $2$ cancels out. - - - - -===== Interpretations and optimizing our parameters ===== - - -The function -!bt -\[ -C(\bm{\beta})=\frac{1}{n}\left\{\left(\bm{y}-\bm{X}\bm{\beta}\right)^T\left(\bm{y}-\bm{X}\bm{\beta}\right)\right\}, -\] -!et -can be linked to the variance of the quantity $y_i$ if we interpret the latter as the mean value. -When linking below with the maximum likelihood approach below, we will indeed interpret $y_i$ as a mean value (see exercises) -!bt -\[ -y_{i}=\langle y_i \rangle = \beta_0x_{i,0}+\beta_1x_{i,1}+\beta_2x_{i,2}+\dots+\beta_{n-1}x_{i,n-1}+\epsilon_i, -\] -!et - -where $\langle y_i \rangle$ is the mean value. Keep in mind also that -till now we have treated $y_i$ as the exact value. Normally, the -response (dependent or outcome) variable $y_i$ the outcome of a -numerical experiment or another type of experiment and is thus only an -approximation to the true value. It is then always accompanied by an -error estimate, often limited to a statistical error estimate given by -the standard deviation discussed earlier. In the discussion here we -will treat $y_i$ as our exact value for the response variable. - -In order to find the parameters $\beta_i$ we will then minimize the spread of $C(\bm{\beta})$, that is we are going to solve the problem -!bt -\[ -{\displaystyle \min_{\bm{\beta}\in -{\mathbb{R}}^{p}}}\frac{1}{n}\left\{\left(\bm{y}-\bm{X}\bm{\beta}\right)^T\left(\bm{y}-\bm{X}\bm{\beta}\right)\right\}. -\] -!et -In practical terms it means we will require -!bt -\[ -\frac{\partial C(\bm{\beta})}{\partial \beta_j} = \frac{\partial }{\partial \beta_j}\left[ \frac{1}{n}\sum_{i=0}^{n-1}\left(y_i-\beta_0x_{i,0}-\beta_1x_{i,1}-\beta_2x_{i,2}-\dots-\beta_{n-1}x_{i,n-1}\right)^2\right]=0, -\] -!et -which results in -!bt -\[ -\frac{\partial C(\bm{\beta})}{\partial \beta_j} = -\frac{2}{n}\left[ \sum_{i=0}^{n-1}x_{ij}\left(y_i-\beta_0x_{i,0}-\beta_1x_{i,1}-\beta_2x_{i,2}-\dots-\beta_{n-1}x_{i,n-1}\right)\right]=0, -\] -!et -or in a matrix-vector form as -!bt -\[ -\frac{\partial C(\bm{\beta})}{\partial \bm{\beta}} = 0 = \bm{X}^T\left( \bm{y}-\bm{X}\bm{\beta}\right). -\] -!et - - - -We can rewrite -!bt -\[ -\frac{\partial C(\bm{\beta})}{\partial \bm{\beta}} = 0 = \bm{X}^T\left( \bm{y}-\bm{X}\bm{\beta}\right), -\] -!et -as -!bt -\[ -\bm{X}^T\bm{y} = \bm{X}^T\bm{X}\bm{\beta}, -\] -!et -and if the matrix $\bm{X}^T\bm{X}$ is invertible we have the solution -!bt -\[ -\bm{\beta} =\left(\bm{X}^T\bm{X}\right)^{-1}\bm{X}^T\bm{y}. -\] -!et - -We note also that since our design matrix is defined as $\bm{X}\in -{\mathbb{R}}^{n\times p}$, the product $\bm{X}^T\bm{X} \in -{\mathbb{R}}^{p\times p}$. In the above case we have that $p \ll n$, -in our case $p=5$ meaning that we end up with inverting a small -$5\times 5$ matrix. This is a rather common situation, in many cases we end up with low-dimensional -matrices to invert. The methods discussed here and for many other -supervised learning algorithms like classification with logistic -regression or support vector machines, exhibit dimensionalities which -allow for the usage of direct linear algebra methods such as _LU_ decomposition or _Singular Value Decomposition_ (SVD) for finding the inverse of the matrix -$\bm{X}^T\bm{X}$. - - - -The residuals $\bm{\epsilon}$ are in turn given by -!bt -\[ -\bm{\epsilon} = \bm{y}-\bm{\tilde{y}} = \bm{y}-\bm{X}\bm{\beta}, -\] -!et -and with -!bt -\[ -\bm{X}^T\left( \bm{y}-\bm{X}\bm{\beta}\right)= 0, -\] -!et -we have -!bt -\[ -\bm{X}^T\bm{\epsilon}=\bm{X}^T\left( \bm{y}-\bm{X}\bm{\beta}\right)= 0, -\] -!et -meaning that the solution for $\bm{\beta}$ is the one which minimizes the residuals. Later we will link this with the maximum likelihood approach. - - -Let us now return to our nuclear binding energies and simply code the above equations. - -It is rather straightforward to implement the matrix inversion and obtain the parameters $\bm{\beta}$. After having defined the matrix $\bm{X}$ we simply need to -write -!bc pycod -# matrix inversion to find beta -beta = np.linalg.inv(X.T.dot(X)).dot(X.T).dot(Energies) -# and then make the prediction -ytilde = X @ beta -!ec -Alternatively, you can use the least squares functionality in _Numpy_ as -!bc pycod -fit = np.linalg.lstsq(X, Energies, rcond =None)[0] -ytildenp = np.dot(fit,X.T) -!ec - -And finally we plot our fit with and compare with data -!bc pycod -Masses['Eapprox'] = ytilde -# Generate a plot comparing the experimental with the fitted values values. -fig, ax = plt.subplots() -ax.set_xlabel(r'$A = N + Z$') -ax.set_ylabel(r'$E_\mathrm{bind}\,/\mathrm{MeV}$') -ax.plot(Masses['A'], Masses['Ebinding'], alpha=0.7, lw=2, - label='Ame2016') -ax.plot(Masses['A'], Masses['Eapprox'], alpha=0.7, lw=2, c='m', - label='Fit') -ax.legend() -save_fig("Masses2016OLS") -plt.show() -!ec - -===== Adding error analysis and training set up ===== - -We can easily test our fit by computing the $R2$ score that we discussed in connection with the functionality of _Scikit_Learn_ in the introductory slides. -Since we are not using _Scikit-Learn here we can define our own $R2$ function as -!bc pycod -def R2(y_data, y_model): - return 1 - np.sum((y_data - y_model) ** 2) / np.sum((y_data - np.mean(y_model)) ** 2) -!ec -and we would be using it as -!bc pycod -print(R2(Energies,ytilde)) -!ec - -We can easily add our _MSE_ score as -!bc pycod -def MSE(y_data,y_model): - n = np.size(y_model) - return np.sum((y_data-y_model)**2)/n - -print(MSE(Energies,ytilde)) -!ec -and finally the relative error as -!bc pycod -def RelativeError(y_data,y_model): - return abs((y_data-y_model)/y_data) -print(RelativeError(Energies, ytilde)) -!ec - - - -===== The $\chi^2$ function ===== - -Normally, the response (dependent or outcome) variable $y_i$ is the -outcome of a numerical experiment or another type of experiment and is -thus only an approximation to the true value. It is then always -accompanied by an error estimate, often limited to a statistical error -estimate given by the standard deviation discussed earlier. In the -discussion here we will treat $y_i$ as our exact value for the -response variable. - -Introducing the standard deviation $\sigma_i$ for each measurement -$y_i$, we define now the $\chi^2$ function (omitting the $1/n$ term) -as - -!bt -\[ -\chi^2(\bm{\beta})=\frac{1}{n}\sum_{i=0}^{n-1}\frac{\left(y_i-\tilde{y}_i\right)^2}{\sigma_i^2}=\frac{1}{n}\left\{\left(\bm{y}-\bm{\tilde{y}}\right)^T\frac{1}{\bm{\Sigma^2}}\left(\bm{y}-\bm{\tilde{y}}\right)\right\}, -\] -!et -where the matrix $\bm{\Sigma}$ is a diagonal matrix with $\sigma_i$ as matrix elements. - - -In order to find the parameters $\beta_i$ we will then minimize the spread of $\chi^2(\bm{\beta})$ by requiring -!bt -\[ -\frac{\partial \chi^2(\bm{\beta})}{\partial \beta_j} = \frac{\partial }{\partial \beta_j}\left[ \frac{1}{n}\sum_{i=0}^{n-1}\left(\frac{y_i-\beta_0x_{i,0}-\beta_1x_{i,1}-\beta_2x_{i,2}-\dots-\beta_{n-1}x_{i,n-1}}{\sigma_i}\right)^2\right]=0, -\] -!et -which results in -!bt -\[ -\frac{\partial \chi^2(\bm{\beta})}{\partial \beta_j} = -\frac{2}{n}\left[ \sum_{i=0}^{n-1}\frac{x_{ij}}{\sigma_i}\left(\frac{y_i-\beta_0x_{i,0}-\beta_1x_{i,1}-\beta_2x_{i,2}-\dots-\beta_{n-1}x_{i,n-1}}{\sigma_i}\right)\right]=0, -\] -!et -or in a matrix-vector form as -!bt -\[ -\frac{\partial \chi^2(\bm{\beta})}{\partial \bm{\beta}} = 0 = \bm{A}^T\left( \bm{b}-\bm{A}\bm{\beta}\right). -\] -!et -where we have defined the matrix $\bm{A} =\bm{X}/\bm{\Sigma}$ with matrix elements $a_{ij} = x_{ij}/\sigma_i$ and the vector $\bm{b}$ with elements $b_i = y_i/\sigma_i$. - -We can rewrite -!bt -\[ -\frac{\partial \chi^2(\bm{\beta})}{\partial \bm{\beta}} = 0 = \bm{A}^T\left( \bm{b}-\bm{A}\bm{\beta}\right), -\] -!et -as -!bt -\[ -\bm{A}^T\bm{b} = \bm{A}^T\bm{A}\bm{\beta}, -\] -!et -and if the matrix $\bm{A}^T\bm{A}$ is invertible we have the solution -!bt -\[ -\bm{\beta} =\left(\bm{A}^T\bm{A}\right)^{-1}\bm{A}^T\bm{b}. -\] -!et - -If we then introduce the matrix -!bt -\[ -\bm{H} = \left(\bm{A}^T\bm{A}\right)^{-1}, -\] -!et -we have then the following expression for the parameters $\beta_j$ (the matrix elements of $\bm{H}$ are $h_{ij}$) -!bt -\[ -\beta_j = \sum_{k=0}^{p-1}h_{jk}\sum_{i=0}^{n-1}\frac{y_i}{\sigma_i}\frac{x_{ik}}{\sigma_i} = \sum_{k=0}^{p-1}h_{jk}\sum_{i=0}^{n-1}b_ia_{ik} -\] -!et -We state without proof the expression for the uncertainty in the parameters $\beta_j$ as (we leave this as an exercise) -!bt -\[ -\sigma^2(\beta_j) = \sum_{i=0}^{n-1}\sigma_i^2\left( \frac{\partial \beta_j}{\partial y_i}\right)^2, -\] -!et -resulting in -!bt -\[ -\sigma^2(\beta_j) = \left(\sum_{k=0}^{p-1}h_{jk}\sum_{i=0}^{n-1}a_{ik}\right)\left(\sum_{l=0}^{p-1}h_{jl}\sum_{m=0}^{n-1}a_{ml}\right) = h_{jj}! -\] -!et - -The first step here is to approximate the function $y$ with a first-order polynomial, that is we write -!bt -\[ -y=y(x) \rightarrow y(x_i) \approx \beta_0+\beta_1 x_i. -\] -!et -By computing the derivatives of $\chi^2$ with respect to $\beta_0$ and $\beta_1$ show that these are given by -!bt -\[ -\frac{\partial \chi^2(\bm{\beta})}{\partial \beta_0} = -2\left[ \frac{1}{n}\sum_{i=0}^{n-1}\left(\frac{y_i-\beta_0-\beta_1x_{i}}{\sigma_i^2}\right)\right]=0, -\] -!et -and -!bt -\[ -\frac{\partial \chi^2(\bm{\beta})}{\partial \beta_1} = -\frac{2}{n}\left[ \sum_{i=0}^{n-1}x_i\left(\frac{y_i-\beta_0-\beta_1x_{i}}{\sigma_i^2}\right)\right]=0. -\] -!et - -For a linear fit (a first-order polynomial) we don't need to invert a matrix!! -Defining -!bt -\[ -\gamma = \sum_{i=0}^{n-1}\frac{1}{\sigma_i^2}, -\] -!et - -!bt -\[ -\gamma_x = \sum_{i=0}^{n-1}\frac{x_{i}}{\sigma_i^2}, -\] -!et - -!bt -\[ -\gamma_y = \sum_{i=0}^{n-1}\left(\frac{y_i}{\sigma_i^2}\right), -\] -!et - -!bt -\[ -\gamma_{xx} = \sum_{i=0}^{n-1}\frac{x_ix_{i}}{\sigma_i^2}, -\] -!et - -!bt -\[ -\gamma_{xy} = \sum_{i=0}^{n-1}\frac{y_ix_{i}}{\sigma_i^2}, -\] -!et - -we obtain - -!bt -\[ -\beta_0 = \frac{\gamma_{xx}\gamma_y-\gamma_x\gamma_y}{\gamma\gamma_{xx}-\gamma_x^2}, -\] -!et - -!bt -\[ -\beta_1 = \frac{\gamma_{xy}\gamma-\gamma_x\gamma_y}{\gamma\gamma_{xx}-\gamma_x^2}. -\] -!et - -This approach (different linear and non-linear regression) suffers -often from both being underdetermined and overdetermined in the -unknown coefficients $\beta_i$. A better approach is to use the -Singular Value Decomposition (SVD) method discussed below. Or using -Lasso and Ridge regression. See below. - - -===== Fitting an Equation of State for Dense Nuclear Matter ===== - -Before we continue, let us introduce yet another example. We are going to fit the -nuclear equation of state using results from many-body calculations. -The equation of state we have made available here, as function of -density, has been derived using modern nucleon-nucleon potentials with -"the addition of three-body -forces":"https://www.sciencedirect.com/science/article/pii/S0370157399001106". This -time the file is presented as a standard _csv_ file. - -The beginning of the Python code here is similar to what you have seen before, -with the same initializations and declarations. We use also _pandas_ -again, rather extensively in order to organize our data. - -The difference now is that we use _Scikit-Learn's_ regression tools -instead of our own matrix inversion implementation. Furthermore, we -sneak in _Ridge_ regression (to be discussed below) which includes a -hyperparameter $\lambda$, also to be explained below. - -!split -===== The code ===== - -!bc pycod -# Common imports -import os -import numpy as np -import pandas as pd -import matplotlib.pyplot as plt -import matplotlib.pyplot as plt -import sklearn.linear_model as skl -from sklearn.metrics import mean_squared_error, r2_score, mean_absolute_error - -# Where to save the figures and data files -PROJECT_ROOT_DIR = "Results" -FIGURE_ID = "Results/FigureFiles" -DATA_ID = "DataFiles/" - -if not os.path.exists(PROJECT_ROOT_DIR): - os.mkdir(PROJECT_ROOT_DIR) - -if not os.path.exists(FIGURE_ID): - os.makedirs(FIGURE_ID) - -if not os.path.exists(DATA_ID): - os.makedirs(DATA_ID) - -def image_path(fig_id): - return os.path.join(FIGURE_ID, fig_id) - -def data_path(dat_id): - return os.path.join(DATA_ID, dat_id) - -def save_fig(fig_id): - plt.savefig(image_path(fig_id) + ".png", format='png') - -infile = open(data_path("EoS.csv"),'r') - -# Read the EoS data as csv file and organize the data into two arrays with density and energies -EoS = pd.read_csv(infile, names=('Density', 'Energy')) -EoS['Energy'] = pd.to_numeric(EoS['Energy'], errors='coerce') -EoS = EoS.dropna() -Energies = EoS['Energy'] -Density = EoS['Density'] -# The design matrix now as function of various polytrops -X = np.zeros((len(Density),4)) -X[:,3] = Density**(4.0/3.0) -X[:,2] = Density -X[:,1] = Density**(2.0/3.0) -X[:,0] = 1 - -# We use now Scikit-Learn's linear regressor and ridge regressor -# OLS part -clf = skl.LinearRegression().fit(X, Energies) -ytilde = clf.predict(X) -EoS['Eols'] = ytilde -# The mean squared error -print("Mean squared error: %.2f" % mean_squared_error(Energies, ytilde)) -# Explained variance score: 1 is perfect prediction -print('Variance score: %.2f' % r2_score(Energies, ytilde)) -# Mean absolute error -print('Mean absolute error: %.2f' % mean_absolute_error(Energies, ytilde)) -print(clf.coef_, clf.intercept_) - -# The Ridge regression with a hyperparameter lambda = 0.1 -_lambda = 0.1 -clf_ridge = skl.Ridge(alpha=_lambda).fit(X, Energies) -yridge = clf_ridge.predict(X) -EoS['Eridge'] = yridge -# The mean squared error -print("Mean squared error: %.2f" % mean_squared_error(Energies, yridge)) -# Explained variance score: 1 is perfect prediction -print('Variance score: %.2f' % r2_score(Energies, yridge)) -# Mean absolute error -print('Mean absolute error: %.2f' % mean_absolute_error(Energies, yridge)) -print(clf_ridge.coef_, clf_ridge.intercept_) - -fig, ax = plt.subplots() -ax.set_xlabel(r'$\rho[\mathrm{fm}^{-3}]$') -ax.set_ylabel(r'Energy per particle') -ax.plot(EoS['Density'], EoS['Energy'], alpha=0.7, lw=2, - label='Theoretical data') -ax.plot(EoS['Density'], EoS['Eols'], alpha=0.7, lw=2, c='m', - label='OLS') -ax.plot(EoS['Density'], EoS['Eridge'], alpha=0.7, lw=2, c='g', - label='Ridge $\lambda = 0.1$') -ax.legend() -save_fig("EoSfitting") -plt.show() -!ec - -The above simple polynomial in density $\rho$ gives an excellent fit -to the data. -We note also that there is a small deviation between the -standard OLS and the Ridge regression at higher densities. We discuss this in more detail -below. - - -===== Splitting our Data in Training and Test data ===== - -It is normal in essentially all Machine Learning studies to split the -data in a training set and a test set (sometimes also an additional -validation set). _Scikit-Learn_ has an own function for this. There -is no explicit recipe for how much data should be included as training -data and say test data. An accepted rule of thumb is to use -approximately $2/3$ to $4/5$ of the data as training data. We will -postpone a discussion of this splitting to the end of these notes and -our discussion of the so-called _bias-variance_ tradeoff. Here we -limit ourselves to repeat the above equation of state fitting example -but now splitting the data into a training set and a test set. - -!bc pycod -import os -import numpy as np -import pandas as pd -import matplotlib.pyplot as plt -from sklearn.model_selection import train_test_split -# Where to save the figures and data files -PROJECT_ROOT_DIR = "Results" -FIGURE_ID = "Results/FigureFiles" -DATA_ID = "DataFiles/" - -if not os.path.exists(PROJECT_ROOT_DIR): - os.mkdir(PROJECT_ROOT_DIR) - -if not os.path.exists(FIGURE_ID): - os.makedirs(FIGURE_ID) - -if not os.path.exists(DATA_ID): - os.makedirs(DATA_ID) - -def image_path(fig_id): - return os.path.join(FIGURE_ID, fig_id) - -def data_path(dat_id): - return os.path.join(DATA_ID, dat_id) - -def save_fig(fig_id): - plt.savefig(image_path(fig_id) + ".png", format='png') - -def R2(y_data, y_model): - return 1 - np.sum((y_data - y_model) ** 2) / np.sum((y_data - np.mean(y_model)) ** 2) -def MSE(y_data,y_model): - n = np.size(y_model) - return np.sum((y_data-y_model)**2)/n - -infile = open(data_path("EoS.csv"),'r') - -# Read the EoS data as csv file and organized into two arrays with density and energies -EoS = pd.read_csv(infile, names=('Density', 'Energy')) -EoS['Energy'] = pd.to_numeric(EoS['Energy'], errors='coerce') -EoS = EoS.dropna() -Energies = EoS['Energy'] -Density = EoS['Density'] -# The design matrix now as function of various polytrops -X = np.zeros((len(Density),5)) -X[:,0] = 1 -X[:,1] = Density**(2.0/3.0) -X[:,2] = Density -X[:,3] = Density**(4.0/3.0) -X[:,4] = Density**(5.0/3.0) -# We split the data in test and training data -X_train, X_test, y_train, y_test = train_test_split(X, Energies, test_size=0.2) -# matrix inversion to find beta -beta = np.linalg.inv(X_train.T.dot(X_train)).dot(X_train.T).dot(y_train) -# and then make the prediction -ytilde = X_train @ beta -print("Training R2") -print(R2(y_train,ytilde)) -print("Training MSE") -print(MSE(y_train,ytilde)) -ypredict = X_test @ beta -print("Test R2") -print(R2(y_test,ypredict)) -print("Test MSE") -print(MSE(y_test,ypredict)) -!ec - - - -===== The singular value decomposition ===== - -The examples we have looked at so far are cases where we normally can -invert the matrix $\bm{X}^T\bm{X}$. Using a polynomial expansion as we -did both for the masses and the fitting of the equation of state, -leads to row vectors of the design matrix which are essentially -orthogonal due to the polynomial character of our model. This may -however not the be case in general and a standard matrix inversion -algorithm based on say LU decomposition may lead to singularities. We will see an example of this below when we try to fit -the coupling constant of the widely used Ising model. -There is however a way to partially circumvent this problem and also gain some insight about the ordinary least squares approach. - -This is given by the _Singular Value Decomposition_ algorithm, perhaps -the most powerful linear algebra algorithm. Let us look at a -different example where we may have problems with the standard matrix -inversion algorithm. Thereafter we dive into the math of the SVD. - - -===== The Ising model ===== - -The one-dimensional Ising model with nearest neighbor interaction, no -external field and a constant coupling constant $J$ is given by - -!bt -\begin{align} - H = -J \sum_{k}^L s_k s_{k + 1}, -\end{align} -!et - -where $s_i \in \{-1, 1\}$ and $s_{N + 1} = s_1$. The number of spins -in the system is determined by $L$. For the one-dimensional system -there is no phase transition. - -We will look at a system of $L = 40$ spins with a coupling constant of -$J = 1$. To get enough training data we will generate 10000 states -with their respective energies. - - -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from mpl_toolkits.axes_grid1 import make_axes_locatable -import seaborn as sns -import scipy.linalg as scl -from sklearn.model_selection import train_test_split -import tqdm -sns.set(color_codes=True) -cmap_args=dict(vmin=-1., vmax=1., cmap='seismic') - -L = 40 -n = int(1e4) - -spins = np.random.choice([-1, 1], size=(n, L)) -J = 1.0 - -energies = np.zeros(n) - -for i in range(n): - energies[i] = - J * np.dot(spins[i], np.roll(spins[i], 1)) -!ec - -Here we use ordinary least squares -regression to predict the energy for the nearest neighbor -one-dimensional Ising model on a ring, i.e., the endpoints wrap -around. We will use linear regression to fit a value for -the coupling constant to achieve this. - -===== Reformulating the problem to suit regression ===== - -A more general form for the one-dimensional Ising model is - -!bt -\begin{align} - H = - \sum_j^L \sum_k^L s_j s_k J_{jk}. -\end{align} -!et - -Here we allow for interactions beyond the nearest neighbors and a state dependent -coupling constant. This latter expression can be formulated as -a matrix-product -!bt -\begin{align} - \bm{H} = \bm{X} J, -\end{align} -!et - -where $X_{jk} = s_j s_k$ and $J$ is a matrix which consists of the -elements $-J_{jk}$. This form of writing the energy fits perfectly -with the form utilized in linear regression, that is - -!bt -\begin{align} - \bm{y} = \bm{X}\bm{\beta} + \bm{\epsilon}, -\end{align} -!et - -We split the data in training and test data as discussed in the previous example - -!bc pycod -X = np.zeros((n, L ** 2)) -for i in range(n): - X[i] = np.outer(spins[i], spins[i]).ravel() -y = energies -X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2) -!ec - - -In the ordinary least squares method we choose the cost function - -!bt -\begin{align} - C(\bm{X}, \bm{\beta})= \frac{1}{n}\left\{(\bm{X}\bm{\beta} - \bm{y})^T(\bm{X}\bm{\beta} - \bm{y})\right\}. -\end{align} -!et - -We then find the extremal point of $C$ by taking the derivative with respect to $\bm{\beta}$ as discussed above. -This yields the expression for $\bm{\beta}$ to be - -!bt -\[ - \bm{\beta} = \frac{\bm{X}^T \bm{y}}{\bm{X}^T \bm{X}}, -\] -!et - -which immediately imposes some requirements on $\bm{X}$ as there must exist -an inverse of $\bm{X}^T \bm{X}$. If the expression we are modeling contains an -intercept, i.e., a constant term, we must make sure that the -first column of $\bm{X}$ consists of $1$. We do this here - -!bc pycod -X_train_own = np.concatenate( - (np.ones(len(X_train))[:, np.newaxis], X_train), - axis=1 -) -X_test_own = np.concatenate( - (np.ones(len(X_test))[:, np.newaxis], X_test), - axis=1 -) -!ec - -!bc pycod -def ols_inv(x: np.ndarray, y: np.ndarray) -> np.ndarray: - return scl.inv(x.T @ x) @ (x.T @ y) -beta = ols_inv(X_train_own, y_train) -!ec - - - -===== Singular Value decomposition ===== - -Doing the inversion directly turns out to be a bad idea since the matrix -$\bm{X}^T\bm{X}$ is singular. An alternative approach is to use the _singular -value decomposition_. Using the definition of the Moore-Penrose -pseudoinverse we can write the equation for $\bm{\beta}$ as - -!bt -\[ - \bm{\beta} = \bm{X}^{+}\bm{y}, -\] -!et - -where the pseudoinverse of $\bm{X}$ is given by - -!bt -\[ - \bm{X}^{+} = \frac{\bm{X}^T}{\bm{X}^T\bm{X}}. -\] -!et - -Using singular value decomposition we can decompose the matrix $\bm{X} = \bm{U}\bm{\Sigma} \bm{V}^T$, -where $\bm{U}$ and $\bm{V}$ are orthogonal(unitary) matrices and $\bm{\Sigma}$ contains the singular values (more details below). -where $X^{+} = V\Sigma^{+} U^T$. This reduces the equation for -$\omega$ to -!bt -\begin{align} - \bm{\beta} = \bm{V}\bm{\Sigma}^{+} \bm{U}^T \bm{y}. -\end{align} -!et - -Note that solving this equation by actually doing the pseudoinverse -(which is what we will do) is not a good idea as this operation scales -as $\mathcal{O}(n^3)$, where $n$ is the number of elements in a -general matrix. Instead, doing $QR$-factorization and solving the -linear system as an equation would reduce this down to -$\mathcal{O}(n^2)$ operations. - - -!bc pycod -def ols_svd(x: np.ndarray, y: np.ndarray) -> np.ndarray: - u, s, v = scl.svd(x) - return v.T @ scl.pinv(scl.diagsvd(s, u.shape[0], v.shape[0])) @ u.T @ y -!ec - -!bc pycod -beta = ols_svd(X_train_own,y_train) -!ec - -When extracting the $J$-matrix we need to make sure that we remove the intercept, as is done here - -!bc pycod -J = beta[1:].reshape(L, L) -!ec - -A way of looking at the coefficients in $J$ is to plot the matrices as images. - - -!bc pycod -fig = plt.figure(figsize=(20, 14)) -im = plt.imshow(J, **cmap_args) -plt.title("OLS", fontsize=18) -plt.xticks(fontsize=18) -plt.yticks(fontsize=18) -cb = fig.colorbar(im) -cb.ax.set_yticklabels(cb.ax.get_yticklabels(), fontsize=18) -plt.show() -!ec -It is interesting to note that OLS -considers both $J_{j, j + 1} = -0.5$ and $J_{j, j - 1} = -0.5$ as -valid matrix elements for $J$. -In our discussion below on hyperparameters and Ridge and Lasso regression we will see that -this problem can be removed, partly and only with Lasso regression. - -In this case our matrix inversion was actually possible. The obvious question now is what is the mathematics behind the SVD? - - - -===== Linear Regression Problems ===== - -One of the typical problems we encounter with linear regression, in particular -when the matrix $\bm{X}$ (our so-called design matrix) is high-dimensional, -are problems with near singular or singular matrices. The column vectors of $\bm{X}$ -may be linearly dependent, normally referred to as super-collinearity. -This means that the matrix may be rank deficient and it is basically impossible to -to model the data using linear regression. As an example, consider the matrix -!bt -\begin{align*} -\mathbf{X} & = \left[ -\begin{array}{rrr} -1 & -1 & 2 -\\ -1 & 0 & 1 -\\ -1 & 2 & -1 -\\ -1 & 1 & 0 -\end{array} \right] -\end{align*} -!et - -The columns of $\bm{X}$ are linearly dependent. We see this easily since the -the first column is the row-wise sum of the other two columns. The rank (more correct, -the column rank) of a matrix is the dimension of the space spanned by the -column vectors. Hence, the rank of $\mathbf{X}$ is equal to the number -of linearly independent columns. In this particular case the matrix has rank 2. - -Super-collinearity of an $(n \times p)$-dimensional design matrix $\mathbf{X}$ implies -that the inverse of the matrix $\bm{X}^T\bm{x}$ (the matrix we need to invert to solve the linear regression equations) is non-invertible. If we have a square matrix that does not have an inverse, we say this matrix singular. The example here demonstrates this -!bt -\begin{align*} -\bm{X} & = \left[ -\begin{array}{rr} -1 & -1 -\\ -1 & -1 -\end{array} \right]. -\end{align*} -!et -We see easily that $\mbox{det}(\bm{X}) = x_{11} x_{22} - x_{12} x_{21} = 1 \times (-1) - 1 \times (-1) = 0$. Hence, $\mathbf{X}$ is singular and its inverse is undefined. -This is equivalent to saying that the matrix $\bm{X}$ has at least an eigenvalue which is zero. - - - -===== Fixing the singularity ===== - -If our design matrix $\bm{X}$ which enters the linear regression problem -!bt -\begin{align} -\bm{\beta} & = (\bm{X}^{T} \bm{X})^{-1} \bm{X}^{T} \bm{y}, -\end{align} -!et -has linearly dependent column vectors, we will not be able to compute the inverse -of $\bm{X}^T\bm{X}$ and we cannot find the parameters (estimators) $\beta_i$. -The estimators are only well-defined if $(\bm{X}^{T}\bm{X})^{-1}$ exits. -This is more likely to happen when the matrix $\bm{X}$ is high-dimensional. In this case it is likely to encounter a situation where -the regression parameters $\beta_i$ cannot be estimated. - -A cheap *ad hoc* approach is simply to add a small diagonal component to the matrix to invert, that is we change -!bt -\[ -\bm{X}^{T} \bm{X} \rightarrow \bm{X}^{T} \bm{X}+\lambda \bm{I}, -\] -!et -where $\bm{I}$ is the identity matrix. When we discuss _Ridge_ regression this is actually what we end up evaluating. The parameter $\lambda$ is called a hyperparameter. More about this later. - - - - -===== Basic math of the SVD ===== - - -From standard linear algebra we know that a square matrix $\bm{X}$ can be diagonalized if and only it is -a so-called "normal matrix":"https://en.wikipedia.org/wiki/Normal_matrix", that is if $\bm{X}\in {\mathbb{R}}^{n\times n}$ -we have $\bm{X}\bm{X}^T=\bm{X}^T\bm{X}$ or if $\bm{X}\in {\mathbb{C}}^{n\times n}$ we have $\bm{X}\bm{X}^{\dagger}=\bm{X}^{\dagger}\bm{X}$. -The matrix has then a set of eigenpairs - -!bt -\[ -(\lambda_1,\bm{u}_1),\dots, (\lambda_n,\bm{u}_n), -!et -and the eigenvalues are given by the diagonal matrix -!bt -\[ -\bm{\Sigma}=\mathrm{Diag}(\lambda_1, \dots,\lambda_n). -\] -!et -The matrix $\bm{X}$ can be written in terms of an orthogonal/unitary transformation $\bm{U}$ -!bt -\[ -\bm{X} = \bm{U}\bm{\Sigma}\bm{V}^T, -\] -!et -with $\bm{U}\bm{U}^T=\bm{I}$ or $\bm{U}\bm{U}^{\dagger}=\bm{I}$. - -Not all square matrices are diagonalizable. A matrix like the one discussed above -!bt -\[ -\bm{X} = \begin{bmatrix} -1& -1 \\ -1& -1\\ -\end{bmatrix} -\] -!et -is not diagonalizable, it is a so-called "defective matrix":"https://en.wikipedia.org/wiki/Defective_matrix". It is easy to see that the condition -$\bm{X}\bm{X}^T=\bm{X}^T\bm{X}$ is not fulfilled. - - - -===== The SVD, a Fantastic Algorithm ===== - - -However, and this is the strength of the SVD algorithm, any general -matrix $\bm{X}$ can be decomposed in terms of a diagonal matrix and -two orthogonal/unitary matrices. The "Singular Value Decompostion -(SVD) theorem":"https://en.wikipedia.org/wiki/Singular_value_decomposition" -states that a general $m\times n$ matrix $\bm{X}$ can be written in -terms of a diagonal matrix $\bm{\Sigma}$ of dimensionality $n\times n$ -and two orthognal matrices $\bm{U}$ and $\bm{V}$, where the first has -dimensionality $m \times m$ and the last dimensionality $n\times n$. -We have then - -!bt -\[ -\bm{X} = \bm{U}\bm{\Sigma}\bm{V}^T -\] -!et - -As an example, the above defective matrix can be decomposed as - -!bt -\[ -\bm{X} = \frac{1}{\sqrt{2}}\begin{bmatrix} 1& 1 \\ 1& -1\\ \end{bmatrix} \begin{bmatrix} 2& 0 \\ 0& 0\\ \end{bmatrix} \frac{1}{\sqrt{2}}\begin{bmatrix} 1& -1 \\ 1& 1\\ \end{bmatrix}=\bm{U}\bm{\Sigma}\bm{V}^T, -\] -!et - -with eigenvalues $\sigma_1=2$ and $\sigma_2=0$. -The SVD exits always! - - - -===== Another Example ===== - -Consider the following matrix which can be SVD decomposed as - -!bt -\[ -\bm{X} = \frac{1}{15}\begin{bmatrix} 14 & 2\\ 4 & 22\\ 16 & 13\end{matrix}=\frac{1}{3}\begin{bmatrix} 1& 2 & 2 \\ 2& -1 & 1\\ 2 & 1& -2\end{bmatrix} \begin{bmatrix} 2& 0 \\ 0& 1\\ 0 & 0\end{bmatrix}\frac{1}{5}\begin{bmatrix} 3& 4 \\ 4& -3\end{bmatrix}=\bm{U}\bm{\Sigma}\bm{V}^T. -\] -!et - -This is a $3\times 2$ matrix which is decomposed in terms of a -$3\times 3$ matrix $\bm{U}$, and a $2\times 2$ matrix $\bm{V}$. It is easy to see -that $\bm{U}$ and $\bm{V}$ are orthogonal (how?). - -And the SVD -decomposition (singular values) gives eigenvalues -$\sigma_i\geq\sigma_{i+1}$ for all $i$ and for dimensions larger than $i=2$, the -eigenvalues (singular values) are zero. - -In the general case, where our design matrix $\bm{X}$ has dimension -$n\times p$, the matrix is thus decomposed into an $n\times n$ -orthogonal matrix $\bm{U}$, a $p\times p$ orthogonal matrix $\bm{V}$ -and a diagonal matrix $\bm{\Sigma}$ with $r=\mathrm{min}(n,p)$ -singular values $\sigma_i\lg 0$ on the main diagonal and zeros filling -the rest of the matrix. There are at most $p$ singular values -assuming that $n > p$. In our regression examples for the nuclear -masses and the equation of state this is indeed the case, while for -the Ising model we have $p > n$. These are often cases that lead to -near singular or singular matrices. - -The columns of $\bm{U}$ are called the left singular vectors while the columns of $\bm{V}$ are the right singular vectors. - - -===== Economy-size SVD ===== - -If we assume that $n > p$, then our matrix $\bm{U}$ has dimension $n -\times n$. The last $n-p$ columns of $\bm{U}$ become however -irrelevant in our calculations since they are multiplied with the -zeros in $\bm{\Sigma}$. - -The economy-size decomposition removes extra rows or columns of zeros -from the diagonal matrix of singular values, $\bm{\Sigma}$, along with the columns -in either $\bm{U}$ or $\bm{V}$ that multiply those zeros in the expression. -Removing these zeros and columns can improve execution time -and reduce storage requirements without compromising the accuracy of -the decomposition. - -If $n > p$, we keep only the first $p$ columns of $\bm{U}$ and $\bm{\Sigma}$ has dimension $p\times p$. -If $p > n$, then only the first $n$ columns of $\bm{V}$ are computed and $\bm{\Sigma}$ has dimension $n\times n$. -The $n=p$ case is obvious, we retain the full SVD. -In general the economy-size SVD leads to less FLOPS and still conserving the desired accuracy. - - -===== Mathematical Properties ===== - -There are several interesting mathematical properties which will be -relevant when we are going to discuss the differences between say -ordinary least squares (OLS) and _Ridge_ regression. - -We have from OLS that the parameters of the linear approximation are given by -!bt -\[ -\bm{\tilde{y}} = \bm{X}\bm{\beta} = \bm{X}\left(\bm{X}^T\bm{X}\right)^{-1}\bm{X}^T\bm{y}. -\] -!et - -The matrix to invert can be rewritten in terms of our SVD decomposition as - -!bt -\[ -\bm{X}^T\bm{X} = \bm{V}\bm{\Sigma}^T\bm{U}^T\bm{U}\bm{\Sigma}\bm{V}^T. -\] -!et -Using the orthogonality properties of $\bm{U}$ we have - -!bt -\[ -\bm{X}^T\bm{X} = \bm{V}\bm{\Sigma}^T\bm{\Sigma}\bm{V}^T = \bm{V}\bm{D}\bm{V}^T, -\] -!et -with $\bm{D}$ being a diagonal matrix with values along the diagonal given by the singular values squared. - -This means that -!bt -\[ -(\bm{X}^T\bm{X})\bm{V} = \bm{V}\bm{D}, -\] -!et -that is the eigenvectors of $(\bm{X}^T\bm{X})$ are given by the columns of the right singular matrix of $\bm{X}$ and the eigenvalues are the squared singular values. It is easy to show (show this) that -!bt -\[ -(\bm{X}\bm{X}^T)\bm{U} = \bm{U}\bm{D}, -\] -!et -that is, the eigenvectors of $(\bm{X}\bm{X})^T$ are the columns of the left singular matrix and the eigenvalues are the same. - -Going back to our OLS equation we have -!bt -\[ -\bm{X}\bm{\beta} = \bm{X}\left(\bm{V}\bm{D}\bm{V}^T \right)^{-1}\bm{X}^T\bm{y}=\bm{U\Sigma V^T}\left(\bm{V}\bm{D}\bm{V}^T \right)^{-1}(\bm{U\Sigma V^T})^T\bm{y}=\bm{U}\bm{U}^T\bm{y}. -\] -!et -We will come back to this expression when we discuss Ridge regression. - - - -===== Ridge and LASSO Regression ===== - -Let us remind ourselves about the expression for the standard Mean Squared Error (MSE) which we used to define our cost function and the equations for the ordinary least squares (OLS) method, that is -our optimization problem is -!bt -\[ -{\displaystyle \min_{\bm{\beta}\in {\mathbb{R}}^{p}}}\frac{1}{n}\left\{\left(\bm{y}-\bm{X}\bm{\beta}\right)^T\left(\bm{y}-\bm{X}\bm{\beta}\right)\right\}. -\] -!et -or we can state it as -!bt -\[ -{\displaystyle \min_{\bm{\beta}\in -{\mathbb{R}}^{p}}}\frac{1}{n}\sum_{i=0}^{n-1}\left(y_i-\tilde{y}_i\right)^2=\frac{1}{n}\vert\vert \bm{y}-\bm{X}\bm{\beta}\vert\vert_2^2, -\] -!et -where we have used the definition of a norm-2 vector, that is -!bt -\[ -\vert\vert \bm{x}\vert\vert_2 = \sqrt{\sum_i x_i^2}. -\] -!et - -By minimizing the above equation with respect to the parameters -$\bm{\beta}$ we could then obtain an analytical expression for the -parameters $\bm{\beta}$. We can add a regularization parameter $\lambda$ by -defining a new cost function to be optimized, that is - -!bt -\[ -{\displaystyle \min_{\bm{\beta}\in -{\mathbb{R}}^{p}}}\frac{1}{n}\vert\vert \bm{y}-\bm{X}\bm{\beta}\vert\vert_2^2+\lambda\vert\vert \bm{\beta}\vert\vert_2^2 -\] -!et - -which leads to the Ridge regression minimization problem where we -require that $\vert\vert \bm{\beta}\vert\vert_2^2\le t$, where $t$ is -a finite number larger than zero. By defining - -!bt -\[ -C(\bm{X},\bm{\beta})=\frac{1}{n}\vert\vert \bm{y}-\bm{X}\bm{\beta}\vert\vert_2^2+\lambda\vert\vert \bm{\beta}\vert\vert_1, -\] -!et - -we have a new optimization equation -!bt -\[ -{\displaystyle \min_{\bm{\beta}\in -{\mathbb{R}}^{p}}}\frac{1}{n}\vert\vert \bm{y}-\bm{X}\bm{\beta}\vert\vert_2^2+\lambda\vert\vert \bm{\beta}\vert\vert_1 -\] -!et -which leads to Lasso regression. Lasso stands for least absolute shrinkage and selection operator. - -Here we have defined the norm-1 as -!bt -\[ -\vert\vert \bm{x}\vert\vert_1 = \sum_i \vert x_i\vert. -\] -!et - -Using the matrix-vector expression for Ridge regression, - -!bt -\[ -C(\bm{X},\bm{\beta})=\frac{1}{n}\left\{(\bm{y}-\bm{X}\bm{\beta})^T(\bm{y}-\bm{X}\bm{\beta})\right\}+\lambda\bm{\beta}^T\bm{\beta}, -\] -!et - -by taking the derivatives with respect to $\bm{\beta}$ we obtain then -a slightly modified matrix inversion problem which for finite values -of $\lambda$ does not suffer from singularity problems. We obtain - -!bt -\[ -\bm{\beta}^{\mathrm{Ridge}} = \left(\bm{X}^T\bm{X}+\lambda\bm{I}\right)^{-1}\bm{X}^T\bm{y}, -\] -!et - -with $\bm{I}$ being a $p\times p$ identity matrix with the constraint that - -!bt -\[ -\sum_{i=0}^{p-1} \beta_i^2 \leq t, -\] -!et - -with $t$ a finite positive number. - -We see that Ridge regression is nothing but the standard -OLS with a modified diagonal term added to $\bm{X}^T\bm{X}$. The -consequences, in particular for our discussion of the bias-variance -are rather interesting. - -Furthermore, if we use the result above in terms of the SVD decomposition (our analysis was done for the OLS method), we had -!bt -\[ -(\bm{X}\bm{X}^T)\bm{U} = \bm{U}\bm{D}. -\] -!et - -We can analyse the OLS solutions in terms of the eigenvectors (the columns) of the right singular value matrix $\bm{U}$ as -!bt -\[ -\bm{X}\bm{\beta} = \bm{X}\left(\bm{V}\bm{D}\bm{V}^T \right)^{-1}\bm{X}^T\bm{y}=\bm{U\Sigma V^T}\left(\bm{V}\bm{D}\bm{V}^T \right)^{-1}(\bm{U\Sigma V^T})^T\bm{y}=\bm{U}\bm{U}^T\bm{y} -\] -!et - - -For Ridge regression this becomes - -!bt -\[ -\bm{X}\bm{\beta}^{\mathrm{Ridge}} = \bm{U\Sigma V^T}\left(\bm{V}\bm{D}\bm{V}^T+\lambda\bm{I} \right)^{-1}(\bm{U\Sigma V^T})^T\bm{y}=\sum_{j=0}^{p-1}\bm{u}_j\bm{u}_j^T\frac{\sigma_j^2}{\sigma_j^2+\lambda}\bm{y}, -\] -!et - -with the vectors $\bm{u}_j$ being the columns of $\bm{U}$. - -===== Interpreting the Ridge results ===== - -Since $\lambda \geq 0$, it means that compared to OLS, we have - -!bt -\[ -\frac{\sigma_j^2}{\sigma_j^2+\lambda} \leq 1. -\] -!et - -Ridge regression finds the coordinates of $\bm{y}$ with respect to the -orthonormal basis $\bm{U}$, it then shrinks the coordinates by -$\frac{\sigma_j^2}{\sigma_j^2+\lambda}$. Recall that the SVD has -eigenvalues ordered in a descending way, that is $\sigma_i \geq -\sigma_{i+1}$. - -For small eigenvalues $\sigma_i$ it means that their contributions become less important, a fact which can be used to reduce the number of degrees of freedom. -Actually, calculating the variance of $\bm{X}\bm{v}_j$ shows that this quantity is equal to $\sigma_j^2/n$. -With a parameter $\lambda$ we can thus shrink the role of specific parameters. - - -For the sake of simplicity, let us assume that the design matrix is orthonormal, that is - -!bt -\[ -\bm{X}^T\bm{X}=(\bm{X}^T\bm{X})^{-1} =\bm{I}. -\] -!et - -In this case the standard OLS results in -!bt -\[ -\bm{\beta}^{\mathrm{OLS}} = \bm{X}^T\bm{y}=\sum_{i=0}^{p-1}\bm{u}_j\bm{u}_j^T\bm{y}, -\] -!et - -and - -!bt -\[ -\bm{\beta}^{\mathrm{Ridge}} = \left(\bm{I}+\lambda\bm{I}\right)^{-1}\bm{X}^T\bm{y}=\left(1+\lambda\right)^{-1}\bm{\beta}^{\mathrm{OLS}}, -\] -!et - -that is the Ridge estimator scales the OLS estimator by the inverse of a factor $1+\lambda$, and -the Ridge estimator converges to zero when the hyperparameter goes to -infinity. - -We will come back to more interpreations after we have gone through some of the statistical analysis part. - -For more discussions of Ridge and Lasso regression, "Wessel van Wieringen's":"https://arxiv.org/abs/1509.09169" article is highly recommended. -Similarly, "Mehta et al's article":"https://arxiv.org/abs/1803.08823" is also recommended. - -===== Where are we going? ===== - -Before we proceed, we need to rethink what we have been doing. In our -eager to fit the data, we have omitted several important elements in -our regression analysis. In what follows we will -o look at statistical properties, including a discussion of mean values, variance and the so-called bias-variance tradeoff -o introduce resampling techniques like cross-validation, bootstrapping and jackknife and more - -This will allow us to link the standard linear algebra methods we have discussed above to a statistical interpretation of the methods. - - - -===== Resampling methods ===== - -Resampling methods are an indispensable tool in modern -statistics. They involve repeatedly drawing samples from a training -set and refitting a model of interest on each sample in order to -obtain additional information about the fitted model. For example, in -order to estimate the variability of a linear regression fit, we can -repeatedly draw different samples from the training data, fit a linear -regression to each new sample, and then examine the extent to which -the resulting fits differ. Such an approach may allow us to obtain -information that would not be available from fitting the model only -once using the original training sample. - - -Resampling approaches can be computationally expensive, because they -involve fitting the same statistical method multiple times using -different subsets of the training data. However, due to recent -advances in computing power, the computational requirements of -resampling methods generally are not prohibitive. In this chapter, we -discuss two of the most commonly used resampling methods, -cross-validation and the bootstrap. Both methods are important tools -in the practical application of many statistical learning -procedures. For example, cross-validation can be used to estimate the -test error associated with a given statistical learning method in -order to evaluate its performance, or to select the appropriate level -of flexibility. The process of evaluating a model’s performance is -known as model assessment, whereas the process of selecting the proper -level of flexibility for a model is known as model selection. The -bootstrap is widely used. - -===== Why resampling methods ? ===== - -* Our simulations can be treated as *computer experiments*. This is particularly the case for Monte Carlo methods -* The results can be analysed with the same statistical tools as we would use analysing experimental data. -* As in all experiments, we are looking for expectation values and an estimate of how accurate they are, i.e., possible sources for errors. - - -* As in other experiments, many numerical experiments have two classes of errors: - * Statistical errors - * Systematical errors -* Statistical errors can be estimated using standard tools from statistics -* Systematical errors are method specific and must be treated differently from case to case. - -===== Statistics ===== - -The *probability distribution function (PDF)* is a function -$p(x)$ on the domain which, in the discrete case, gives us the -probability or relative frequency with which these values of $X$ occur: -!bt -\[ -p(x) = \mathrm{prob}(X=x) -\] -!et -In the continuous case, the PDF does not directly depict the -actual probability. Instead we define the probability for the -stochastic variable to assume any value on an infinitesimal interval -around $x$ to be $p(x)dx$. The continuous function $p(x)$ then gives us -the *density* of the probability rather than the probability -itself. The probability for a stochastic variable to assume any value -on a non-infinitesimal interval $[a,\,b]$ is then just the integral: -!bt -\[ -\mathrm{prob}(a\leq X\leq b) = \int_a^b p(x)dx -\] -!et -Qualitatively speaking, a stochastic variable represents the values of -numbers chosen as if by chance from some specified PDF so that the -selection of a large set of these numbers reproduces this PDF. - -A particularly useful class of special expectation values are the -*moments*. The $n$-th moment of the PDF $p$ is defined as -follows: -!bt -\[ -\langle x^n\rangle \equiv \int\! x^n p(x)\,dx -\] -!et -The zero-th moment $\langle 1\rangle$ is just the normalization condition of -$p$. The first moment, $\langle x\rangle$, is called the *mean* of $p$ -and often denoted by the letter $\mu$: -!bt -\[ -\langle x\rangle = \mu \equiv \int\! x p(x)\,dx -\] -!et - -A special version of the moments is the set of *central moments*, -the n-th central moment defined as: -!bt -\[ -\langle (x-\langle x \rangle )^n\rangle \equiv \int\! (x-\langle x\rangle)^n p(x)\,dx -\] -!et -The zero-th and first central moments are both trivial, equal $1$ and -$0$, respectively. But the second central moment, known as the -*variance* of $p$, is of particular interest. For the stochastic -variable $X$, the variance is denoted as $\sigma^2_X$ or $\mathrm{var}(X)$: -!bt -\begin{align} -\sigma^2_X\ \ =\ \ \mathrm{var}(X) & = \langle (x-\langle x\rangle)^2\rangle = -\int\! (x-\langle x\rangle)^2 p(x)\,dx\\ -& = \int\! \left(x^2 - 2 x \langle x\rangle^{2} + - \langle x\rangle^2\right)p(x)\,dx\\ -& = \langle x^2\rangle - 2 \langle x\rangle\langle x\rangle + \langle x\rangle^2\\ -& = \langle x^2\rangle - \langle x\rangle^2 -\end{align} -!et -The square root of the variance, $\sigma =\sqrt{\langle (x-\langle x\rangle)^2\rangle}$ is called the *standard deviation* of $p$. It is clearly just the RMS (root-mean-square) -value of the deviation of the PDF from its mean value, interpreted -qualitatively as the *spread* of $p$ around its mean. - - - -===== Statistics, covariance ===== - -Another important quantity is the so called covariance, a variant of -the above defined variance. Consider again the set $\{X_i\}$ of $n$ -stochastic variables (not necessarily uncorrelated) with the -multivariate PDF $P(x_1,\dots,x_n)$. The *covariance* of two -of the stochastic variables, $X_i$ and $X_j$, is defined as follows: -!bt -\begin{align} -\mathrm{cov}(X_i,\,X_j) &\equiv \langle (x_i-\langle x_i\rangle)(x_j-\langle x_j\rangle)\rangle -\nonumber\\ -&= -\int\!\cdots\!\int\!(x_i-\langle x_i \rangle)(x_j-\langle x_j \rangle)\, -P(x_1,\dots,x_n)\,dx_1\dots dx_n -label{eq:def_covariance} -\end{align} -!et -with -!bt -\[ -\langle x_i\rangle = -\int\!\cdots\!\int\!x_i\,P(x_1,\dots,x_n)\,dx_1\dots dx_n -\] -!et - -If we consider the above covariance as a matrix $C_{ij}=\mathrm{cov}(X_i,\,X_j)$, then the diagonal elements are just the familiar -variances, $C_{ii} = \mathrm{cov}(X_i,\,X_i) = \mathrm{var}(X_i)$. It turns out that -all the off-diagonal elements are zero if the stochastic variables are -uncorrelated. This is easy to show, keeping in mind the linearity of -the expectation value. Consider the stochastic variables $X_i$ and -$X_j$, ($i\neq j$): -!bt -\begin{align} -\mathrm{cov}(X_i,\,X_j) &= \langle(x_i-\langle x_i\rangle)(x_j-\langle x_j\rangle)\rangle\\ -&=\langle x_i x_j - x_i\langle x_j\rangle - \langle x_i\rangle x_j + \langle x_i\rangle\langle x_j\rangle\rangle \\ -&=\langle x_i x_j\rangle - \langle x_i\langle x_j\rangle\rangle - \langle \langle x_i\rangle x_j\rangle + -\langle \langle x_i\rangle\langle x_j\rangle\rangle\\ -&=\langle x_i x_j\rangle - \langle x_i\rangle\langle x_j\rangle - \langle x_i\rangle\langle x_j\rangle + -\langle x_i\rangle\langle x_j\rangle\\ -&=\langle x_i x_j\rangle - \langle x_i\rangle\langle x_j\rangle -\end{align} -!et - -===== Statistics, independent variables ===== - -If $X_i$ and $X_j$ are independent, we get -$\langle x_i x_j\rangle =\langle x_i\rangle\langle x_j\rangle$, resulting in $\mathrm{cov}(X_i, X_j) = 0\ \ (i\neq j)$. - -Also useful for us is the covariance of linear combinations of -stochastic variables. Let $\{X_i\}$ and $\{Y_i\}$ be two sets of -stochastic variables. Let also $\{a_i\}$ and $\{b_i\}$ be two sets of -scalars. Consider the linear combination: -!bt -\[ -U = \sum_i a_i X_i \qquad V = \sum_j b_j Y_j -\] -!et -By the linearity of the expectation value -!bt -\[ -\mathrm{cov}(U, V) = \sum_{i,j}a_i b_j \mathrm{cov}(X_i, Y_j) -\] -!et - -Now, since the variance is just $\mathrm{var}(X_i) = \mathrm{cov}(X_i, X_i)$, we get -the variance of the linear combination $U = \sum_i a_i X_i$: -!bt -\begin{equation} -\mathrm{var}(U) = \sum_{i,j}a_i a_j \mathrm{cov}(X_i, X_j) -label{eq:variance_linear_combination} -\end{equation} -!et -And in the special case when the stochastic variables are -uncorrelated, the off-diagonal elements of the covariance are as we -know zero, resulting in: -!bt -\[ -\mathrm{var}(U) = \sum_i a_i^2 \mathrm{cov}(X_i, X_i) = \sum_i a_i^2 \mathrm{var}(X_i) -\] -!et -!bt -\[ -\mathrm{var}(\sum_i a_i X_i) = \sum_i a_i^2 \mathrm{var}(X_i) -\] -!et -which will become very useful in our study of the error in the mean -value of a set of measurements. - -===== Statistics and stochastic processes ===== - -A *stochastic process* is a process that produces sequentially a -chain of values: -!bt -\[ -\{x_1, x_2,\dots\,x_k,\dots\}. -\] -!et -We will call these -values our *measurements* and the entire set as our measured -*sample*. The action of measuring all the elements of a sample -we will call a stochastic *experiment* since, operationally, -they are often associated with results of empirical observation of -some physical or mathematical phenomena; precisely an experiment. We -assume that these values are distributed according to some -PDF $p_X^{\phantom X}(x)$, where $X$ is just the formal symbol for the -stochastic variable whose PDF is $p_X^{\phantom X}(x)$. Instead of -trying to determine the full distribution $p$ we are often only -interested in finding the few lowest moments, like the mean -$\mu_X^{\phantom X}$ and the variance $\sigma_X^{\phantom X}$. - -In practical situations a sample is always of finite size. Let that -size be $n$. The expectation value of a sample, the *sample mean*, is then defined as follows: -!bt -\[ -\bar{x}_n \equiv \frac{1}{n}\sum_{k=1}^n x_k -\] -!et -The *sample variance* is: -!bt -\[ -\mathrm{var}(x) \equiv \frac{1}{n}\sum_{k=1}^n (x_k - \bar{x}_n)^2 -\] -!et -its square root being the *standard deviation of the sample*. The -*sample covariance* is: -!bt -\[ -\mathrm{cov}(x)\equiv\frac{1}{n}\sum_{kl}(x_k - \bar{x}_n)(x_l - \bar{x}_n) -\] -!et - -Note that the sample variance is the sample covariance without the -cross terms. In a similar manner as the covariance in Eq.~(ref{eq:def_covariance}) is a measure of the correlation between -two stochastic variables, the above defined sample covariance is a -measure of the sequential correlation between succeeding measurements -of a sample. - -These quantities, being known experimental values, differ -significantly from and must not be confused with the similarly named -quantities for stochastic variables, mean $\mu_X$, variance $\mathrm{var}(X)$ -and covariance $\mathrm{cov}(X,Y)$. - -The law of large numbers -states that as the size of our sample grows to infinity, the sample -mean approaches the true mean $\mu_X^{\phantom X}$ of the chosen PDF: -!bt -\[ -\lim_{n\to\infty}\bar{x}_n = \mu_X^{\phantom X} -\] -!et -The sample mean $\bar{x}_n$ works therefore as an estimate of the true -mean $\mu_X^{\phantom X}$. - -What we need to find out is how good an approximation $\bar{x}_n$ is to -$\mu_X^{\phantom X}$. In any stochastic measurement, an estimated -mean is of no use to us without a measure of its error. A quantity -that tells us how well we can reproduce it in another experiment. We -are therefore interested in the PDF of the sample mean itself. Its -standard deviation will be a measure of the spread of sample means, -and we will simply call it the *error* of the sample mean, or -just sample error, and denote it by $\mathrm{err}_X^{\phantom X}$. In -practice, we will only be able to produce an *estimate* of the -sample error since the exact value would require the knowledge of the -true PDFs behind, which we usually do not have. - -===== Statistics, more on sample error ===== - -Let us first take a look at what happens to the sample error as the -size of the sample grows. In a sample, each of the measurements $x_i$ -can be associated with its own stochastic variable $X_i$. The -stochastic variable $\overline X_n$ for the sample mean $\bar{x}_n$ is -then just a linear combination, already familiar to us: -!bt -\[ -\overline X_n = \frac{1}{n}\sum_{i=1}^n X_i -\] -!et -All the coefficients are just equal $1/n$. The PDF of $\overline X_n$, -denoted by $p_{\overline X_n}(x)$ is the desired PDF of the sample -means. - -The probability density of obtaining a sample mean $\bar x_n$ -is the product of probabilities of obtaining arbitrary values $x_1, -x_2,\dots,x_n$ with the constraint that the mean of the set $\{x_i\}$ -is $\bar x_n$: -!bt -\[ -p_{\overline X_n}(x) = \int p_X^{\phantom X}(x_1)\cdots -\int p_X^{\phantom X}(x_n)\ -\delta\!\left(x - \frac{x_1+x_2+\dots+x_n}{n}\right)dx_n \cdots dx_1 -\] -!et -And in particular we are interested in its variance $\mathrm{var}(\overline X_n)$. - -===== Statistics, central limit theorem ===== - -It is generally not possible to express $p_{\overline X_n}(x)$ in a -closed form given an arbitrary PDF $p_X^{\phantom X}$ and a number -$n$. But for the limit $n\to\infty$ it is possible to make an -approximation. The very important result is called *the central limit theorem*. It tells us that as $n$ goes to infinity, -$p_{\overline X_n}(x)$ approaches a Gaussian distribution whose mean -and variance equal the true mean and variance, $\mu_{X}^{\phantom X}$ -and $\sigma_{X}^{2}$, respectively: -!bt -\begin{equation} -\lim_{n\to\infty} p_{\overline X_n}(x) = -\left(\frac{n}{2\pi\mathrm{var}(X)}\right)^{1/2} -e^{-\frac{n(x-\bar x_n)^2}{2\mathrm{var}(X)}} -label{eq:central_limit_gaussian} -\end{equation} -!et - - -The desired variance -$\mathrm{var}(\overline X_n)$, i.e. the sample error squared -$\mathrm{err}_X^2$, is given by: -!bt -\begin{equation} -\mathrm{err}_X^2 = \mathrm{var}(\overline X_n) = \frac{1}{n^2} -\sum_{ij} \mathrm{cov}(X_i, X_j) -label{eq:error_exact} -\end{equation} -!et -We see now that in order to calculate the exact error of the sample -with the above expression, we would need the true means -$\mu_{X_i}^{\phantom X}$ of the stochastic variables $X_i$. To -calculate these requires that we know the true multivariate PDF of all -the $X_i$. But this PDF is unknown to us, we have only got the measurements of -one sample. The best we can do is to let the sample itself be an -estimate of the PDF of each of the $X_i$, estimating all properties of -$X_i$ through the measurements of the sample. - -Our estimate of $\mu_{X_i}^{\phantom X}$ is then the sample mean $\bar x$ -itself, in accordance with the the central limit theorem: -!bt -\[ -\mu_{X_i}^{\phantom X} = \langle x_i\rangle \approx \frac{1}{n}\sum_{k=1}^n x_k = \bar x -\] -!et -Using $\bar x$ in place of $\mu_{X_i}^{\phantom X}$ we can give an -*estimate* of the covariance in Eq.~(ref{eq:error_exact}) -!bt -\[ -\mathrm{cov}(X_i, X_j) = \langle (x_i-\langle x_i\rangle)(x_j-\langle x_j\rangle)\rangle -\approx\langle (x_i - \bar x)(x_j - \bar{x})\rangle, -\] -!et -resulting in -!bt -\[ -\frac{1}{n} \sum_{l}^n \left(\frac{1}{n}\sum_{k}^n (x_k -\bar x_n)(x_l - \bar x_n)\right)=\frac{1}{n}\frac{1}{n} \sum_{kl} (x_k -\bar x_n)(x_l - \bar x_n)=\frac{1}{n}\mathrm{cov}(x) -\] -!et - -By the same procedure we can use the sample variance as an -estimate of the variance of any of the stochastic variables $X_i$ -!bt -\[ -\mathrm{var}(X_i)=\langle x_i - \langle x_i\rangle\rangle \approx \langle x_i - \bar x_n\rangle\nonumber, -\] -!et -which is approximated as -!bt -\begin{equation} -\mathrm{var}(X_i)\approx \frac{1}{n}\sum_{k=1}^n (x_k - \bar x_n)=\mathrm{var}(x) -label{eq:var_estimate_i_think} -\end{equation} -!et - -Now we can calculate an estimate of the error -$\mathrm{err}_X^{\phantom X}$ of the sample mean $\bar x_n$: -!bt -\begin{align} -\mathrm{err}_X^2 -&=\frac{1}{n^2}\sum_{ij} \mathrm{cov}(X_i, X_j) \nonumber \\ -&\approx&\frac{1}{n^2}\sum_{ij}\frac{1}{n}\mathrm{cov}(x) =\frac{1}{n^2}n^2\frac{1}{n}\mathrm{cov}(x)\nonumber\\ -&=\frac{1}{n}\mathrm{cov}(x) -label{eq:error_estimate} -\end{align} -!et -which is nothing but the sample covariance divided by the number of -measurements in the sample. - -In the special case that the measurements of the sample are -uncorrelated (equivalently the stochastic variables $X_i$ are -uncorrelated) we have that the off-diagonal elements of the covariance -are zero. This gives the following estimate of the sample error: -!bt -\[ -\mathrm{err}_X^2=\frac{1}{n^2}\sum_{ij} \mathrm{cov}(X_i, X_j) = -\frac{1}{n^2} \sum_i \mathrm{var}(X_i), -\] -!et -resulting in -!bt -\begin{equation} -\mathrm{err}_X^2\approx \frac{1}{n^2} \sum_i \mathrm{var}(x)= \frac{1}{n}\mathrm{var}(x) -label{eq:error_estimate_uncorrel} -\end{equation} -!et -where in the second step we have used Eq.~(ref{eq:var_estimate_i_think}). -The error of the sample is then just its standard deviation divided by -the square root of the number of measurements the sample contains. -This is a very useful formula which is easy to compute. It acts as a -first approximation to the error, but in numerical experiments, we -cannot overlook the always present correlations. - -For computational purposes one usually splits up the estimate of -$\mathrm{err}_X^2$, given by Eq.~(ref{eq:error_estimate}), into two -parts -!bt -\[ -\mathrm{err}_X^2 = \frac{1}{n}\mathrm{var}(x) + \frac{1}{n}(\mathrm{cov}(x)-\mathrm{var}(x)), -\] -!et -which equals -!bt -\begin{equation} -\frac{1}{n^2}\sum_{k=1}^n (x_k - \bar x_n)^2 +\frac{2}{n^2}\sum_{k 0$. We say then that the ridge estimator is biased. - -We can also compute the variance as - -!bt -\[ -\mbox{Var}[\bm{\beta}^{\mathrm{Ridge}}]=\sigma^2[ \mathbf{X}^{T} \mathbf{X} + \lambda \mathbf{I} ]^{-1} \mathbf{X}^{T} \mathbf{X} \{ [ \mathbf{X}^{\top} \mathbf{X} + \lambda \mathbf{I} ]^{-1}\}^{T}, -\] -!et -and it is easy to see that if the parameter $\lambda$ goes to infinity then the variance of Ridge parameters $\bm{\beta}$ goes to zero. - -With this, we can compute the difference - -!bt -\[ -\mbox{Var}[\bm{\beta}^{\mathrm{OLS}}]-\mbox{Var}(\bm{\beta}^{\mathrm{Ridge}})=\sigma^2 [ \mathbf{X}^{T} \mathbf{X} + \lambda \mathbf{I} ]^{-1}[ 2\lambda\mathbf{I} + \lambda^2 (\mathbf{X}^{T} \mathbf{X})^{-1} ] \{ [ \mathbf{X}^{T} \mathbf{X} + \lambda \mathbf{I} ]^{-1}\}^{T}. -\] -!et -The difference is non-negative definite since each component of the -matrix product is non-negative definite. -This means the variance we obtain with the standard OLS will always for $\lambda > 0$ be larger than the variance of $\bm{\beta}$ obtained with the Ridge estimator. This has interesting consequences when we discuss the so-called bias-variance trade-off below. - - -===== Cross-validation ===== - -Instead of choosing the penalty parameter to balance model fit with -model complexity, cross-validation requires it (i.e. the penalty -parameter) to yield a model with good prediction -performance. Commonly, this performance is evaluated on novel -data. Novel data need not be easy to come by and one has to make do -with the data at hand. - -The setting of _original_ and novel data is -then mimicked by sample splitting: the data set is divided into two -(groups of samples). One of these two data sets, called the -*training set*, plays the role of _original_ data on which the model is -built. The second of these data sets, called the *test set*, plays the -role of the _novel_ data and is used to evaluate the prediction -performance (often operationalized as the log-likelihood or the -prediction error or its square or the R2 score) of the model built on the training data set. This -procedure (model building and prediction evaluation on training and -test set, respectively) is done for a collection of possible penalty -parameter choices. The penalty parameter that yields the model with -the best prediction performance is to be preferred. The thus obtained -performance evaluation depends on the actual split of the data set. To -remove this dependence the data set is split many times into a -training and test set. For each split the model parameters are -estimated for all choices of $\lambda$ using the training data and -estimated parameters are evaluated on the corresponding test set. The -penalty parameter that on average over the test sets performs best (in -some sense) is then selected. - - - -===== Computationally expensive ===== - -The validation set approach is conceptually simple and is easy to implement. But it has two potential drawbacks: - -* The validation estimate of the test error rate can be highly variable, depending on precisely which observations are included in the training set and which observations are included in the validation set. - -* In the validation approach, only a subset of the observations, those that are included in the training set rather than in the validation set are used to fit the model. Since statistical methods tend to perform worse when trained on fewer observations, this suggests that the validation set error rate may tend to overestimate the test error rate for the model fit on the entire data set. - - - - -===== Various steps in cross-validation ===== - -When the repetitive splitting of the data set is done randomly, -samples may accidently end up in a fast majority of the splits in -either training or test set. Such samples may have an unbalanced -influence on either model building or prediction evaluation. To avoid -this $k$-fold cross-validation structures the data splitting. The -samples are divided into $k$ more or less equally sized exhaustive and -mutually exclusive subsets. In turn (at each split) one of these -subsets plays the role of the test set while the union of the -remaining subsets constitutes the training set. Such a splitting -warrants a balanced representation of each sample in both training and -test set over the splits. Still the division into the $k$ subsets -involves a degree of randomness. This may be fully excluded when -choosing $k=n$. This particular case is referred to as leave-one-out -cross-validation (LOOCV). - - -===== How to set up the cross-validation for Ridge and/or Lasso ===== - -* Define a range of interest for the penalty parameter. - -* Divide the data set into training and test set comprising samples $\{1, \ldots, n\} \setminus i$ and $\{ i \}$, respectively. - -* Fit the linear regression model by means of ridge estimation for each $\lambda$ in the grid using the training set, and the corresponding estimate of the error variance $\bm{\sigma}_{-i}^2(\lambda)$, as -!bt -\begin{align*} -\bm{\beta}_{-i}(\lambda) & = ( \bm{X}_{-i, \ast}^{T} -\bm{X}_{-i, \ast} + \lambda \bm{I}_{pp})^{-1} -\bm{X}_{-i, \ast}^{T} \bm{y}_{-i} -\end{align*} -!et - -* Evaluate the prediction performance of these models on the test set by $\log\{L[y_i, \bm{X}_{i, \ast}; \bm{\beta}_{-i}(\lambda), \bm{\sigma}_{-i}^2(\lambda)]\}$. Or, by the prediction error $|y_i - \bm{X}_{i, \ast} \bm{\beta}_{-i}(\lambda)|$, the relative error, the error squared or the R2 score function. - -* Repeat the first three steps such that each sample plays the role of the test set once. - -* Average the prediction performances of the test sets at each grid point of the penalty bias/parameter by computing the *cross-validated log-likelihood*. It is an estimate of the prediction performance of the model corresponding to this value of the penalty parameter on novel data. It is defined as -!bt -\begin{align*} -\frac{1}{n} \sum_{i = 1}^n \log\{L[y_i, \mathbf{X}_{i, \ast}; \bm{\beta}_{-i}(\lambda), \bm{\sigma}_{-i}^2(\lambda)]\}. -\end{align*} -!et - -* The value of the penalty parameter that maximizes the cross-validated log-likelihood is the value of choice. Or we can use the MSE or the R2 score functions. - - - - -===== Resampling methods: Jackknife and Bootstrap ===== - -Two famous -resampling methods are the _independent bootstrap_ and _the jackknife_. - -The jackknife is a special case of the independent bootstrap. Still, the jackknife was made -popular prior to the independent bootstrap. And as the popularity of -the independent bootstrap soared, new variants, such as _the dependent bootstrap_. - -The Jackknife and independent bootstrap work for -independent, identically distributed random variables. -If these conditions are not -satisfied, the methods will fail. Yet, it should be said that if the data are -independent, identically distributed, and we only want to estimate the -variance of $\overline{X}$ (which often is the case), then there is no -need for bootstrapping. - - -===== Resampling methods: Jackknife ===== - -The Jackknife works by making many replicas of the estimator $\widehat{\theta}$. -The jackknife is a resampling method where we systematically leave out one observation from the vector of observed values $\bm{x} = (x_1,x_2,\cdots,X_n)$. -Let $\bm{x}_i$ denote the vector -!bt -\[ -\bm{x}_i = (x_1,x_2,\cdots,x_{i-1},x_{i+1},\cdots,x_n), -\] -!et - -which equals the vector $\bm{x}$ with the exception that observation -number $i$ is left out. Using this notation, define -$\widehat{\theta}_i$ to be the estimator -$\widehat{\theta}$ computed using $\vec{X}_i$. - - - -===== Jackknife code example ===== -!bc pycod -from numpy import * -from numpy.random import randint, randn -from time import time - -def jackknife(data, stat): - n = len(data);t = zeros(n); inds = arange(n); t0 = time() - ## 'jackknifing' by leaving out an observation for each i - for i in range(n): - t[i] = stat(delete(data,i) ) - - # analysis - print("Runtime: %g sec" % (time()-t0)); print("Jackknife Statistics :") - print("original bias std. error") - print("%8g %14g %15g" % (stat(data),(n-1)*mean(t)/n, (n*var(t))**.5)) - - return t - - -# Returns mean of data samples -def stat(data): - return mean(data) - - -mu, sigma = 100, 15 -datapoints = 10000 -x = mu + sigma*random.randn(datapoints) -# jackknife returns the data sample -t = jackknife(x, stat) - -!ec - - - -===== Resampling methods: Bootstrap ===== - -Bootstrapping is a nonparametric approach to statistical inference -that substitutes computation for more traditional distributional -assumptions and asymptotic results. Bootstrapping offers a number of -advantages: -o The bootstrap is quite general, although there are some cases in which it fails. -o Because it does not require distributional assumptions (such as normally distributed errors), the bootstrap can provide more accurate inferences when the data are not well behaved or when the sample size is small. -o It is possible to apply the bootstrap to statistics with sampling distributions that are difficult to derive, even asymptotically. -o It is relatively simple to apply the bootstrap to complex data-collection plans (such as stratified and clustered samples). - - - - -===== Resampling methods: Bootstrap background ===== - -Since $\widehat{\theta} = \widehat{\theta}(\bm{X})$ is a function of random variables, -$\widehat{\theta}$ itself must be a random variable. Thus it has -a pdf, call this function $p(\bm{t})$. The aim of the bootstrap is to -estimate $p(\bm{t})$ by the relative frequency of -$\widehat{\theta}$. You can think of this as using a histogram -in the place of $p(\bm{t})$. If the relative frequency closely -resembles $p(\vec{t})$, then using numerics, it is straight forward to -estimate all the interesting parameters of $p(\bm{t})$ using point -estimators. - - - -===== Resampling methods: More Bootstrap background ===== - -In the case that $\widehat{\theta}$ has -more than one component, and the components are independent, we use the -same estimator on each component separately. If the probability -density function of $X_i$, $p(x)$, had been known, then it would have -been straight forward to do this by: -o Drawing lots of numbers from $p(x)$, suppose we call one such set of numbers $(X_1^*, X_2^*, \cdots, X_n^*)$. -o Then using these numbers, we could compute a replica of $\widehat{\theta}$ called $\widehat{\theta}^*$. - -By repeated use of (1) and (2), many -estimates of $\widehat{\theta}$ could have been obtained. The -idea is to use the relative frequency of $\widehat{\theta}^*$ -(think of a histogram) as an estimate of $p(\bm{t})$. - - -===== Resampling methods: Bootstrap approach ===== - -But -unless there is enough information available about the process that -generated $X_1,X_2,\cdots,X_n$, $p(x)$ is in general -unknown. Therefore, "Efron in 1979":"https://projecteuclid.org/euclid.aos/1176344552" asked the -question: What if we replace $p(x)$ by the relative frequency -of the observation $X_i$; if we draw observations in accordance with -the relative frequency of the observations, will we obtain the same -result in some asymptotic sense? The answer is yes. - - -Instead of generating the histogram for the relative -frequency of the observation $X_i$, just draw the values -$(X_1^*,X_2^*,\cdots,X_n^*)$ with replacement from the vector -$\bm{X}$. - - -===== Resampling methods: Bootstrap steps ===== - -The independent bootstrap works like this: - -o Draw with replacement $n$ numbers for the observed variables $\bm{x} = (x_1,x_2,\cdots,x_n)$. -o Define a vector $\bm{x}^*$ containing the values which were drawn from $\bm{x}$. -o Using the vector $\bm{x}^*$ compute $\widehat{\theta}^*$ by evaluating $\widehat \theta$ under the observations $\bm{x}^*$. -o Repeat this process $k$ times. - -When you are done, you can draw a histogram of the relative frequency -of $\widehat \theta^*$. This is your estimate of the probability -distribution $p(t)$. Using this probability distribution you can -estimate any statistics thereof. In principle you never draw the -histogram of the relative frequency of $\widehat{\theta}^*$. Instead -you use the estimators corresponding to the statistic of interest. For -example, if you are interested in estimating the variance of $\widehat -\theta$, apply the etsimator $\widehat \sigma^2$ to the values -$\widehat \theta ^*$. - - - -===== Code example for the Bootstrap method ===== - -The following code starts with a Gaussian distribution with mean value -$\mu =100$ and variance $\sigma=15$. We use this to generate the data -used in the bootstrap analysis. The bootstrap analysis returns a data -set after a given number of bootstrap operations (as many as we have -data points). This data set consists of estimated mean values for each -bootstrap operation. The histogram generated by the bootstrap method -shows that the distribution for these mean values is also a Gaussian, -centered around the mean value $\mu=100$ but with standard deviation -$\sigma/\sqrt{n}$, where $n$ is the number of bootstrap samples (in -this case the same as the number of original data points). The value -of the standard deviation is what we expect from the central limit -theorem. - - -!bc pycod -from numpy import * -from numpy.random import randint, randn -from time import time -import matplotlib.mlab as mlab -import matplotlib.pyplot as plt - -# Returns mean of bootstrap samples -def stat(data): - return mean(data) - -# Bootstrap algorithm -def bootstrap(data, statistic, R): - t = zeros(R); n = len(data); inds = arange(n); t0 = time() - # non-parametric bootstrap - for i in range(R): - t[i] = statistic(data[randint(0,n,n)]) - - # analysis - print("Runtime: %g sec" % (time()-t0)); print("Bootstrap Statistics :") - print("original bias std. error") - print("%8g %8g %14g %15g" % (statistic(data), std(data),mean(t),std(t))) - return t - - -mu, sigma = 100, 15 -datapoints = 10000 -x = mu + sigma*random.randn(datapoints) -# bootstrap returns the data sample -t = bootstrap(x, stat, datapoints) -# the histogram of the bootstrapped data -n, binsboot, patches = plt.hist(t, 50, normed=1, facecolor='red', alpha=0.75) - -# add a 'best fit' line -y = mlab.normpdf( binsboot, mean(t), std(t)) -lt = plt.plot(binsboot, y, 'r--', linewidth=1) -plt.xlabel('Smarts') -plt.ylabel('Probability') -plt.axis([99.5, 100.6, 0, 3.0]) -plt.grid(True) - -plt.show() - -!ec - - - -===== Code Example for Cross-validation and $k$-fold Cross-validation ===== - -The code here uses Ridge regression with cross-validation (CV) resampling and $k$-fold CV in order to fit a specific polynomial. -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from sklearn.model_selection import KFold -from sklearn.linear_model import Ridge -from sklearn.model_selection import cross_val_score -from sklearn.preprocessing import PolynomialFeatures - -# A seed just to ensure that the random numbers are the same for every run. -# Useful for eventual debugging. -np.random.seed(3155) - -# Generate the data. -nsamples = 100 -x = np.random.randn(nsamples) -y = 3*x**2 + np.random.randn(nsamples) - -## Cross-validation on Ridge regression using KFold only - -# Decide degree on polynomial to fit -poly = PolynomialFeatures(degree = 6) - -# Decide which values of lambda to use -nlambdas = 500 -lambdas = np.logspace(-3, 5, nlambdas) - -# Initialize a KFold instance -k = 5 -kfold = KFold(n_splits = k) - -# Perform the cross-validation to estimate MSE -scores_KFold = np.zeros((nlambdas, k)) - -i = 0 -for lmb in lambdas: - ridge = Ridge(alpha = lmb) - j = 0 - for train_inds, test_inds in kfold.split(x): - xtrain = x[train_inds] - ytrain = y[train_inds] - - xtest = x[test_inds] - ytest = y[test_inds] - - Xtrain = poly.fit_transform(xtrain[:, np.newaxis]) - ridge.fit(Xtrain, ytrain[:, np.newaxis]) - - Xtest = poly.fit_transform(xtest[:, np.newaxis]) - ypred = ridge.predict(Xtest) - - scores_KFold[i,j] = np.sum((ypred - ytest[:, np.newaxis])**2)/np.size(ypred) - - j += 1 - i += 1 - - -estimated_mse_KFold = np.mean(scores_KFold, axis = 1) - -## Cross-validation using cross_val_score from sklearn along with KFold - -# kfold is an instance initialized above as: -# kfold = KFold(n_splits = k) - -estimated_mse_sklearn = np.zeros(nlambdas) -i = 0 -for lmb in lambdas: - ridge = Ridge(alpha = lmb) - - X = poly.fit_transform(x[:, np.newaxis]) - estimated_mse_folds = cross_val_score(ridge, X, y[:, np.newaxis], scoring='neg_mean_squared_error', cv=kfold) - - # cross_val_score return an array containing the estimated negative mse for every fold. - # we have to the the mean of every array in order to get an estimate of the mse of the model - estimated_mse_sklearn[i] = np.mean(-estimated_mse_folds) - - i += 1 - -## Plot and compare the slightly different ways to perform cross-validation - -plt.figure() - -plt.plot(np.log10(lambdas), estimated_mse_sklearn, label = 'cross_val_score') -plt.plot(np.log10(lambdas), estimated_mse_KFold, 'r--', label = 'KFold') - -plt.xlabel('log10(lambda)') -plt.ylabel('mse') - -plt.legend() - -plt.show() - -!ec - - - -===== The bias-variance tradeoff ===== - - -We will discuss the bias-variance tradeoff in the context of -continuous predictions such as regression. However, many of the -intuitions and ideas discussed here also carry over to classification -tasks. Consider a dataset $\mathcal{L}$ consisting of the data -$\mathbf{X}_\mathcal{L}=\{(y_j, \boldsymbol{x}_j), j=0\ldots n-1\}$. - -Let us assume that the true data is generated from a noisy model - -!bt -\[ -\bm{y}=f(\boldsymbol{x}) + \bm{\epsilon} -\] -!et - -where $\epsilon$ is normally distributed with mean zero and standard deviation $\sigma^2$. - -In our derivation of the ordinary least squares method we defined then -an approximation to the function $f$ in terms of the parameters -$\bm{\beta}$ and the design matrix $\bm{X}$ which embody our model, -that is $\bm{\tilde{y}}=\bm{X}\bm{\beta}$. - -Thereafter we found the parameters $\bm{\beta}$ by optimizing the means squared error via the so-called cost function -!bt -\[ -C(\bm{X},\bm{\beta}) =\frac{1}{n}\sum_{i=0}^{n-1}(y_i-\tilde{y}_i)^2=\mathbb{E}\left[(\bm{y}-\bm{\tilde{y}})^2\right]. -\] -!et - -We can rewrite this as -!bt -\[ -\mathbb{E}\left[(\bm{y}-\bm{\tilde{y}})^2\right]=\frac{1}{n}\sum_i(f_i-\mathbb{E}\left[\bm{\tilde{y}}\right])^2+\frac{1}{n}\sum_i(\tilde{y}_i-\mathbb{E}\left[\bm{\tilde{y}}\right])^2+\sigma^2. -\] -!et - -The three terms represent the square of the bias of the learning -method, which can be thought of as the error caused by the simplifying -assumptions built into the method. The second term represents the -variance of the chosen model and finally the last terms is variance of -the error $\bm{\epsilon}$. - -To derive this equation, we need to recall that the variance of $\bm{y}$ and $\bm{\epsilon}$ are both equal to $\sigma^2$. The mean value of $\bm{\epsilon}$ is by definition equal to zero. Furthermore, the function $f$ is not a stochastics variable, idem for $\bm{\tilde{y}}$. -We use a more compact notation in terms of the expectation value -!bt -\[ -\mathbb{E}\left[(\bm{y}-\bm{\tilde{y}})^2\right]=\mathbb{E}\left[(\bm{f}+\bm{\epsilon}-\bm{\tilde{y}})^2\right], -\] -!et -and adding and subtracting $\mathbb{E}\left[\bm{\tilde{y}}\right]$ we get -!bt -\[ -\mathbb{E}\left[(\bm{y}-\bm{\tilde{y}})^2\right]=\mathbb{E}\left[(\bm{f}+\bm{\epsilon}-\bm{\tilde{y}}+\mathbb{E}\left[\bm{\tilde{y}}\right]-\mathbb{E}\left[\bm{\tilde{y}}\right])^2\right], -\] -!et -which, using the abovementioned expectation values can be rewritten as -!bt -\[ -\mathbb{E}\left[(\bm{y}-\bm{\tilde{y}})^2\right]=\mathbb{E}\left[(\bm{y}-\mathbb{E}\left[\bm{\tilde{y}}\right])^2\right]+\mathrm{Var}\left[\bm{\tilde{y}}\right]+\sigma^2, -\] -!et -that is the rewriting in terms of the so-called bias, the variance of the model $\bm{\tilde{y}}$ and the variance of $\bm{\epsilon}$. - - - - - -===== Example code for Bias-Variance tradeoff ===== -!bc pycod -import matplotlib.pyplot as plt -import numpy as np -from sklearn.linear_model import LinearRegression, Ridge, Lasso -from sklearn.preprocessing import PolynomialFeatures -from sklearn.model_selection import train_test_split -from sklearn.pipeline import make_pipeline -from sklearn.utils import resample - -np.random.seed(2018) - -n = 500 -n_boostraps = 100 -degree = 18 # A quite high value, just to show. -noise = 0.1 - -# Make data set. -x = np.linspace(-1, 3, n).reshape(-1, 1) -y = np.exp(-x**2) + 1.5 * np.exp(-(x-2)**2) + np.random.normal(0, 0.1, x.shape) - -# Hold out some test data that is never used in training. -x_train, x_test, y_train, y_test = train_test_split(x, y, test_size=0.2) - -# Combine x transformation and model into one operation. -# Not neccesary, but convenient. -model = make_pipeline(PolynomialFeatures(degree=degree), LinearRegression(fit_intercept=False)) - -# The following (m x n_bootstraps) matrix holds the column vectors y_pred -# for each bootstrap iteration. -y_pred = np.empty((y_test.shape[0], n_boostraps)) -for i in range(n_boostraps): - x_, y_ = resample(x_train, y_train) - - # Evaluate the new model on the same test data each time. - y_pred[:, i] = model.fit(x_, y_).predict(x_test).ravel() - -# Note: Expectations and variances taken w.r.t. different training -# data sets, hence the axis=1. Subsequent means are taken across the test data -# set in order to obtain a total value, but before this we have error/bias/variance -# calculated per data point in the test set. -# Note 2: The use of keepdims=True is important in the calculation of bias as this -# maintains the column vector form. Dropping this yields very unexpected results. -error = np.mean( np.mean((y_test - y_pred)**2, axis=1, keepdims=True) ) -bias = np.mean( (y_test - np.mean(y_pred, axis=1, keepdims=True))**2 ) -variance = np.mean( np.var(y_pred, axis=1, keepdims=True) ) -print('Error:', error) -print('Bias^2:', bias) -print('Var:', variance) -print('{} >= {} + {} = {}'.format(error, bias, variance, bias+variance)) - -plt.plot(x[::5, :], y[::5, :], label='f(x)') -plt.scatter(x_test, y_test, label='Data points') -plt.scatter(x_test, np.mean(y_pred, axis=1), label='Pred') -plt.legend() -plt.show() - -!ec - - - -===== Understanding what happens ===== -!bc pycod -import matplotlib.pyplot as plt -import numpy as np -from sklearn.linear_model import LinearRegression, Ridge, Lasso -from sklearn.preprocessing import PolynomialFeatures -from sklearn.model_selection import train_test_split -from sklearn.pipeline import make_pipeline -from sklearn.utils import resample - -np.random.seed(2018) - -n = 40 -n_boostraps = 100 -maxdegree = 14 - - -# Make data set. -x = np.linspace(-3, 3, n).reshape(-1, 1) -y = np.exp(-x**2) + 1.5 * np.exp(-(x-2)**2)+ np.random.normal(0, 0.1, x.shape) -error = np.zeros(maxdegree) -bias = np.zeros(maxdegree) -variance = np.zeros(maxdegree) -polydegree = np.zeros(maxdegree) -x_train, x_test, y_train, y_test = train_test_split(x, y, test_size=0.2) - -for degree in range(maxdegree): - model = make_pipeline(PolynomialFeatures(degree=degree), LinearRegression(fit_intercept=False)) - y_pred = np.empty((y_test.shape[0], n_boostraps)) - for i in range(n_boostraps): - x_, y_ = resample(x_train, y_train) - y_pred[:, i] = model.fit(x_, y_).predict(x_test).ravel() - - polydegree[degree] = degree - error[degree] = np.mean( np.mean((y_test - y_pred)**2, axis=1, keepdims=True) ) - bias[degree] = np.mean( (y_test - np.mean(y_pred, axis=1, keepdims=True))**2 ) - variance[degree] = np.mean( np.var(y_pred, axis=1, keepdims=True) ) - print('Polynomial degree:', degree) - print('Error:', error[degree]) - print('Bias^2:', bias[degree]) - print('Var:', variance[degree]) - print('{} >= {} + {} = {}'.format(error[degree], bias[degree], variance[degree], bias[degree]+variance[degree])) - -plt.plot(polydegree, np.log10(error), label='Error') -plt.plot(polydegree, bias, label='bias') -plt.plot(polydegree, variance, label='Variance') -plt.legend() -plt.show() - - - - -!ec - - -===== Summing up ===== - - - - -The bias-variance tradeoff summarizes the fundamental tension in -machine learning, particularly supervised learning, between the -complexity of a model and the amount of training data needed to train -it. Since data is often limited, in practice it is often useful to -use a less-complex model with higher bias, that is a model whose asymptotic -performance is worse than another model because it is easier to -train and less sensitive to sampling noise arising from having a -finite-sized training dataset (smaller variance). - - - -The above equations tell us that in -order to minimize the expected test error, we need to select a -statistical learning method that simultaneously achieves low variance -and low bias. Note that variance is inherently a nonnegative quantity, -and squared bias is also nonnegative. Hence, we see that the expected -test MSE can never lie below $Var(\epsilon)$, the irreducible error. - - -What do we mean by the variance and bias of a statistical learning -method? The variance refers to the amount by which our model would change if we -estimated it using a different training data set. Since the training -data are used to fit the statistical learning method, different -training data sets will result in a different estimate. But ideally the -estimate for our model should not vary too much between training -sets. However, if a method has high variance then small changes in -the training data can result in large changes in the model. In general, more -flexible statistical methods have higher variance. - - - -===== Another Example rom Scikit-Learn's Repository ===== -!bc pycod -""" -============================ -Underfitting vs. Overfitting -============================ - -This example demonstrates the problems of underfitting and overfitting and -how we can use linear regression with polynomial features to approximate -nonlinear functions. The plot shows the function that we want to approximate, -which is a part of the cosine function. In addition, the samples from the -real function and the approximations of different models are displayed. The -models have polynomial features of different degrees. We can see that a -linear function (polynomial with degree 1) is not sufficient to fit the -training samples. This is called **underfitting**. A polynomial of degree 4 -approximates the true function almost perfectly. However, for higher degrees -the model will **overfit** the training data, i.e. it learns the noise of the -training data. -We evaluate quantitatively **overfitting** / **underfitting** by using -cross-validation. We calculate the mean squared error (MSE) on the validation -set, the higher, the less likely the model generalizes correctly from the -training data. -""" - -print(__doc__) - -import numpy as np -import matplotlib.pyplot as plt -from sklearn.pipeline import Pipeline -from sklearn.preprocessing import PolynomialFeatures -from sklearn.linear_model import LinearRegression -from sklearn.model_selection import cross_val_score - - -def true_fun(X): - return np.cos(1.5 * np.pi * X) - -np.random.seed(0) - -n_samples = 30 -degrees = [1, 4, 15] - -X = np.sort(np.random.rand(n_samples)) -y = true_fun(X) + np.random.randn(n_samples) * 0.1 - -plt.figure(figsize=(14, 5)) -for i in range(len(degrees)): - ax = plt.subplot(1, len(degrees), i + 1) - plt.setp(ax, xticks=(), yticks=()) - - polynomial_features = PolynomialFeatures(degree=degrees[i], - include_bias=False) - linear_regression = LinearRegression() - pipeline = Pipeline([("polynomial_features", polynomial_features), - ("linear_regression", linear_regression)]) - pipeline.fit(X[:, np.newaxis], y) - - # Evaluate the models using crossvalidation - scores = cross_val_score(pipeline, X[:, np.newaxis], y, - scoring="neg_mean_squared_error", cv=10) - - X_test = np.linspace(0, 1, 100) - plt.plot(X_test, pipeline.predict(X_test[:, np.newaxis]), label="Model") - plt.plot(X_test, true_fun(X_test), label="True function") - plt.scatter(X, y, edgecolor='b', s=20, label="Samples") - plt.xlabel("x") - plt.ylabel("y") - plt.xlim((0, 1)) - plt.ylim((-2, 2)) - plt.legend(loc="best") - plt.title("Degree {}\nMSE = {:.2e}(+/- {:.2e})".format( - degrees[i], -scores.mean(), scores.std())) -plt.show() -!ec - - - - -===== The one-dimensional Ising model ===== - -Let us bring back the Ising model again, but now with an additional -focus on Ridge and Lasso regression as well. We repeat some of the -basic parts of the Ising model and the setup of the training and test -data. The one-dimensional Ising model with nearest neighbor -interaction, no external field and a constant coupling constant $J$ is -given by - -!bt -\begin{align} - H = -J \sum_{k}^L s_k s_{k + 1}, -\end{align} -!et -where $s_i \in \{-1, 1\}$ and $s_{N + 1} = s_1$. The number of spins in the system is determined by $L$. For the one-dimensional system there is no phase transition. - -We will look at a system of $L = 40$ spins with a coupling constant of $J = 1$. To get enough training data we will generate 10000 states with their respective energies. - - -!bc pycod -import numpy as np -import matplotlib.pyplot as plt -from mpl_toolkits.axes_grid1 import make_axes_locatable -import seaborn as sns -import scipy.linalg as scl -from sklearn.model_selection import train_test_split -import sklearn.linear_model as skl -import tqdm -sns.set(color_codes=True) -cmap_args=dict(vmin=-1., vmax=1., cmap='seismic') - -L = 40 -n = int(1e4) - -spins = np.random.choice([-1, 1], size=(n, L)) -J = 1.0 - -energies = np.zeros(n) - -for i in range(n): - energies[i] = - J * np.dot(spins[i], np.roll(spins[i], 1)) -!ec - -A more general form for the one-dimensional Ising model is - -!bt -\begin{align} - H = - \sum_j^L \sum_k^L s_j s_k J_{jk}. -\end{align} -!et - -Here we allow for interactions beyond the nearest neighbors and a more -adaptive coupling matrix. This latter expression can be formulated as -a matrix-product on the form -!bt -\begin{align} - H = X J, -\end{align} -!et - -where $X_{jk} = s_j s_k$ and $J$ is the matrix consisting of the -elements $-J_{jk}$. This form of writing the energy fits perfectly -with the form utilized in linear regression, viz. -!bt -\begin{align} - \bm{y} = \bm{X}\bm{\beta} + \bm{\epsilon}. -\end{align} -!et -We organize the data as we did above -!bc pycod -X = np.zeros((n, L ** 2)) -for i in range(n): - X[i] = np.outer(spins[i], spins[i]).ravel() -y = energies -X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.96) - -X_train_own = np.concatenate( - (np.ones(len(X_train))[:, np.newaxis], X_train), - axis=1 -) - -X_test_own = np.concatenate( - (np.ones(len(X_test))[:, np.newaxis], X_test), - axis=1 -) -!ec - -We will do all fitting with _Scikit-Learn_, - -!bc pycod -clf = skl.LinearRegression().fit(X_train, y_train) -!ec -When extracting the $J$-matrix we make sure to remove the intercept -!bc pycod -J_sk = clf.coef_.reshape(L, L) -!ec -And then we plot the results -!bc pycod -fig = plt.figure(figsize=(20, 14)) -im = plt.imshow(J_sk, **cmap_args) -plt.title("LinearRegression from Scikit-learn", fontsize=18) -plt.xticks(fontsize=18) -plt.yticks(fontsize=18) -cb = fig.colorbar(im) -cb.ax.set_yticklabels(cb.ax.get_yticklabels(), fontsize=18) -plt.show() -!ec -The results perfectly with our previous discussion where we used our own code. - - -===== Ridge regression ===== - -Having explored the ordinary least squares we move on to ridge -regression. In ridge regression we include a _regularizer_. This -involves a new cost function which leads to a new estimate for the -weights $\bm{\beta}$. This results in a penalized regression problem. The -cost function is given by - -!bt -\begin{align} - C(\bm{X}, \bm{\beta}; \lambda) = (\bm{X}\bm{\beta} - \bm{y})^T(\bm{X}\bm{\beta} - \bm{y}) + \lambda \bm{\beta}^T\bm{\beta}. -\end{align} -!et -!bc pycod -_lambda = 0.1 -clf_ridge = skl.Ridge(alpha=_lambda).fit(X_train, y_train) -J_ridge_sk = clf_ridge.coef_.reshape(L, L) -fig = plt.figure(figsize=(20, 14)) -im = plt.imshow(J_ridge_sk, **cmap_args) -plt.title("Ridge from Scikit-learn", fontsize=18) -plt.xticks(fontsize=18) -plt.yticks(fontsize=18) -cb = fig.colorbar(im) -cb.ax.set_yticklabels(cb.ax.get_yticklabels(), fontsize=18) - -plt.show() -!ec - - -===== LASSO regression ===== - -In the _Least Absolute Shrinkage and Selection Operator_ (LASSO)-method we get a third cost function. - -!bt -\begin{align} - C(\bm{X}, \bm{\beta}; \lambda) = (\bm{X}\bm{\beta} - \bm{y})^T(\bm{X}\bm{\beta} - \bm{y}) + \lambda \sqrt{\bm{\beta}^T\bm{\beta}}. -\end{align} -!et - -Finding the extremal point of this cost function is not so straight-forward as in least squares and ridge. We will therefore rely solely on the function ``Lasso`` from _Scikit-Learn_. - -!bc pycod -clf_lasso = skl.Lasso(alpha=_lambda).fit(X_train, y_train) -J_lasso_sk = clf_lasso.coef_.reshape(L, L) -fig = plt.figure(figsize=(20, 14)) -im = plt.imshow(J_lasso_sk, **cmap_args) -plt.title("Lasso from Scikit-learn", fontsize=18) -plt.xticks(fontsize=18) -plt.yticks(fontsize=18) -cb = fig.colorbar(im) -cb.ax.set_yticklabels(cb.ax.get_yticklabels(), fontsize=18) - -plt.show() -!ec - -It is quite striking how LASSO breaks the symmetry of the coupling -constant as opposed to ridge and OLS. We get a sparse solution with -$J_{j, j + 1} = -1$. - - - - -===== Performance as function of the regularization parameter ===== - -We see how the different models perform for a different set of values for $\lambda$. - - -!bc pycod -lambdas = np.logspace(-4, 5, 10) - -train_errors = { - "ols_sk": np.zeros(lambdas.size), - "ridge_sk": np.zeros(lambdas.size), - "lasso_sk": np.zeros(lambdas.size) -} - -test_errors = { - "ols_sk": np.zeros(lambdas.size), - "ridge_sk": np.zeros(lambdas.size), - "lasso_sk": np.zeros(lambdas.size) -} - -plot_counter = 1 - -fig = plt.figure(figsize=(32, 54)) - -for i, _lambda in enumerate(tqdm.tqdm(lambdas)): - for key, method in zip( - ["ols_sk", "ridge_sk", "lasso_sk"], - [skl.LinearRegression(), skl.Ridge(alpha=_lambda), skl.Lasso(alpha=_lambda)] - ): - method = method.fit(X_train, y_train) - - train_errors[key][i] = method.score(X_train, y_train) - test_errors[key][i] = method.score(X_test, y_test) - - omega = method.coef_.reshape(L, L) - - plt.subplot(10, 5, plot_counter) - plt.imshow(omega, **cmap_args) - plt.title(r"%s, $\lambda = %.4f$" % (key, _lambda)) - plot_counter += 1 - -plt.show() -!ec - -We see that LASSO reaches a good solution for low -values of $\lambda$, but will "wither" when we increase $\lambda$ too -much. Ridge is more stable over a larger range of values for -$\lambda$, but eventually also fades away. - - -===== Finding the optimal value of $\lambda$ ===== - -To determine which value of $\lambda$ is best we plot the accuracy of -the models when predicting the training and the testing set. We expect -the accuracy of the training set to be quite good, but if the accuracy -of the testing set is much lower this tells us that we might be -subject to an overfit model. The ideal scenario is an accuracy on the -testing set that is close to the accuracy of the training set. - - -!bc pycod -fig = plt.figure(figsize=(20, 14)) - -colors = { - "ols_sk": "r", - "ridge_sk": "y", - "lasso_sk": "c" -} - -for key in train_errors: - plt.semilogx( - lambdas, - train_errors[key], - colors[key], - label="Train {0}".format(key), - linewidth=4.0 - ) - -for key in test_errors: - plt.semilogx( - lambdas, - test_errors[key], - colors[key] + "--", - label="Test {0}".format(key), - linewidth=4.0 - ) -plt.legend(loc="best", fontsize=18) -plt.xlabel(r"$\lambda$", fontsize=18) -plt.ylabel(r"$R^2$", fontsize=18) -plt.tick_params(labelsize=18) -plt.show() -!ec - -From the above figure we can see that LASSO with $\lambda = 10^{-2}$ -achieves a very good accuracy on the test set. This by far surpasses the -other models for all values of $\lambda$. - - - - -===== Further Exercises ===== - -=== Exercise 1 === - -We will generate our own dataset for a function $y(x)$ where $x \in [0,1]$ and defined by random numbers computed with the uniform distribution. The function $y$ is a quadratic polynomial in $x$ with added stochastic noise according to the normal distribution $\cal {N}(0,1)$. -The following simple Python instructions define our $x$ and $y$ values (with 100 data points). -!bc pycod -x = np.random.rand(100,1) -y = 5*x*x+0.1*np.random.randn(100,1) -!ec - -o Write your own code (following the examples above) for computing the parametrization of the data set fitting a second-order polynomial. -o Use thereafter _scikit-learn_ (see again the examples in the regression slides) and compare with your own code. -o Using scikit-learn, compute also the mean square error, a risk metric corresponding to the expected value of the squared (quadratic) error defined as -!bt -\[ MSE(\hat{y},\hat{\tilde{y}}) = \frac{1}{n} -\sum_{i=0}^{n-1}(y_i-\tilde{y}_i)^2, -\] -!et -and the $R^2$ score function. -If $\tilde{\hat{y}}_i$ is the predicted value of the $i-th$ sample and $y_i$ is the corresponding true value, then the score $R^2$ is defined as -!bt -\[ -R^2(\hat{y}, \tilde{\hat{y}}) = 1 - \frac{\sum_{i=0}^{n - 1} (y_i - \tilde{y}_i)^2}{\sum_{i=0}^{n - 1} (y_i - \bar{y})^2}, -\] -!et -where we have defined the mean value of $\hat{y}$ as -!bt -\[ -\bar{y} = \frac{1}{n} \sum_{i=0}^{n - 1} y_i. -\] -!et - -You can use the functionality included in scikit-learn. If you feel -for it, you can use your own program and define functions which -compute the above two functions. Discuss the meaning of these -results. Try also to vary the coefficient in front of the added -stochastic noise term and discuss the quality of the fits. - - - - -=== Exercise 2, variance of the parameters $\beta$ in linear regression === - -Show that the variance of the parameters $\beta$ in the linear regression method (chapter 3, equation (3.8) of "Trevor Hastie, Robert Tibshirani, Jerome H. Friedman, The Elements of Statistical Learning, Springer":"https://www.springer.com/gp/book/9780387848570") is given as - -!bt -\[ -\mathrm{Var}(\hat{\beta}) = \left(\hat{X}^T\hat{X}\right)^{-1}\sigma^2, -\] -!et -with -!bt -\[ -\sigma^2 = \frac{1}{N-p-1}\sum_{i=1}^{N} (y_i-\tilde{y}_i)^2, -\] -!et -where we have assumed that we fit a function of degree $p-1$ (for example a polynomial in $x$). - - - -=== Exercise 3 === - -This exercise is a continuation of exercise 1. We will -use the same function to generate our data set, still staying with a -simple function $y(x)$ which we want to fit using linear regression, -but now extending the analysis to include the Ridge and the Lasso -regression methods. You can use the code under the Regression as an example on how to use the Ridge and the Lasso methods. - -We will thus again generate our own dataset for a function $y(x)$ where -$x \in [0,1]$ and defined by random numbers computed with the uniform -distribution. The function $y$ is a quadratic polynomial in $x$ with -added stochastic noise according to the normal distribution $\cal{N}(0,1)$. - -The following simple Python instructions define our $x$ and $y$ values (with 100 data points). -!bc pycod -x = np.random.rand(100,1) -y = 5*x*x+0.1*np.random.randn(100,1) -!ec - -o Write your own code for the Ridge method and compute the parametrization for different values of $\lambda$. Compare and analyze your results with those from exercise 1. Study the dependence on $\lambda$ while also varying the strength of the noise in your expression for $y(x)$. - -o Repeat the above but using the functionality of _scikit-learn_. Compare your code with the results from _scikit-learn_. Remember to run with the same random numbers for generating $x$ and $y$. - -o Our next step is to study the variance of the parameters $\beta_1$ and $\beta_2$ (assuming that we are parametrizing our function with a second-order polynomial. We will use standard linear regression and the Ridge regression. You can now opt for either writing your own function that calculates the variance of these paramaters (recall that this is equal to the diagonal elements of the matrix $(\hat{X}^T\hat{X})+\lambda\hat{I})^{-1}$) or use the functionality of _scikit-learn_ and compute their variances. Discuss the results of these variances as functions - -o Repeat the previous step but add now the Lasso method. Discuss your results and compare with standard regression and the Ridge regression results. - -o Try to implement the cross-validation as well. - -o Finally, using _scikit-learn_ or your own code, compute also the mean square error, a risk metric corresponding to the expected value of the squared (quadratic) error defined as -!bt -\[ MSE(\hat{y},\hat{\tilde{y}}) = \frac{1}{n} -\sum_{i=0}^{n-1}(y_i-\tilde{y}_i)^2, -\] -!et -and the $R^2$ score function. -If $\tilde{\hat{y}}_i$ is the predicted value of the $i-th$ sample and $y_i$ is the corresponding true value, then the score $R^2$ is defined as -!bt -\[ -R^2(\hat{y}, \tilde{\hat{y}}) = 1 - \frac{\sum_{i=0}^{n - 1} (y_i - \tilde{y}_i)^2}{\sum_{i=0}^{n - 1} (y_i - \bar{y})^2}, -\] -!et -where we have defined the mean value of $\hat{y}$ as -!bt -\[ -\bar{y} = \frac{1}{n} \sum_{i=0}^{n - 1} y_i. -\] -!et -Discuss these quantities as functions of the variable $\lambda$ in the Ridge and Lasso regression methods. - -=== Exercise 4 === - -We will study how -to fit polynomials to a specific two-dimensional function called -"Franke's -function":"http://www.dtic.mil/dtic/tr/fulltext/u2/a081688.pdf". This -is a function which has been widely used when testing various interpolation and fitting -algorithms. Furthermore, after having established the model and the -method, we will employ resamling techniques such as the cross-validation and/or -the bootstrap methods, in order to perform a proper assessment of our models. - - -The Franke function, which is a weighted sum of four exponentials reads as follows -!bt -\begin{align*} -f(x,y) &= \frac{3}{4}\exp{\left(-\frac{(9x-2)^2}{4} - \frac{(9y-2)^2}{4}\right)}+\frac{3}{4}\exp{\left(-\frac{(9x+1)^2}{49}- \frac{(9y+1)}{10}\right)} \\ -&+\frac{1}{2}\exp{\left(-\frac{(9x-7)^2}{4} - \frac{(9y-3)^2}{4}\right)} -\frac{1}{5}\exp{\left(-(9x-4)^2 - (9y-7)^2\right) }. -\end{align*} -!et - -The function will be defined for $x,y\in [0,1]$. Our first step will -be to perform an OLS regression analysis of this function, trying out -a polynomial fit with an $x$ and $y$ dependence of the form $[x, y, -x^2, y^2, xy, \dots]$. We will also include cross-validation and -bootstrap as resampling techniques. As in homeworks 1 and 2, we -can use a uniform distribution to set up the arrays of values for $x$ -and $y$, or as in the example below just a fix values for $x$ and $y$ with a given step size. -In this case we will have two predictors and need to fit a -function (for example a polynomial) of $x$ and $y$. Thereafter we will -repeat much of the same procedure using the the Ridge and -Lasso regression methods, introducing thus a dependence on the bias -(penalty) $\lambda$. - - -The Python function for the Franke function is included here (it performs also a three-dimensional plot of it) -!bc pycod -from mpl_toolkits.mplot3d import Axes3D -import matplotlib.pyplot as plt -from matplotlib import cm -from matplotlib.ticker import LinearLocator, FormatStrFormatter -import numpy as np -from random import random, seed - -fig = plt.figure() -ax = fig.gca(projection='3d') - -# Make data. -x = np.arange(0, 1, 0.05) -y = np.arange(0, 1, 0.05) -x, y = np.meshgrid(x,y) - - -def FrankeFunction(x,y): - term1 = 0.75*np.exp(-(0.25*(9*x-2)**2) - 0.25*((9*y-2)**2)) - term2 = 0.75*np.exp(-((9*x+1)**2)/49.0 - 0.1*(9*y+1)) - term3 = 0.5*np.exp(-(9*x-7)**2/4.0 - 0.25*((9*y-3)**2)) - term4 = -0.2*np.exp(-(9*x-4)**2 - (9*y-7)**2) - return term1 + term2 + term3 + term4 - - -z = FrankeFunction(x, y) - -# Plot the surface. -surf = ax.plot_surface(x, y, z, cmap=cm.coolwarm, - linewidth=0, antialiased=False) - -# Customize the z axis. -ax.set_zlim(-0.10, 1.40) -ax.zaxis.set_major_locator(LinearLocator(10)) -ax.zaxis.set_major_formatter(FormatStrFormatter('%.02f')) - -# Add a color bar which maps values to colors. -fig.colorbar(surf, shrink=0.5, aspect=5) - -plt.show() - -!ec - - -We will thus again generate our own dataset for a function $\mathrm{FrankeFunction}(x,y)$ where -$x,y \in [0,1]$ could be defined by random numbers computed with the uniform -distribution. The function $f(x,y)$ is the Franke function. You should explore also the addition -an added stochastic noise to this function using the normal distribution $\cal{N}(0,1)$. - -Write your own code (using either a matrix inversion or a singular value decomposition from e.g., _numpy_ ) or use your code from exercises 1 and 3 -and perform a standard least square regression analysis using polynomials in $x$ and $y$ up to fifth order. Find the confidence intervals of the parameters $\beta$ by computing their variances, evaluate the Mean Squared error (MSE) -!bt -\[ MSE(\hat{y},\hat{\tilde{y}}) = \frac{1}{n} -\sum_{i=0}^{n-1}(y_i-\tilde{y}_i)^2, -\] -!et -and the $R^2$ score function. -If $\tilde{\hat{y}}_i$ is the predicted value of the $i-th$ sample and $y_i$ is the corresponding true value, then the score $R^2$ is defined as -!bt -\[ -R^2(\hat{y}, \tilde{\hat{y}}) = 1 - \frac{\sum_{i=0}^{n - 1} (y_i - \tilde{y}_i)^2}{\sum_{i=0}^{n - 1} (y_i - \bar{y})^2}, -\] -!et -where we have defined the mean value of $\hat{y}$ as -!bt -\[ -\bar{y} = \frac{1}{n} \sum_{i=0}^{n - 1} y_i. -\] -!et - -Perform a resampling of the data where you split the data in training data and test data. Implement the $k$-fold cross-validation algorithm and/or the bootstrap algorithm -and evaluate again the MSE and the $R^2$ functions resulting from the test data. Evaluate also the bias and variance of the final models. - - -Write then your own code for the Ridge method, either using matrix -inversion or the singular value decomposition as done for standard OLS. Perform the same analysis as in the -previous exercise (for the same polynomials and include resampling -techniques) but now for different values of $\lambda$. Compare and -analyze your results with those obtained with standard OLS. Study the -dependence on $\lambda$ while also varying eventually the strength of -the noise in your expression for $\mathrm{FrankeFunction}(x,y)$. - -Then perform the same studies but now with Lasso regression. Use the functionalities of -_scikit-learn_. Give a critical discussion of the three methods and a -judgement of which model fits the data best. - - - - - - - -======= Optimization and Gradient Methods ======= - - -===== Optimization, the central part of any Machine Learning algortithm ===== - -Almost every problem in machine learning and data science starts with -a dataset $X$, a model $g(\beta)$, which is a function of the -parameters $\beta$ and a cost function $C(X, g(\beta))$ that allows -us to judge how well the model $g(\beta)$ explains the observations -$X$. The model is fit by finding the values of $\beta$ that minimize -the cost function. Ideally we would be able to solve for $\beta$ -analytically, however this is not possible in general and we must use -some approximative/numerical method to compute the minimum. - - - -===== Revisiting our Logistic Regression case ===== - -In our discussion on Logistic Regression we studied the -case of -two classes, with $y_i$ either -$0$ or $1$. Furthermore we assumed also that we have only two -parameters $\beta$ in our fitting, that is we -defined probabilities - -!bt -\begin{align*} -p(y_i=1|x_i,\hat{\beta}) &= \frac{\exp{(\beta_0+\beta_1x_i)}}{1+\exp{(\beta_0+\beta_1x_i)}},\nonumber\\ -p(y_i=0|x_i,\hat{\beta}) &= 1 - p(y_i=1|x_i,\hat{\beta}), -\end{align*} -!et -where $\hat{\beta}$ are the weights we wish to extract from data, in our case $\beta_0$ and $\beta_1$. - - -Our compact equations used a definition of a vector $\hat{y}$ with $n$ -elements $y_i$, an $n\times p$ matrix $\hat{X}$ which contains the -$x_i$ values and a vector $\hat{p}$ of fitted probabilities -$p(y_i\vert x_i,\hat{\beta})$. We rewrote in a more compact form -the first derivative of the cost function as - -!bt -\[ -\frac{\partial \mathcal{C}(\hat{\beta})}{\partial \hat{\beta}} = -\hat{X}^T\left(\hat{y}-\hat{p}\right). -\] -!et - -If we in addition define a diagonal matrix $\hat{W}$ with elements -$p(y_i\vert x_i,\hat{\beta})(1-p(y_i\vert x_i,\hat{\beta})$, we can obtain a compact expression of the second derivative as - -!bt -\[ -\frac{\partial^2 \mathcal{C}(\hat{\beta})}{\partial \hat{\beta}\partial \hat{\beta}^T} = \hat{X}^T\hat{W}\hat{X}. -\] -!et -This defines what is called the Hessian matrix. - - -===== Solving using Newton-Raphson's method ===== - -If we can set up these equations, Newton-Raphson's iterative method is normally the method of choice. It requires however that we can compute in an efficient way the matrices that define the first and second derivatives. - -Our iterative scheme is then given by - -!bt -\[ -\hat{\beta}^{\mathrm{new}} = \hat{\beta}^{\mathrm{old}}-\left(\frac{\partial^2 \mathcal{C}(\hat{\beta})}{\partial \hat{\beta}\partial \hat{\beta}^T}\right)^{-1}_{\hat{\beta}^{\mathrm{old}}}\times \left(\frac{\partial \mathcal{C}(\hat{\beta})}{\partial \hat{\beta}}\right)_{\hat{\beta}^{\mathrm{old}}}, -\] -!et -or in matrix form as - -!bt -\[ -\hat{\beta}^{\mathrm{new}} = \hat{\beta}^{\mathrm{old}}-\left(\hat{X}^T\hat{W}\hat{X} \right)^{-1}\times \left(-\hat{X}^T(\hat{y}-\hat{p}) \right)_{\hat{\beta}^{\mathrm{old}}}. -\] -!et -The right-hand side is computed with the old values of $\beta$. - -If we can compute these matrices, in particular the Hessian, the above is often the easiest method to implement. - - - -Let us quickly remind ourselves how we derive the above method. - -Perhaps the most celebrated of all one-dimensional root-finding -routines is Newton's method, also called the Newton-Raphson -method. This method requires the evaluation of both the -function $f$ and its derivative $f'$ at arbitrary points. -If you can only calculate the derivative -numerically and/or your function is not of the smooth type, we -normally discourage the use of this method. - - - -The Newton-Raphson formula consists geometrically of extending the -tangent line at a current point until it crosses zero, then setting -the next guess to the abscissa of that zero-crossing. The mathematics -behind this method is rather simple. Employing a Taylor expansion for -$x$ sufficiently close to the solution $s$, we have - - -!bt -\[ - f(s)=0=f(x)+(s-x)f'(x)+\frac{(s-x)^2}{2}f''(x) +\dots. - \label{eq:taylornr} -\] -!et - -For small enough values of the function and for well-behaved -functions, the terms beyond linear are unimportant, hence we obtain - - -!bt -\[ - f(x)+(s-x)f'(x)\approx 0, -\] -!et -yielding -!bt -\[ - s\approx x-\frac{f(x)}{f'(x)}. -\] -!et - -Having in mind an iterative procedure, it is natural to start iterating with -!bt -\[ - x_{n+1}=x_n-\frac{f(x_n)}{f'(x_n)}. -\] -!et - - -The above is Newton-Raphson's method. It has a simple geometric -interpretation, namely $x_{n+1}$ is the point where the tangent from -$(x_n,f(x_n))$ crosses the $x$-axis. Close to the solution, -Newton-Raphson converges fast to the desired result. However, if we -are far from a root, where the higher-order terms in the series are -important, the Newton-Raphson formula can give grossly inaccurate -results. For instance, the initial guess for the root might be so far -from the true root as to let the search interval include a local -maximum or minimum of the function. If an iteration places a trial -guess near such a local extremum, so that the first derivative nearly -vanishes, then Newton-Raphson may fail totally - - - -Newton's method can be generalized to systems of several non-linear equations -and variables. Consider the case with two equations -!bt -\[ - \begin{array}{cc} f_1(x_1,x_2) &=0\\ - f_2(x_1,x_2) &=0,\end{array} -\] -!et -which we Taylor expand to obtain - -!bt -\[ - \begin{array}{cc} 0=f_1(x_1+h_1,x_2+h_2)=&f_1(x_1,x_2)+h_1 - \partial f_1/\partial x_1+h_2 - \partial f_1/\partial x_2+\dots\\ - 0=f_2(x_1+h_1,x_2+h_2)=&f_2(x_1,x_2)+h_1 - \partial f_2/\partial x_1+h_2 - \partial f_2/\partial x_2+\dots - \end{array}. -\] -!et -Defining the Jacobian matrix $\bm{J}$ we have -!bt -\[ - \bm{J}=\left( \begin{array}{cc} - \partial f_1/\partial x_1 & \partial f_1/\partial x_2 \\ - \partial f_2/\partial x_1 &\partial f_2/\partial x_2 - \end{array} \right), -\] -!et -we can rephrase Newton's method as -!bt -\[ -\left(\begin{array}{c} x_1^{n+1} \\ x_2^{n+1} \end{array} \right)= -\left(\begin{array}{c} x_1^{n} \\ x_2^{n} \end{array} \right)+ -\left(\begin{array}{c} h_1^{n} \\ h_2^{n} \end{array} \right), -\] -!et -where we have defined -!bt -\[ - \left(\begin{array}{c} h_1^{n} \\ h_2^{n} \end{array} \right)= - -{\bm{J}}^{-1} - \left(\begin{array}{c} f_1(x_1^{n},x_2^{n}) \\ f_2(x_1^{n},x_2^{n}) \end{array} \right). -\] -!et -We need thus to compute the inverse of the Jacobian matrix and it -is to understand that difficulties may -arise in case $\bm{J}$ is nearly singular. - -It is rather straightforward to extend the above scheme to systems of -more than two non-linear equations. In our case, the Jacobian matrix is given by the Hessian that represents the second derivative of cost function. - - - - -===== Steepest descent ===== - -The basic idea of gradient descent is -that a function $F(\mathbf{x})$, -$\mathbf{x} \equiv (x_1,\cdots,x_n)$, decreases fastest if one goes from $\bf {x}$ in the -direction of the negative gradient $-\nabla F(\mathbf{x})$. - -It can be shown that if -!bt -\[ -\mathbf{x}_{k+1} = \mathbf{x}_k - \gamma_k \nabla F(\mathbf{x}_k), -\] -!et -with $\gamma_k > 0$. - -For $\gamma_k$ small enough, then $F(\mathbf{x}_{k+1}) \leq -F(\mathbf{x}_k)$. This means that for a sufficiently small $\gamma_k$ -we are always moving towards smaller function values, i.e a minimum. - - -The previous observation is the basis of the method of steepest -descent, which is also referred to as just gradient descent (GD). One -starts with an initial guess $\mathbf{x}_0$ for a minimum of $F$ and -computes new approximations according to - -!bt -\[ -\mathbf{x}_{k+1} = \mathbf{x}_k - \gamma_k \nabla F(\mathbf{x}_k), \ \ k \geq 0. -\] -!et - -The parameter $\gamma_k$ is often referred to as the step length or -the learning rate within the context of Machine Learning. - - - -Ideally the sequence $\{\mathbf{x}_k \}_{k=0}$ converges to a global -minimum of the function $F$. In general we do not know if we are in a -global or local minimum. In the special case when $F$ is a convex -function, all local minima are also global minima, so in this case -gradient descent can converge to the global solution. The advantage of -this scheme is that it is conceptually simple and straightforward to -implement. However the method in this form has some severe -limitations: - -In machine learing we are often faced with non-convex high dimensional -cost functions with many local minima. Since GD is deterministic we -will get stuck in a local minimum, if the method converges, unless we -have a very good intial guess. This also implies that the scheme is -sensitive to the chosen initial condition. - -Note that the gradient is a function of $\mathbf{x} = -(x_1,\cdots,x_n)$ which makes it expensive to compute numerically. - - - -The gradient descent method -is sensitive to the choice of learning rate $\gamma_k$. This is due -to the fact that we are only guaranteed that $F(\mathbf{x}_{k+1}) \leq -F(\mathbf{x}_k)$ for sufficiently small $\gamma_k$. The problem is to -determine an optimal learning rate. If the learning rate is chosen too -small the method will take a long time to converge and if it is too -large we can experience erratic behavior. - -Many of these shortcomings can be alleviated by introducing -randomness. One such method is that of Stochastic Gradient Descent -(SGD), see below. - - - -Ideally we want our cost/loss function to be convex(concave). - -First we give the definition of a convex set: A set $C$ in -$\mathbb{R}^n$ is said to be convex if, for all $x$ and $y$ in $C$ and -all $t \in (0,1)$ , the point $(1 − t)x + ty$ also belongs to -C. Geometrically this means that every point on the line segment -connecting $x$ and $y$ is in $C$ as discussed below. - -The convex subsets of $\mathbb{R}$ are the intervals of -$\mathbb{R}$. Examples of convex sets of $\mathbb{R}^2$ are the -regular polygons (triangles, rectangles, pentagons, etc...). - - -===== Convex function ===== - -_Convex function_: Let $X \subset \mathbb{R}^n$ be a convex set. Assume that the function $f: X \rightarrow \mathbb{R}$ is continuous, then $f$ is said to be convex if $$f(tx_1 + (1-t)x_2) \leq tf(x_1) + (1-t)f(x_2) $$ for all $x_1, x_2 \in X$ and for all $t \in [0,1]$. If $\leq$ is replaced with a strict inequaltiy in the definition, we demand $x_1 \neq x_2$ and $t\in(0,1)$ then $f$ is said to be strictly convex. For a single variable function, convexity means that if you draw a straight line connecting $f(x_1)$ and $f(x_2)$, the value of the function on the interval $[x_1,x_2]$ is always below the line as illustrated below. - - -In the following we state first and second-order conditions which -ensures convexity of a function $f$. We write $D_f$ to denote the -domain of $f$, i.e the subset of $R^n$ where $f$ is defined. For more -details and proofs we refer to: "S. Boyd and L. Vandenberghe. Convex Optimization. Cambridge University Press":"http://stanford.edu/boyd/cvxbook/, 2004". - -!bblock First order condition -Suppose $f$ is differentiable (i.e $\nabla f(x)$ is well defined for -all $x$ in the domain of $f$). Then $f$ is convex if and only if $D_f$ -is a convex set and $$f(y) \geq f(x) + \nabla f(x)^T (y-x) $$ holds -for all $x,y \in D_f$. This condition means that for a convex function -the first order Taylor expansion (right hand side above) at any point -a global under estimator of the function. To convince yourself you can -make a drawing of $f(x) = x^2+1$ and draw the tangent line to $f(x)$ and -note that it is always below the graph. -!eblock - -!bblock Second order condition -Assume that $f$ is twice -differentiable, i.e the Hessian matrix exists at each point in -$D_f$. Then $f$ is convex if and only if $D_f$ is a convex set and its -Hessian is positive semi-definite for all $x\in D_f$. For a -single-variable function this reduces to $f''(x) \geq 0$. Geometrically this means that $f$ has nonnegative curvature -everywhere. -!eblock - -This condition is particularly useful since it gives us an procedure for determining if the function under consideration is convex, apart from using the definition. - - -The next result is of great importance to us and the reason why we are -going on about convex functions. In machine learning we frequently -have to minimize a loss/cost function in order to find the best -parameters for the model we are considering. - -Ideally we want the -global minimum (for high-dimensional models it is hard to know -if we have local or global minimum). However, if the cost/loss function -is convex the following result provides invaluable information: - -!bblock Any minimum is global for convex functions -Consider the problem of finding $x \in \mathbb{R}^n$ such that $f(x)$ -is minimal, where $f$ is convex and differentiable. Then, any point -$x^*$ that satisfies $\nabla f(x^*) = 0$ is a global minimum. -!eblock - -This result means that if we know that the cost/loss function is convex and we are able to find a minimum, we are guaranteed that it is a global minimum. - - -===== Some simple problems ===== - -o Show that $f(x)=x^2$ is convex for $x \in \mathbb{R}$ using the definition of convexity. Hint: If you re-write the definition, $f$ is convex if the following holds for all $x,y \in D_f$ and any $\lambda \in [0,1]$ $\lambda f(x)+(1-\lambda)f(y)-f(\lambda x + (1-\lambda) y ) \geq 0$. - -o Using the second order condition show that the following functions are convex on the specified domain. - * $f(x) = e^x$ is convex for $x \in \mathbb{R}$. - * $g(x) = -\ln(x)$ is convex for $x \in (0,\infty)$. -o Let $f(x) = x^2$ and $g(x) = e^x$. Show that $f(g(x))$ and $g(f(x))$ is convex for $x \in \mathbb{R}$. Also show that if $f(x)$ is any convex function than $h(x) = e^{f(x)}$ is convex. - -o A norm is any function that satisfy the following properties - * $f(\alpha x) = |\alpha| f(x)$ for all $\alpha \in \mathbb{R}$. - * $f(x+y) \leq f(x) + f(y)$ - * $f(x) \leq 0$ for all $x \in \mathbb{R}^n$ with equality if and only if $x = 0$ - -Using the definition of convexity, try to show that a function satisfying the properties above is convex (the third condition is not needed to show this). - - - -===== Standard steepest descent ===== - - -Before we proceed, we would like to discuss the approach called the -_standard Steepest descent_, which again leads to us having to be able -to compute a matrix. It belongs to the class of Conjugate Gradient methods (CG). - -"The success of the CG method":"https://www.cs.cmu.edu/~quake-papers/painless-conjugate-gradient.pdf" -for finding solutions of non-linear problems is based on the theory -of conjugate gradients for linear systems of equations. It belongs to -the class of iterative methods for solving problems from linear -algebra of the type -!bt -\begin{equation*} -\hat{A}\hat{x} = \hat{b}. -\end{equation*} -!et - -In the iterative process we end up with a problem like - -!bt -\begin{equation*} - \hat{r}= \hat{b}-\hat{A}\hat{x}, -\end{equation*} -!et -where $\hat{r}$ is the so-called residual or error in the iterative process. - -When we have found the exact solution, $\hat{r}=0$. - - -The residual is zero when we reach the minimum of the quadratic equation -!bt -\begin{equation*} - P(\hat{x})=\frac{1}{2}\hat{x}^T\hat{A}\hat{x} - \hat{x}^T\hat{b}, -\end{equation*} -!et - -with the constraint that the matrix $\hat{A}$ is positive definite and -symmetric. This defines also the Hessian and we want it to be positive definite. - - - -We denote the initial guess for $\hat{x}$ as $\hat{x}_0$. -We can assume without loss of generality that -!bt -\begin{equation*} -\hat{x}_0=0, -\end{equation*} -!et -or consider the system -!bt -\begin{equation*} -\hat{A}\hat{z} = \hat{b}-\hat{A}\hat{x}_0, -\end{equation*} -!et -instead. - - - -One can show that the solution $\hat{x}$ is also the unique minimizer of the quadratic form -!bt -\begin{equation*} - f(\hat{x}) = \frac{1}{2}\hat{x}^T\hat{A}\hat{x} - \hat{x}^T \hat{x} , \quad \hat{x}\in\mathbf{R}^n. -\end{equation*} -!et -This suggests taking the first basis vector $\hat{r}_1$ (see below for definition) -to be the gradient of $f$ at $\hat{x}=\hat{x}_0$, -which equals -!bt -\begin{equation*} -\hat{A}\hat{x}_0-\hat{b}, -\end{equation*} -!et -and -$\hat{x}_0=0$ it is equal $-\hat{b}$. - -We can compute the residual iteratively as -!bt -\begin{equation*} -\hat{r}_{k+1}=\hat{b}-\hat{A}\hat{x}_{k+1}, - \end{equation*} -!et -which equals -!bt -\begin{equation*} -\hat{b}-\hat{A}(\hat{x}_k+\alpha_k\hat{r}_k), - \end{equation*} -!et -or -!bt -\begin{equation*} -(\hat{b}-\hat{A}\hat{x}_k)-\alpha_k\hat{A}\hat{r}_k, - \end{equation*} -!et -which gives - -!bt -\[ -\alpha_k = \frac{\hat{r}_k^T\hat{r}_k}{\hat{r}_k^T\hat{A}\hat{r}_k} -\] -!et -leading to the iterative scheme -!bt -\begin{equation*} -\hat{x}_{k+1}=\hat{x}_k-\alpha_k\hat{r}_{k}, - \end{equation*} -!et - -===== Simple codes for steepest descent and conjugate gradient using a $2\times 2$ matrix, in c++, Python code to come ===== - -!bc cppcod -#include -#include -#include -#include -#include "vectormatrixclass.h" -using namespace std; -// Main function begins here -int main(int argc, char * argv[]){ - int dim = 2; - Vector x(dim),xsd(dim), b(dim),x0(dim); - Matrix A(dim,dim); - - // Set our initial guess - x0(0) = x0(1) = 0; - // Set the matrix - A(0,0) = 3; A(1,0) = 2; A(0,1) = 2; A(1,1) = 6; - b(0) = 2; b(1) = -8; - cout << "The Matrix A that we are using: " << endl; - A.Print(); - cout << endl; - xsd = SteepestDescent(A,b,x0); - cout << "The approximate solution using Steepest Descent is: " << endl; - xsd.Print(); - cout << endl; -} -!ec - - - -!bc cppcod -Vector SteepestDescent(Matrix A, Vector b, Vector x0){ - int IterMax, i; - int dim = x0.Dimension(); - const double tolerance = 1.0e-14; - Vector x(dim),f(dim),z(dim); - double c,alpha,d; - IterMax = 30; - x = x0; - r = A*x-b; - i = 0; - while (i <= IterMax){ - z = A*r; - c = dot(r,r); - alpha = c/dot(r,z); - x = x - alpha*r; - r = A*x-b; - if(sqrt(dot(r,r)) < tolerance) break; - i++; - } - return x; -} -!ec - -===== Steepest descent example ===== - -!bc pycod -import numpy as np -import numpy.linalg as la - -import scipy.optimize as sopt - -import matplotlib.pyplot as pt -from mpl_toolkits.mplot3d import axes3d - -def f(x): - return 0.5*x[0]**2 + 2.5*x[1]**2 - -def df(x): - return np.array([x[0], 5*x[1]]) - -fig = pt.figure() -ax = fig.gca(projection="3d") - -xmesh, ymesh = np.mgrid[-2:2:50j,-2:2:50j] -fmesh = f(np.array([xmesh, ymesh])) -ax.plot_surface(xmesh, ymesh, fmesh) -!ec -And then as countor plot -!bc pycod -pt.axis("equal") -pt.contour(xmesh, ymesh, fmesh) -guesses = [np.array([2, 2./5])] -!ec -Find guesses -!bc pycod -x = guesses[-1] -s = -df(x) -!ec -Run it! -!bc pycod -def f1d(alpha): - return f(x + alpha*s) - -alpha_opt = sopt.golden(f1d) -next_guess = x + alpha_opt * s -guesses.append(next_guess) -print(next_guess) -!ec -What happened? -!bc pycod -pt.axis("equal") -pt.contour(xmesh, ymesh, fmesh, 50) -it_array = np.array(guesses) -pt.plot(it_array.T[0], it_array.T[1], "x-") -!ec - - -===== Conjugate gradient method ===== - -In the CG method we define so-called conjugate directions and two vectors -$\hat{s}$ and $\hat{t}$ -are said to be -conjugate if -!bt -\begin{equation*} -\hat{s}^T\hat{A}\hat{t}= 0. -\end{equation*} -!et -The philosophy of the CG method is to perform searches in various conjugate directions -of our vectors $\hat{x}_i$ obeying the above criterion, namely -!bt -\begin{equation*} -\hat{x}_i^T\hat{A}\hat{x}_j= 0. -\end{equation*} -!et -Two vectors are conjugate if they are orthogonal with respect to -this inner product. Being conjugate is a symmetric relation: if $\hat{s}$ is conjugate to $\hat{t}$, then $\hat{t}$ is conjugate to $\hat{s}$. - -An example is given by the eigenvectors of the matrix -!bt -\begin{equation*} -\hat{v}_i^T\hat{A}\hat{v}_j= \lambda\hat{v}_i^T\hat{v}_j, -\end{equation*} -!et -which is zero unless $i=j$. - -Assume now that we have a symmetric positive-definite matrix $\hat{A}$ of size -$n\times n$. At each iteration $i+1$ we obtain the conjugate direction of a vector -!bt -\begin{equation*} -\hat{x}_{i+1}=\hat{x}_{i}+\alpha_i\hat{p}_{i}. -\end{equation*} -!et -We assume that $\hat{p}_{i}$ is a sequence of $n$ mutually conjugate directions. -Then the $\hat{p}_{i}$ form a basis of $R^n$ and we can expand the solution -$ \hat{A}\hat{x} = \hat{b}$ in this basis, namely - -!bt -\begin{equation*} - \hat{x} = \sum^{n}_{i=1} \alpha_i \hat{p}_i. -\end{equation*} -!et - -The coefficients are given by -!bt -\begin{equation*} - \mathbf{A}\mathbf{x} = \sum^{n}_{i=1} \alpha_i \mathbf{A} \mathbf{p}_i = \mathbf{b}. -\end{equation*} -!et -Multiplying with $\hat{p}_k^T$ from the left gives - -!bt -\begin{equation*} - \hat{p}_k^T \hat{A}\hat{x} = \sum^{n}_{i=1} \alpha_i\hat{p}_k^T \hat{A}\hat{p}_i= \hat{p}_k^T \hat{b}, -\end{equation*} -!et -and we can define the coefficients $\alpha_k$ as - -!bt -\begin{equation*} - \alpha_k = \frac{\hat{p}_k^T \hat{b}}{\hat{p}_k^T \hat{A} \hat{p}_k} -\end{equation*} -!et - -If we choose the conjugate vectors $\hat{p}_k$ carefully, -then we may not need all of them to obtain a good approximation to the solution -$\hat{x}$. -We want to regard the conjugate gradient method as an iterative method. -This will us to solve systems where $n$ is so large that the direct -method would take too much time. - -We denote the initial guess for $\hat{x}$ as $\hat{x}_0$. -We can assume without loss of generality that -!bt -\begin{equation*} -\hat{x}_0=0, -\end{equation*} -!et -or consider the system -!bt -\begin{equation*} -\hat{A}\hat{z} = \hat{b}-\hat{A}\hat{x}_0, -\end{equation*} -!et -instead. - -One can show that the solution $\hat{x}$ is also the unique minimizer of the quadratic form -!bt -\begin{equation*} - f(\hat{x}) = \frac{1}{2}\hat{x}^T\hat{A}\hat{x} - \hat{x}^T \hat{x} , \quad \hat{x}\in\mathbf{R}^n. -\end{equation*} -!et -This suggests taking the first basis vector $\hat{p}_1$ -to be the gradient of $f$ at $\hat{x}=\hat{x}_0$, -which equals -!bt -\begin{equation*} -\hat{A}\hat{x}_0-\hat{b}, -\end{equation*} -!et -and -$\hat{x}_0=0$ it is equal $-\hat{b}$. -The other vectors in the basis will be conjugate to the gradient, -hence the name conjugate gradient method. - -Let $\hat{r}_k$ be the residual at the $k$-th step: -!bt -\begin{equation*} -\hat{r}_k=\hat{b}-\hat{A}\hat{x}_k. -\end{equation*} -!et -Note that $\hat{r}_k$ is the negative gradient of $f$ at -$\hat{x}=\hat{x}_k$, -so the gradient descent method would be to move in the direction $\hat{r}_k$. -Here, we insist that the directions $\hat{p}_k$ are conjugate to each other, -so we take the direction closest to the gradient $\hat{r}_k$ -under the conjugacy constraint. -This gives the following expression -!bt -\begin{equation*} -\hat{p}_{k+1}=\hat{r}_k-\frac{\hat{p}_k^T \hat{A}\hat{r}_k}{\hat{p}_k^T\hat{A}\hat{p}_k} \hat{p}_k. -\end{equation*} -!et - -We can also compute the residual iteratively as -!bt -\begin{equation*} -\hat{r}_{k+1}=\hat{b}-\hat{A}\hat{x}_{k+1}, - \end{equation*} -!et -which equals -!bt -\begin{equation*} -\hat{b}-\hat{A}(\hat{x}_k+\alpha_k\hat{p}_k), - \end{equation*} -!et -or -!bt -\begin{equation*} -(\hat{b}-\hat{A}\hat{x}_k)-\alpha_k\hat{A}\hat{p}_k, - \end{equation*} -!et -which gives - -!bt -\begin{equation*} -\hat{r}_{k+1}=\hat{r}_k-\hat{A}\hat{p}_{k}, - \end{equation*} -!et - -===== Simple implementation of the Conjugate gradient algorithm ===== - -!bc cppcod - Vector ConjugateGradient(Matrix A, Vector b, Vector x0){ - int dim = x0.Dimension(); - const double tolerance = 1.0e-14; - Vector x(dim),r(dim),v(dim),z(dim); - double c,t,d; - - x = x0; - r = b - A*x; - v = r; - c = dot(r,r); - int i = 0; IterMax = dim; - while(i <= IterMax){ - z = A*v; - t = c/dot(v,z); - x = x + t*v; - r = r - t*z; - d = dot(r,r); - if(sqrt(d) < tolerance) - break; - v = r + (d/c)*v; - c = d; i++; - } - return x; -} -!ec - -===== Broyden–Fletcher–Goldfarb–Shanno algorithm ===== - -The optimization problem is to minimize $f(\mathbf {x} )$ where $\mathbf {x}$ is a vector in $R^{n}$, and $f$ is a differentiable scalar function. There are no constraints on the values that $\mathbf {x}$ can take. - -The algorithm begins at an initial estimate for the optimal value $\mathbf {x}_{0}$ and proceeds iteratively to get a better estimate at each stage. - -The search direction $p_k$ at stage $k$ is given by the solution of the analogue of the Newton equation -!bt -\[ -B_{k}\mathbf {p} _{k}=-\nabla f(\mathbf {x}_{k}), -\] -!et - -where $B_{k}$ is an approximation to the Hessian matrix, which is -updated iteratively at each stage, and $\nabla f(\mathbf {x} _{k})$ -is the gradient of the function -evaluated at $x_k$. -A line search in the direction $p_k$ is then used to -find the next point $x_{k+1}$ by minimising -!bt -\[ -f(\mathbf {x}_{k}+\alpha \mathbf {p}_{k}), -\] -!et -over the scalar $\alpha > 0$. - - -We will use linear regression as a case study for the gradient descent -methods. Linear regression is a great test case for the gradient -descent methods discussed in the lectures since it has several -desirable properties such as: - -o An analytical solution. -o The gradient can be computed analytically. -o The cost function is convex which guarantees that gradient descent converges for small enough learning rates - -We revisit the example from homework set 1 where we had -!bt -\[ -y_i = 5x_i^2 + 0.1\xi_i, \ i=1,\cdots,100 -\] -!et -with $x_i \in [0,1] $ chosen randomly with a uniform distribution. Additionally $\xi_i$ represents stochastic noise chosen according to a normal distribution $\cal {N}(0,1)$. -The linear regression model is given by -!bt -\[ -h_\beta(x) = \hat{y} = \beta_0 + \beta_1 x, -\] -!et -such that -!bt -\[ -\hat{y}_i = \beta_0 + \beta_1 x_i. -\] -!et - - -===== Gradient descent example ===== - -Let $\mathbf{y} = (y_1,\cdots,y_n)^T$, $\mathbf{\hat{y}} = (\hat{y}_1,\cdots,\hat{y}_n)^T$ and $\beta = (\beta_0, \beta_1)^T$ - -It is convenient to write $\mathbf{\hat{y}} = X\beta$ where $X \in \mathbb{R}^{100 \times 2} $ is the design matrix given by -!bt -\[ -X \equiv \begin{bmatrix} -1 & x_1 \\ -\vdots & \vdots \\ -1 & x_{100} & \\ -\end{bmatrix}. -\] -!et -The loss function is given by -!bt -\[ -C(\beta) = ||X\beta-\mathbf{y}||^2 = ||X\beta||^2 - 2 \mathbf{y}^T X\beta + ||\mathbf{y}||^2 = \sum_{i=1}^{100} (\beta_0 + \beta_1 x_i)^2 - 2 y_i (\beta_0 + \beta_1 x_i) + y_i^2 -\] -!et -and we want to find $\beta$ such that $C(\beta)$ is minimized. - - -Computing $\partial C(\beta) / \partial \beta_0$ and $\partial C(\beta) / \partial \beta_1$ we can show that the gradient can be written as -!bt -\[ -\nabla_{\beta} C(\beta) = (\partial C(\beta) / \partial \beta_0, \partial C(\beta) / \partial \beta_1)^T = 2\begin{bmatrix} \sum_{i=1}^{100} \left(\beta_0+\beta_1x_i-y_i\right) \\ -\sum_{i=1}^{100}\left( x_i (\beta_0+\beta_1x_i)-y_ix_i\right) \\ -\end{bmatrix} = 2X^T(X\beta - \mathbf{y}), -\] -!et -where $X$ is the design matrix defined above. - - -The Hessian matrix of $C(\beta)$ is given by -!bt -\[ -\hat{H} \equiv \begin{bmatrix} -\frac{\partial^2 C(\beta)}{\partial \beta_0^2} & \frac{\partial^2 C(\beta)}{\partial \beta_0 \partial \beta_1} \\ -\frac{\partial^2 C(\beta)}{\partial \beta_0 \partial \beta_1} & \frac{\partial^2 C(\beta)}{\partial \beta_1^2} & \\ -\end{bmatrix} = 2X^T X. -\] -!et -This result implies that $C(\beta)$ is a convex function since the matrix $X^T X$ always is positive semi-definite. - - - -===== Simple program ===== - -We can now write a program that minimizes $C(\beta)$ using the gradient descent method with a constant learning rate $\gamma$ according to -!bt -\[ -\beta_{k+1} = \beta_k - \gamma \nabla_\beta C(\beta_k), \ k=0,1,\cdots -\] -!et - -We can use the expression we computed for the gradient and let use a -$\beta_0$ be chosen randomly and let $\gamma = 0.001$. Stop iterating -when $||\nabla_\beta C(\beta_k) || \leq \epsilon = 10^{-8}$. - -And finally we can compare our solution for $\beta$ with the analytic result given by -$\beta= (X^TX)^{-1} X^T \mathbf{y}$. -!bc pycod -import numpy as np - -""" -The following setup is just a suggestion, feel free to write it the way you like. -""" - -#Setup problem described in the exercise -N = 100 #Nr of datapoints -M = 2 #Nr of features -x = np.random.rand(N) #Uniformly generated x-values in [0,1] -y = 5*x**2 + 0.1*np.random.randn(N) -X = np.c_[np.ones(N),x] #Construct design matrix - -#Compute beta according to normal equations to compare with GD solution -Xt_X_inv = np.linalg.inv(np.dot(X.T,X)) -Xt_y = np.dot(X.transpose(),y) -beta_NE = np.dot(Xt_X_inv,Xt_y) -print(beta_NE) -!ec - - -Another simple example is here -!bc pycod - -# Importing various packages -from random import random, seed -import numpy as np -import matplotlib.pyplot as plt -from mpl_toolkits.mplot3d import Axes3D -from matplotlib import cm -from matplotlib.ticker import LinearLocator, FormatStrFormatter -import sys - -x = 2*np.random.rand(100,1) -y = 4+3*x+np.random.randn(100,1) - -xb = np.c_[np.ones((100,1)), x] -beta_linreg = np.linalg.inv(xb.T.dot(xb)).dot(xb.T).dot(y) -print(beta_linreg) -beta = np.random.randn(2,1) - -eta = 0.1 -Niterations = 1000 -m = 100 - -for iter in range(Niterations): - gradients = 2.0/m*xb.T.dot(xb.dot(beta)-y) - beta -= eta*gradients - -print(beta) -xnew = np.array([[0],[2]]) -xbnew = np.c_[np.ones((2,1)), xnew] -ypredict = xbnew.dot(beta) -ypredict2 = xbnew.dot(beta_linreg) -plt.plot(xnew, ypredict, "r-") -plt.plot(xnew, ypredict2, "b-") -plt.plot(x, y ,'ro') -plt.axis([0,2.0,0, 15.0]) -plt.xlabel(r'$x$') -plt.ylabel(r'$y$') -plt.title(r'Gradient descent example') -plt.show() - -!ec - - -===== And a corresponding example using _scikit-learn_ ===== - -!bc pycod -# Importing various packages -from random import random, seed -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import SGDRegressor - -x = 2*np.random.rand(100,1) -y = 4+3*x+np.random.randn(100,1) - -xb = np.c_[np.ones((100,1)), x] -beta_linreg = np.linalg.inv(xb.T.dot(xb)).dot(xb.T).dot(y) -print(beta_linreg) -sgdreg = SGDRegressor(n_iter = 50, penalty=None, eta0=0.1) -sgdreg.fit(x,y.ravel()) -print(sgdreg.intercept_, sgdreg.coef_) - -!ec - - - - -===== Gradient descent and Ridge ===== - -We have also discussed Ridge regression where the loss function contains a regularized given by the $L_2$ norm of $\beta$, -!bt -\[ -C_{\text{ridge}}(\beta) = ||X\beta -\mathbf{y}||^2 + \lambda ||\beta||^2, \ \lambda \geq 0. -\] -!et - -In order to minimize $C_{\text{ridge}}(\beta)$ using GD we only have adjust the gradient as follows -!bt -\[ -\nabla_\beta C_{\text{ridge}}(\beta) = 2\begin{bmatrix} \sum_{i=1}^{100} \left(\beta_0+\beta_1x_i-y_i\right) \\ -\sum_{i=1}^{100}\left( x_i (\beta_0+\beta_1x_i)-y_ix_i\right) \\ -\end{bmatrix} + 2\lambda\begin{bmatrix} \beta_0 \\ \beta_1\end{bmatrix} = 2 (X^T(X\beta - \mathbf{y})+\lambda \beta). -\] -!et - -We can now extend our program to minimize $C_{\text{ridge}}(\beta)$ using gradient descent and compare with the analytical solution given by -!bt -\[ -\beta_{\text{ridge}} = \left(X^T X + \lambda I_{2 \times 2} \right)^{-1} X^T \mathbf{y}, -\] -!et -for $\lambda = {0,1,10,50,100}$ ($\lambda = 0$ corresponds to ordinary least squares). -We can then compute $||\beta_{\text{ridge}}||$ for each $\lambda$. - -!bc pycod -import numpy as np - -""" -The following setup is just a suggestion, feel free to write it the way you like. -""" - -#Setup problem described in the exercise -N = 100 #Nr of datapoints -M = 2 #Nr of features -x = np.random.rand(N) -y = 5*x**2 + 0.1*np.random.randn(N) - - -#Compute analytic beta for Ridge regression -X = np.c_[np.ones(N),x] -XT_X = np.dot(X.T,X) - -l = 0.1 #Ridge parameter lambda -Id = np.eye(XT_X.shape[0]) - -Z = np.linalg.inv(XT_X+l*Id) -beta_ridge = np.dot(Z,np.dot(X.T,y)) - -print(beta_ridge) -print(np.linalg.norm(beta_ridge)) #||beta|| -!ec - - -===== Automatic differentiation ===== -Python has tools for so-called _automatic differentiation_. -Consider the following example -!bt -\[ -f(x) = \sin\left(2\pi x + x^2\right) -\] -!et -which has the following derivative -!bt -\[ -f'(x) = \cos\left(2\pi x + x^2\right)\left(2\pi + 2x\right) -\] -!et -Using _autograd_ we have - -!bc pycod -import autograd.numpy as np - -# To do elementwise differentiation: -from autograd import elementwise_grad as egrad - -# To plot: -import matplotlib.pyplot as plt - - -def f(x): - return np.sin(2*np.pi*x + x**2) - -def f_grad_analytic(x): - return np.cos(2*np.pi*x + x**2)*(2*np.pi + 2*x) - -# Do the comparison: -x = np.linspace(0,1,1000) - -f_grad = egrad(f) - -computed = f_grad(x) -analytic = f_grad_analytic(x) - -plt.title('Derivative computed from Autograd compared with the analytical derivative') -plt.plot(x,computed,label='autograd') -plt.plot(x,analytic,label='analytic') - -plt.xlabel('x') -plt.ylabel('y') -plt.legend() - -plt.show() - -print("The max absolute difference is: %g"%(np.max(np.abs(computed - analytic)))) -!ec - - -===== Using autograd ===== - -Here we -experiment with what kind of functions Autograd is capable -of finding the gradient of. The following Python functions are just -meant to illustrate what Autograd can do, but please feel free to -experiment with other, possibly more complicated, functions as well. - -!bc pycod -import autograd.numpy as np -from autograd import grad - -def f1(x): - return x**3 + 1 - -f1_grad = grad(f1) - -# Remember to send in float as argument to the computed gradient from Autograd! -a = 1.0 - -# See the evaluated gradient at a using autograd: -print("The gradient of f1 evaluated at a = %g using autograd is: %g"%(a,f1_grad(a))) - -# Compare with the analytical derivative, that is f1'(x) = 3*x**2 -grad_analytical = 3*a**2 -print("The gradient of f1 evaluated at a = %g by finding the analytic expression is: %g"%(a,grad_analytical)) -!ec - - - -===== Autograd with more complicated functions ===== - -To differentiate with respect to two (or more) arguments of a Python -function, Autograd need to know at which variable the function if -being differentiated with respect to. - -!bc pycod -import autograd.numpy as np -from autograd import grad -def f2(x1,x2): - return 3*x1**3 + x2*(x1 - 5) + 1 - -# By sending the argument 0, Autograd will compute the derivative w.r.t the first variable, in this case x1 -f2_grad_x1 = grad(f2,0) - -# ... and differentiate w.r.t x2 by sending 1 as an additional arugment to grad -f2_grad_x2 = grad(f2,1) - -x1 = 1.0 -x2 = 3.0 - -print("Evaluating at x1 = %g, x2 = %g"%(x1,x2)) -print("-"*30) - -# Compare with the analytical derivatives: - -# Derivative of f2 w.r.t x1 is: 9*x1**2 + x2: -f2_grad_x1_analytical = 9*x1**2 + x2 - -# Derivative of f2 w.r.t x2 is: x1 - 5: -f2_grad_x2_analytical = x1 - 5 - -# See the evaluated derivations: -print("The derivative of f2 w.r.t x1: %g"%( f2_grad_x1(x1,x2) )) -print("The analytical derivative of f2 w.r.t x1: %g"%( f2_grad_x1(x1,x2) )) - -print() - -print("The derivative of f2 w.r.t x2: %g"%( f2_grad_x2(x1,x2) )) -print("The analytical derivative of f2 w.r.t x2: %g"%( f2_grad_x2(x1,x2) )) -!ec - -Note that the grad function will not produce the true gradient of the function. The true gradient of a function with two or more variables will produce a vector, where each element is the function differentiated w.r.t a variable. - - - -===== More complicated functions using the elements of their arguments directly ===== - -!bc pycod -import autograd.numpy as np -from autograd import grad -def f3(x): # Assumes x is an array of length 5 or higher - return 2*x[0] + 3*x[1] + 5*x[2] + 7*x[3] + 11*x[4]**2 - -f3_grad = grad(f3) - -x = np.linspace(0,4,5) - -# Print the computed gradient: -print("The computed gradient of f3 is: ", f3_grad(x)) - -# The analytical gradient is: (2, 3, 5, 7, 22*x[4]) -f3_grad_analytical = np.array([2, 3, 5, 7, 22*x[4]]) - -# Print the analytical gradient: -print("The analytical gradient of f3 is: ", f3_grad_analytical) -!ec - -Note that in this case, when sending an array as input argument, the -output from Autograd is another array. This is the true gradient of -the function, as opposed to the function in the previous example. By -using arrays to represent the variables, the output from Autograd -might be easier to work with, as the output is closer to what one -could expect form a gradient-evaluting function. - - -===== Functions using mathematical functions from Numpy ===== - -!bc pycod -import autograd.numpy as np -from autograd import grad -def f4(x): - return np.sqrt(1+x**2) + np.exp(x) + np.sin(2*np.pi*x) - -f4_grad = grad(f4) - -x = 2.7 - -# Print the computed derivative: -print("The computed derivative of f4 at x = %g is: %g"%(x,f4_grad(x))) - -# The analytical derivative is: x/sqrt(1 + x**2) + exp(x) + cos(2*pi*x)*2*pi -f4_grad_analytical = x/np.sqrt(1 + x**2) + np.exp(x) + np.cos(2*np.pi*x)*2*np.pi - -# Print the analytical gradient: -print("The analytical gradient of f4 at x = %g is: %g"%(x,f4_grad_analytical)) -!ec - - - -!bc pycod -import autograd.numpy as np -from autograd import grad -def f5(x): - if x >= 0: - return x**2 - else: - return -3*x + 1 - -f5_grad = grad(f5) - -x = 2.7 - -# Print the computed derivative: -print("The computed derivative of f5 at x = %g is: %g"%(x,f5_grad(x))) -!ec - - -!bc pycod -import autograd.numpy as np -from autograd import grad -def f6_for(x): - val = 0 - for i in range(10): - val = val + x**i - return val - -def f6_while(x): - val = 0 - i = 0 - while i < 10: - val = val + x**i - i = i + 1 - return val - -f6_for_grad = grad(f6_for) -f6_while_grad = grad(f6_while) - -x = 0.5 - -# Print the computed derivaties of f6_for and f6_while -print("The computed derivative of f6_for at x = %g is: %g"%(x,f6_for_grad(x))) -print("The computed derivative of f6_while at x = %g is: %g"%(x,f6_while_grad(x))) -!ec -!bc pycod -import autograd.numpy as np -from autograd import grad -# Both of the functions are implementation of the sum: sum(x**i) for i = 0, ..., 9 -# The analytical derivative is: sum(i*x**(i-1)) -f6_grad_analytical = 0 -for i in range(10): - f6_grad_analytical += i*x**(i-1) - -print("The analytical derivative of f6 at x = %g is: %g"%(x,f6_grad_analytical)) -!ec - - -===== Using recursion ===== -!bc pycod -import autograd.numpy as np -from autograd import grad - -def f7(n): # Assume that n is an integer - if n == 1 or n == 0: - return 1 - else: - return n*f7(n-1) - -f7_grad = grad(f7) - -n = 2.0 - -print("The computed derivative of f7 at n = %d is: %g"%(n,f7_grad(n))) - -# The function f7 is an implementation of the factorial of n. -# By using the product rule, one can find that the derivative is: - -f7_grad_analytical = 0 -for i in range(int(n)-1): - tmp = 1 - for k in range(int(n)-1): - if k != i: - tmp *= (n - k) - f7_grad_analytical += tmp - -print("The analytical derivative of f7 at n = %d is: %g"%(n,f7_grad_analytical)) - -!ec -Note that if n is equal to zero or one, Autograd will give an error message. This message appears when the output is independent on input. - - -===== Unsupported functions ===== -Autograd supports many features. However, there are some functions that is not supported (yet) by Autograd. - -Assigning a value to the variable being differentiated with respect to -!bc pycod -import autograd.numpy as np -from autograd import grad -def f8(x): # Assume x is an array - x[2] = 3 - return x*2 - -f8_grad = grad(f8) - -x = 8.4 - -print("The derivative of f8 is:",f8_grad(x)) -!ec -Here, Autograd tells us that an 'ArrayBox' does not support item assignment. The item assignment is done when the program tries to assign x[2] to the value 3. However, Autograd has implemented the computation of the derivative such that this assignment is not possible. - - -===== The syntax a.dot(b) when finding the dot product ===== -!bc pycod -import autograd.numpy as np -from autograd import grad -def f9(a): # Assume a is an array with 2 elements - b = np.array([1.0,2.0]) - return a.dot(b) - -f9_grad = grad(f9) - -x = np.array([1.0,0.0]) - -print("The derivative of f9 is:",f9_grad(x)) -!ec - -Here we are told that the 'dot' function does not belong to Autograd's -version of a Numpy array. To overcome this, an alternative syntax -which also computed the dot product can be used: - -!bc pycod -import autograd.numpy as np -from autograd import grad -def f9_alternative(x): # Assume a is an array with 2 elements - b = np.array([1.0,2.0]) - return np.dot(x,b) # The same as x_1*b_1 + x_2*b_2 - -f9_alternative_grad = grad(f9_alternative) - -x = np.array([3.0,0.0]) - -print("The gradient of f9 is:",f9_alternative_grad(x)) - -# The analytical gradient of the dot product of vectors x and b with two elements (x_1,x_2) and (b_1, b_2) respectively -# w.r.t x is (b_1, b_2). -!ec - - -===== Recommended to avoid ===== -The documentation recommends to avoid inplace operations such as -!bc pycod -a += b -a -= b -a*= b -a /=b -!ec - - -===== Stochastic Gradient Descent ===== - -Stochastic gradient descent (SGD) and variants thereof address some of -the shortcomings of the Gradient descent method discussed above. - -The underlying idea of SGD comes from the observation that the cost -function, which we want to minimize, can almost always be written as a -sum over $n$ data points $\{\mathbf{x}_i\}_{i=1}^n$, -!bt -\[ -C(\mathbf{\beta}) = \sum_{i=1}^n c_i(\mathbf{x}_i, -\mathbf{\beta}). -\] -!et - - -This in turn means that the gradient can be -computed as a sum over $i$-gradients -!bt -\[ -\nabla_\beta C(\mathbf{\beta}) = \sum_i^n \nabla_\beta c_i(\mathbf{x}_i, -\mathbf{\beta}). -\] -!et - -Stochasticity/randomness is introduced by only taking the -gradient on a subset of the data called minibatches. If there are $n$ -data points and the size of each minibatch is $M$, there will be $n/M$ -minibatches. We denote these minibatches by $B_k$ where -$k=1,\cdots,n/M$. - - -As an example, suppose we have $10$ data points $(\mathbf{x}_1,\cdots, \mathbf{x}_{10})$ -and we choose to have $M=5$ minibathces, -then each minibatch contains two data points. In particular we have -$B_1 = (\mathbf{x}_1,\mathbf{x}_2), \cdots, B_5 = -(\mathbf{x}_9,\mathbf{x}_{10})$. Note that if you choose $M=1$ you -have only a single batch with all data points and on the other extreme, -you may choose $M=n$ resulting in a minibatch for each datapoint, i.e -$B_k = \mathbf{x}_k$. - -The idea is now to approximate the gradient by replacing the sum over -all data points with a sum over the data points in one the minibatches -picked at random in each gradient descent step -!bt -\[ -\nabla_{\beta} -C(\mathbf{\beta}) = \sum_{i=1}^n \nabla_\beta c_i(\mathbf{x}_i, -\mathbf{\beta}) \rightarrow \sum_{i \in B_k}^n \nabla_\beta -c_i(\mathbf{x}_i, \mathbf{\beta}). -\] -!et - - - -Thus a gradient descent step now looks like -!bt -\[ -\beta_{j+1} = \beta_j - \gamma_j \sum_{i \in B_k}^n \nabla_\beta c_i(\mathbf{x}_i, -\mathbf{\beta}) -\] -!et - -where $k$ is picked at random with equal -probability from $[1,n/M]$. An iteration over the number of -minibathces (n/M) is commonly referred to as an epoch. Thus it is -typical to choose a number of epochs and for each epoch iterate over -the number of minibatches, as exemplified in the code below. - - -!bc pycod -import numpy as np - -n = 100 #100 datapoints -M = 5 #size of each minibatch -m = int(n/M) #number of minibatches -n_epochs = 10 #number of epochs - -j = 0 -for epoch in range(1,n_epochs+1): - for i in range(m): - k = np.random.randint(m) #Pick the k-th minibatch at random - #Compute the gradient using the data in minibatch Bk - #Compute new suggestion for - j += 1 -!ec - -Taking the gradient only on a subset of the data has two important -benefits. First, it introduces randomness which decreases the chance -that our opmization scheme gets stuck in a local minima. Second, if -the size of the minibatches are small relative to the number of -datapoints ($M < n$), the computation of the gradient is much -cheaper since we sum over the datapoints in the $k-th$ minibatch and not -all $n$ datapoints. - - -A natural question is when do we stop the search for a new minimum? -One possibility is to compute the full gradient after a given number -of epochs and check if the norm of the gradient is smaller than some -threshold and stop if true. However, the condition that the gradient -is zero is valid also for local minima, so this would only tell us -that we are close to a local/global minimum. However, we could also -evaluate the cost function at this point, store the result and -continue the search. If the test kicks in at a later stage we can -compare the values of the cost function and keep the $\beta$ that -gave the lowest value. - - -Another approach is to let the step length $\gamma_j$ depend on the -number of epochs in such a way that it becomes very small after a -reasonable time such that we do not move at all. - -As an example, let $e = 0,1,2,3,\cdots$ denote the current epoch and let $t_0, t_1 > 0$ be two fixed numbers. Furthermore, let $t = e \cdot m + i$ where $m$ is the number of minibatches and $i=0,\cdots,m-1$. Then the function $$\gamma_j(t; t_0, t_1) = \frac{t_0}{t+t_1} $$ goes to zero as the number of epochs gets large. I.e. we start with a step length $\gamma_j (0; t_0, t_1) = t_0/t_1$ which decays in *time* $t$. - -In this way we can fix the number of epochs, compute $\beta$ and -evaluate the cost function at the end. Repeating the computation will -give a different result since the scheme is random by design. Then we -pick the final $\beta$ that gives the lowest value of the cost -function. - -!bc pycod -import numpy as np - -def step_length(t,t0,t1): - return t0/(t+t1) - -n = 100 #100 datapoints -M = 5 #size of each minibatch -m = int(n/M) #number of minibatches -n_epochs = 500 #number of epochs -t0 = 1.0 -t1 = 10 - -gamma_j = t0/t1 -j = 0 -for epoch in range(1,n_epochs+1): - for i in range(m): - k = np.random.randint(m) #Pick the k-th minibatch at random - #Compute the gradient using the data in minibatch Bk - #Compute new suggestion for beta - t = epoch*m+i - gamma_j = step_length(t,t0,t1) - j += 1 - -print("gamma_j after %d epochs: %g" % (n_epochs,gamma_j)) -!ec - - - -!bc pycod -# Importing various packages -from math import exp, sqrt -from random import random, seed -import numpy as np -import matplotlib.pyplot as plt -from sklearn.linear_model import SGDRegressor - -x = 2*np.random.rand(100,1) -y = 4+3*x+np.random.randn(100,1) - -xb = np.c_[np.ones((100,1)), x] -theta_linreg = np.linalg.inv(xb.T.dot(xb)).dot(xb.T).dot(y) -print("Own inversion") -print(theta_linreg) -sgdreg = SGDRegressor(n_iter = 50, penalty=None, eta0=0.1) -sgdreg.fit(x,y.ravel()) -print("sgdreg from scikit") -print(sgdreg.intercept_, sgdreg.coef_) - - -theta = np.random.randn(2,1) - -eta = 0.1 -Niterations = 1000 -m = 100 - -for iter in range(Niterations): - gradients = 2.0/m*xb.T.dot(xb.dot(theta)-y) - theta -= eta*gradients -print("theta frm own gd") -print(theta) - -xnew = np.array([[0],[2]]) -xbnew = np.c_[np.ones((2,1)), xnew] -ypredict = xbnew.dot(theta) -ypredict2 = xbnew.dot(theta_linreg) - - -n_epochs = 50 -t0, t1 = 5, 50 -m = 100 -def learning_schedule(t): - return t0/(t+t1) - -theta = np.random.randn(2,1) - -for epoch in range(n_epochs): - for i in range(m): - random_index = np.random.randint(m) - xi = xb[random_index:random_index+1] - yi = y[random_index:random_index+1] - gradients = 2 * xi.T.dot(xi.dot(theta)-yi) - eta = learning_schedule(epoch*m+i) - theta = theta - eta*gradients -print("theta from own sdg") -print(theta) - - - - - - -plt.plot(xnew, ypredict, "r-") -plt.plot(xnew, ypredict2, "b-") -plt.plot(x, y ,'ro') -plt.axis([0,2.0,0, 15.0]) -plt.xlabel(r'$x$') -plt.ylabel(r'$y$') -plt.title(r'Random numbers ') -plt.show() - -!ec - - -===== Using gradient descent methods, limitations ===== - -* _Gradient descent (GD) finds local minima of our function_. Since the GD algorithm is deterministic, if it converges, it will converge to a local minimum of our energy function. Because in ML we are often dealing with extremely rugged landscapes with many local minima, this can lead to poor performance. - -* _GD is sensitive to initial conditions_. One consequence of the local nature of GD is that initial conditions matter. Depending on where one starts, one will end up at a different local minima. Therefore, it is very important to think about how one initializes the training process. This is true for GD as well as more complicated variants of GD. - -* _Gradients are computationally expensive to calculate for large datasets_. In many cases in statistics and ML, the energy function is a sum of terms, with one term for each data point. For example, in linear regression, $E \propto \sum_{i=1}^n (y_i - \mathbf{w}^T\cdot\mathbf{x}_i)^2$; for logistic regression, the square error is replaced by the cross entropy. To calculate the gradient we have to sum over *all* $n$ data points. Doing this at every GD step becomes extremely computationally expensive. An ingenious solution to this, is to calculate the gradients using small subsets of the data called ``mini batches''. This has the added benefit of introducing stochasticity into our algorithm. - -* _GD is very sensitive to choices of learning rates_. GD is extremely sensitive to the choice of learning rates. If the learning rate is very small, the training process take an extremely long time. For larger learning rates, GD can diverge and give poor results. Furthermore, depending on what the local landscape looks like, we have to modify the learning rates to ensure convergence. Ideally, we would *adaptively* choose the learning rates to match the landscape. - -* _GD treats all directions in parameter space uniformly._ Another major drawback of GD is that unlike Newton's method, the learning rate for GD is the same in all directions in parameter space. For this reason, the maximum learning rate is set by the behavior of the steepest direction and this can significantly slow down training. Ideally, we would like to take large steps in flat directions and small steps in steep directions. Since we are exploring rugged landscapes where curvatures change, this requires us to keep track of not only the gradient but second derivatives. The ideal scenario would be to calculate the Hessian but this proves to be too computationally expensive. - -* GD can take exponential time to escape saddle points, even with random initialization. As we mentioned, GD is extremely sensitive to initial condition since it determines the particular local minimum GD would eventually reach. However, even with a good initialization scheme, through the introduction of randomness, GD can still take exponential time to escape saddle points. - - - -===== Momentum based GD ===== - -The stochastic gradient descent (SGD) is almost always used with a *momentum* or inertia term that serves as a memory of the direction we are moving in parameter space. This is typically -implemented as follows -!bt -\begin{align} -\mathbf{v}_{t}&=\gamma \mathbf{v}_{t-1}+\eta_{t}\nabla_\theta E(\boldsymbol{\theta}_t) \nonumber \\ -\boldsymbol{\theta}_{t+1}&= \boldsymbol{\theta}_t -\mathbf{v}_{t}, -\end{align} -!et -where we have introduced a momentum parameter $\gamma$, with $0\le\gamma\le 1$, and for brevity we dropped the explicit notation to indicate the gradient is to be taken over a different mini-batch at each step. We call this algorithm gradient descent with momentum (GDM). From these equations, it is clear that $\mathbf{v}_t$ is a running average of recently encountered gradients and $(1-\gamma)^{-1}$ sets the characteristic time scale for the memory used in the averaging procedure. Consistent with this, when $\gamma=0$, this just reduces down to ordinary SGD as discussed earlier. An equivalent way of writing the updates is -!bt -\[ -\Delta \boldsymbol{\theta}_{t+1} = \gamma \Delta \boldsymbol{\theta}_t -\ \eta_{t}\nabla_\theta E(\boldsymbol{\theta}_t), -\] -!et -where we have defined $\Delta \boldsymbol{\theta}_{t}= \boldsymbol{\theta}_t-\boldsymbol{\theta}_{t-1}$. - - -===== More on momentum based approaches ===== - -Let us try to get more intuition from these equations. It is helpful to consider a simple physical analogy with a particle of mass $m$ moving in a viscous medium with drag coefficient $\mu$ and potential -$E(\mathbf{w})$. If we denote the particle's position by $\mathbf{w}$, then its motion is described by -!bt -\[ -m {d^2 \mathbf{w} \over dt^2} + \mu {d \mathbf{w} \over dt }= -\nabla_w E(\mathbf{w}). -\] -!et -We can discretize this equation in the usual way to get -!bt -\[ -m { \mathbf{w}_{t+\Delta t}-2 \mathbf{w}_{t} +\mathbf{w}_{t-\Delta t} \over (\Delta t)^2}+\mu {\mathbf{w}_{t+\Delta t}- \mathbf{w}_{t} \over \Delta t} = -\nabla_w E(\mathbf{w}). -\] -!et -Rearranging this equation, we can rewrite this as -!bt -\[ -\Delta \mathbf{w}_{t +\Delta t}= - { (\Delta t)^2 \over m +\mu \Delta t} \nabla_w E(\mathbf{w})+ {m \over m +\mu \Delta t} \Delta \mathbf{w}_t. -\] -!et - - -===== Momentum parameter ===== -Notice that this equation is identical to previous one if we identify the position of the particle, $\mathbf{w}$, with the parameters $\boldsymbol{\theta}$. This allows -us to identify the momentum parameter and learning rate with the mass of the particle and the viscous drag as: -!bt -\[ -\gamma= {m \over m +\mu \Delta t }, \qquad \eta = {(\Delta t)^2 \over m +\mu \Delta t}. -\] -!et -Thus, as the name suggests, the momentum parameter is proportional to the mass of the particle and effectively provides inertia. Furthermore, in the large viscosity/small learning rate limit, our memory time scales as $(1-\gamma)^{-1} \approx m/(\mu \Delta t)$. - -Why is momentum useful? SGD momentum helps the gradient descent algorithm gain speed in directions with persistent but small gradients even in the presence of stochasticity, while suppressing oscillations in high-curvature directions. This becomes especially important in situations where the landscape is shallow and flat in some directions and narrow and steep in others. It has been argued that first-order methods (with appropriate initial conditions) can perform comparable to more expensive second order methods, especially in the context of complex deep learning models. - -These beneficial properties of momentum can sometimes become even more pronounced by using a slight modification of the classical momentum algorithm called Nesterov Accelerated Gradient (NAG). - -In the NAG algorithm, rather than calculating the gradient at the current parameters, $\nabla_\theta E(\boldsymbol{\theta}_t)$, one calculates the gradient at the expected value of the parameters given our current momentum, $\nabla_\theta E(\boldsymbol{\theta}_t +\gamma \mathbf{v}_{t-1})$. This yields the NAG update rule -!bt -\begin{align} -\mathbf{v}_{t}&=\gamma \mathbf{v}_{t-1}+\eta_{t}\nabla_\theta E(\boldsymbol{\theta}_t +\gamma \mathbf{v}_{t-1}) \nonumber \\ -\boldsymbol{\theta}_{t+1}&= \boldsymbol{\theta}_t -\mathbf{v}_{t}. -\end{align} -!et -One of the major advantages of NAG is that it allows for the use of a larger learning rate than GDM for the same choice of $\gamma$. - - - -In stochastic gradient descent, with and without momentum, we still -have to specify a schedule for tuning the learning rates $\eta_t$ -as a function of time. As discussed in the context of Newton's -method, this presents a number of dilemmas. The learning rate is -limited by the steepest direction which can change depending on the -current position in the landscape. To circumvent this problem, ideally -our algorithm would keep track of curvature and take large steps in -shallow, flat directions and small steps in steep, narrow directions. -Second-order methods accomplish this by calculating or approximating -the Hessian and normalizing the learning rate by the -curvature. However, this is very computationally expensive for -extremely large models. Ideally, we would like to be able to -adaptively change the step size to match the landscape without paying -the steep computational price of calculating or approximating -Hessians. - -Recently, a number of methods have been introduced that accomplish this by tracking not only the gradient, but also the second moment of the gradient. These methods include AdaGrad, AdaDelta, RMS-Prop, and ADAM. - - -===== RMS prop ===== - -In RMS prop, in addition to keeping a running average of the first moment of the gradient, we also keep track of the second moment denoted by $\mathbf{s}_t=\mathbb{E}[\mathbf{g}_t^2]$. The update rule for RMS prop is given by -!bt -\begin{align} -\mathbf{g}_t &= \nabla_\theta E(\boldsymbol{\theta}) \\ -\mathbf{s}_t &=\beta \mathbf{s}_{t-1} +(1-\beta)\mathbf{g}_t^2 \nonumber \\ -\boldsymbol{\theta}_{t+1}&=&\boldsymbol{\theta}_t - \eta_t { \mathbf{g}_t \over \sqrt{\mathbf{s}_t +\epsilon}}, \nonumber -\end{align} -!et -where $\beta$ controls the averaging time of the second moment and is typically taken to be about $\beta=0.9$, $\eta_t$ is a learning rate typically chosen to be $10^{-3}$, and $\epsilon\sim 10^{-8} $ is a small regularization constant to prevent divergences. Multiplication and division by vectors is understood as an element-wise operation. It is clear from this formula that the learning rate is reduced in directions where the norm of the gradient is consistently large. This greatly speeds up the convergence by allowing us to use a larger learning rate for flat directions. - - - -===== ADAM optimizer ===== - -A related algorithm is the ADAM optimizer. In ADAM, we keep a running average of both the first and second moment of the gradient and use this information to adaptively change the learning rate for different parameters. In addition to keeping a running average of the first and second moments of the gradient (i.e. $\mathbf{m}_t=\mathbb{E}[\mathbf{g}_t]$ and $\mathbf{s}_t=\mathbb{E}[\mathbf{g}^2_t]$, respectively), ADAM performs an additional bias correction to account for the fact that we are estimating the first two moments of the gradient using a running average (denoted by the hats in the update rule below). The update rule for ADAM is given by (where multiplication and division are once again understood to be element-wise operations below) -!bt -\begin{align} -\mathbf{g}_t &= \nabla_\theta E(\boldsymbol{\theta}) \\ -\mathbf{m}_t &= \beta_1 \mathbf{m}_{t-1} + (1-\beta_1) \mathbf{g}_t \nonumber \\ -\mathbf{s}_t &=\beta_2 \mathbf{s}_{t-1} +(1-\beta_2)\mathbf{g}_t^2 \nonumber \\ -\hat{\mathbf{m}}_t&={\mathbf{m}_t \over 1-\beta_1^t} \nonumber \\ -\hat{\mathbf{s}}_t &={\mathbf{s}_t \over1-\beta_2^t} \nonumber \\ -\boldsymbol{\theta}_{t+1}&=\boldsymbol{\theta}_t - \eta_t { \hat{\mathbf{m}}_t \over \sqrt{\hat{\mathbf{s}}_t} +\epsilon}, \nonumber \\ -\end{align} -!et -where $\beta_1$ and $\beta_2$ set the memory lifetime of the first and second moment and are typically taken to be $0.9$ and $0.99$ respectively, and $\eta$ and $\epsilon$ are identical to RMSprop. - -Like in RMSprop, the effective step size of a parameter depends on the magnitude of its gradient squared. To understand this better, let us rewrite this expression in terms of the variance $\boldsymbol{\sigma}_t^2 = \hat{\mathbf{s}}_t - (\hat{\mathbf{m}}_t)^2$. Consider a single parameter $\theta_t$. The update rule for this parameter is given by -!bt -\[ -\Delta \theta_{t+1}= -\eta_t { \hat{m}_t \over \sqrt{\sigma_t^2 + m_t^2 }+\epsilon}. -\] -!et - - - - - -===== Practical tips ===== - -* _Randomize the data when making mini-batches_. It is always important to randomly shuffle the data when forming mini-batches. Otherwise, the gradient descent method can fit spurious correlations resulting from the order in which data is presented. - -* _Transform your inputs_. Learning becomes difficult when our landscape has a mixture of steep and flat directions. One simple trick for minimizing these situations is to standardize the data by subtracting the mean and normalizing the variance of input variables. Whenever possible, also decorrelate the inputs. To understand why this is helpful, consider the case of linear regression. It is easy to show that for the squared error cost function, the Hessian of the energy matrix is just the correlation matrix between the inputs. Thus, by standardizing the inputs, we are ensuring that the landscape looks homogeneous in all directions in parameter space. Since most deep networks can be viewed as linear transformations followed by a non-linearity at each layer, we expect this intuition to hold beyond the linear case. - -* _Monitor the out-of-sample performance._ Always monitor the performance of your model on a validation set (a small portion of the training data that is held out of the training process to serve as a proxy for the test set. If the validation error starts increasing, then the model is beginning to overfit. Terminate the learning process. This *early stopping* significantly improves performance in many settings. - -* _Adaptive optimization methods don't always have good generalization._ Recent studies have shown that adaptive methods such as ADAM, RMSPorp, and AdaGrad tend to have poor generalization compared to SGD or SGD with momentum, particularly in the high-dimensional limit (i.e. the number of parameters exceeds the number of data points). Although it is not clear at this stage why these methods perform so well in training deep neural networks, simpler procedures like properly-tuned SGD may work as well or better in these applications. - - diff --git a/doc/LectureNotes/book.ipynb b/doc/LectureNotes/book.ipynb deleted file mode 100644 index 1b7eaafd4..000000000 --- a/doc/LectureNotes/book.ipynb +++ /dev/null @@ -1,2401 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "\n", - "# Data Analysis and Machine Learning\n", - "\n", - " \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: **Dec 22, 2019**\n", - "\n", - "Copyright 1999-2019, Morten Hjorth-Jensen. Released under CC Attribution-NonCommercial 4.0 license\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "# Introduction\n", - "\n", - "\n", - "During the last two decades there has been a swift and amazing\n", - "development of Machine Learning techniques and algorithms that impact\n", - "many areas in not only Science and Technology but also the Humanities,\n", - "Social Sciences, Medicine, Law, indeed, almost all possible\n", - "disciplines. The applications are incredibly many, from self-driving\n", - "cars to solving high-dimensional differential equations or complicated\n", - "quantum mechanical many-body problems. Machine Learning is perceived\n", - "by many as one of the main disruptive techniques nowadays. \n", - "\n", - "Statistics, Data science and Machine Learning form important\n", - "fields of research in modern science. They describe how to learn and\n", - "make predictions from data, as well as allowing us to extract\n", - "important correlations about physical process and the underlying laws\n", - "of motion in large data sets. The latter, big data sets, appear\n", - "frequently in essentially all disciplines, from the traditional\n", - "Science, Technology, Mathematics and Engineering fields to Life\n", - "Science, Law, education research, the Humanities and the Social\n", - "Sciences.\n", - "\n", - "It has become more\n", - "and more common to see research projects on big data in for example\n", - "the Social Sciences where extracting patterns from complicated survey\n", - "data is one of many research directions. Having a solid grasp of data\n", - "analysis and machine learning is thus becoming central to scientific\n", - "computing in many fields, and competences and skills within the fields\n", - "of machine learning and scientific computing are nowadays strongly\n", - "requested by many potential employers. The latter cannot be\n", - "overstated, familiarity with machine learning has almost become a\n", - "prerequisite for many of the most exciting employment opportunities,\n", - "whether they are in bioinformatics, life science, physics or finance,\n", - "in the private or the public sector. This author has had several\n", - "students or met students who have been hired recently based on their\n", - "skills and competences in scientific computing and data science, often\n", - "with marginal knowledge of machine learning.\n", - "\n", - "Machine learning is a subfield of computer science, and is closely\n", - "related to computational statistics. It evolved from the study of\n", - "pattern recognition in artificial intelligence (AI) research, and has\n", - "made contributions to AI tasks like computer vision, natural language\n", - "processing and speech recognition. Many of the methods we will study are also \n", - "strongly rooted in basic mathematics and physics research. \n", - "\n", - "Ideally, machine learning represents the science of giving computers\n", - "the ability to learn without being explicitly programmed. The idea is\n", - "that there exist generic algorithms which can be used to find patterns\n", - "in a broad class of data sets without having to write code\n", - "specifically for each problem. The algorithm will build its own logic\n", - "based on the data. You should however always keep in mind that\n", - "machines and algorithms are to a large extent developed by humans. The\n", - "insights and knowledge we have about a specific system, play a central\n", - "role when we develop a specific machine learning algorithm. \n", - "\n", - "Machine learning is an extremely rich field, in spite of its young\n", - "age. The increases we have seen during the last three decades in\n", - "computational capabilities have been followed by developments of\n", - "methods and techniques for analyzing and handling large date sets,\n", - "relying heavily on statistics, computer science and mathematics. The\n", - "field is rather new and developing rapidly. Popular software packages\n", - "written in Python for machine learning like\n", - "[Scikit-learn](http://scikit-learn.org/stable/),\n", - "[Tensorflow](https://www.tensorflow.org/),\n", - "[PyTorch](http://pytorch.org/) and [Keras](https://keras.io/), all\n", - "freely available at their respective GitHub sites, encompass\n", - "communities of developers in the thousands or more. And the number of\n", - "code developers and contributors keeps increasing. Not all the\n", - "algorithms and methods can be given a rigorous mathematical\n", - "justification, opening up thereby large rooms for experimenting and\n", - "trial and error and thereby exciting new developments. However, a\n", - "solid command of linear algebra, multivariate theory, probability\n", - "theory, statistical data analysis, understanding errors and Monte\n", - "Carlo methods are central elements in a proper understanding of many\n", - "of algorithms and methods we will discuss.\n", - "\n", - "\n", - "## Learning outcomes\n", - "\n", - "These sets of lectures aim at giving you an overview of central aspects of\n", - "statistical data analysis as well as some of the central algorithms\n", - "used in machine learning. We will introduce a variety of central\n", - "algorithms and methods essential for studies of data analysis and\n", - "machine learning. \n", - "\n", - "Hands-on projects and experimenting with data and algorithms plays a central role in\n", - "these lectures, and our hope is, through the various\n", - "projects and exercises, to expose you to fundamental\n", - "research problems in these fields, with the aim to reproduce state of\n", - "the art scientific results. You will learn to develop and\n", - "structure codes for studying these systems, get acquainted with\n", - "computing facilities and learn to handle large scientific projects. A\n", - "good scientific and ethical conduct is emphasized throughout the\n", - "course. More specifically, you will\n", - "\n", - "1. Learn about basic data analysis, Bayesian statistics, Monte Carlo methods, data optimization and machine learning;\n", - "\n", - "2. Be capable of extending the acquired knowledge to other systems and cases;\n", - "\n", - "3. Have an understanding of central algorithms used in data analysis and machine learning;\n", - "\n", - "4. Gain knowledge of central aspects of Monte Carlo methods, Markov chains, Gibbs samplers and their possible applications, from numerical integration to simulation of stock markets;\n", - "\n", - "5. Understand methods for regression and classification;\n", - "\n", - "6. Learn about neural network, genetic algorithms and Boltzmann machines;\n", - "\n", - "7. Work on numerical projects to illustrate the theory. The projects play a central role and you are expected to know modern programming languages like Python or C++, in addition to a basic knowledge of linear algebra (typically taught during the first one or two years of undergraduate studies).\n", - "\n", - "There are several topics we will cover here, spanning from \n", - "statistical data analysis and its basic concepts such as expectation\n", - "values, variance, covariance, correlation functions and errors, via\n", - "well-known probability distribution functions like the uniform\n", - "distribution, the binomial distribution, the Poisson distribution and\n", - "simple and multivariate normal distributions to central elements of\n", - "Bayesian statistics and modeling. We will also remind the reader about\n", - "central elements from linear algebra and standard methods based on\n", - "linear algebra used to optimize (minimize) functions (the family of gradient descent methods)\n", - "and the Singular-value decomposition and\n", - "least square methods for parameterizing data.\n", - "\n", - "We will also cover Monte Carlo methods, Markov chains, well-known\n", - "algorithms for sampling stochastic events like the Metropolis-Hastings\n", - "and Gibbs sampling methods. An important aspect of all our\n", - "calculations is a proper estimation of errors. Here we will also\n", - "discuss famous resampling techniques like the blocking, the bootstrapping\n", - "and the jackknife methods and the infamous bias-variance tradeoff. \n", - "\n", - "The second part of the material covers several algorithms used in\n", - "machine learning.\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "## Types of Machine Learning\n", - "\n", - "\n", - "The approaches to machine learning are many, but are often split into\n", - "two main categories. In *supervised learning* we know the answer to a\n", - "problem, and let the computer deduce the logic behind it. On the other\n", - "hand, *unsupervised learning* is a method for finding patterns and\n", - "relationship in data sets without any prior knowledge of the system.\n", - "Some authours also operate with a third category, namely\n", - "*reinforcement learning*. This is a paradigm of learning inspired by\n", - "behavioral psychology, where learning is achieved by trial-and-error,\n", - "solely from rewards and punishment.\n", - "\n", - "Another way to categorize machine learning tasks is to consider the\n", - "desired output of a system. Some of the most common tasks are:\n", - "\n", - " * Classification: Outputs are divided into two or more classes. The goal is to produce a model that assigns inputs into one of these classes. An example is to identify digits based on pictures of hand-written ones. Classification is typically supervised learning.\n", - "\n", - " * Regression: Finding a functional relationship between an input data set and a reference data set. The goal is to construct a function that maps input data to continuous output values.\n", - "\n", - " * Clustering: Data are divided into groups with certain common traits, without knowing the different groups beforehand. It is thus a form of unsupervised learning.\n", - "\n", - "The methods we cover have three main topics in common, irrespective of\n", - "whether we deal with supervised or unsupervised learning. The first\n", - "ingredient is normally our data set (which can be subdivided into\n", - "training and test data), the second item is a model which is normally\n", - "a function of some parameters. The model reflects our knowledge of\n", - "the system (or lack thereof). As an example, if we know that our data\n", - "show a behavior similar to what would be predicted by a polynomial,\n", - "fitting our data to a polynomial of some degree would then determin\n", - "our model.\n", - "\n", - "The last ingredient is a so-called **cost**\n", - "function which allows us to present an estimate on how good our model\n", - "is in reproducing the data it is supposed to train. \n", - "\n", - "Here we will build our machine learning approach on elements of the\n", - "statistical foundation discussed above, with elements from data\n", - "analysis, stochastic processes etc. We will discuss the following\n", - "machine learning algorithms\n", - "\n", - "1. Linear regression and its variants\n", - "\n", - "2. Decision tree algorithms, from single trees to random forests\n", - "\n", - "3. Bayesian statistics and regression\n", - "\n", - "4. Support vector machines and finally various variants of\n", - "\n", - "5. Artifical neural networks and deep learning, including convolutional neural networks and Bayesian neural networks\n", - "\n", - "6. Networks for unsupervised learning using for example reduced Boltzmann machines.\n", - "\n", - "## Choice of programming language\n", - "\n", - "Python plays nowadays a central role in the development of machine\n", - "learning techniques and tools for data analysis. In particular, seen\n", - "the wealth of machine learning and data analysis libraries written in\n", - "Python, easy to use libraries with immediate visualization(and not the\n", - "least impressive galleries of existing examples), the popularity of the\n", - "Jupyter notebook framework with the possibility to run **R** codes or\n", - "compiled programs written in C++, and much more made our choice of\n", - "programming language for this series of lectures easy. However,\n", - "since the focus here is not only on using existing Python libraries such\n", - "as **Scikit-Learn** or **Tensorflow**, but also on developing your own\n", - "algorithms and codes, we will as far as possible present many of these\n", - "algorithms either as a Python codes or C++ or Fortran (or other languages) codes. \n", - "\n", - "The reason we also focus on compiled languages like C++ (or\n", - "Fortran), is that Python is still notoriously slow when we do not\n", - "utilize highly streamlined computational libraries like\n", - "[Lapack](http://www.netlib.org/lapack/) or other numerical libraries\n", - "written in compiled languages (many of these libraries are written in\n", - "Fortran). Although a project like [Numba](https://numba.pydata.org/)\n", - "holds great promise for speeding up the unrolling of lengthy loops, C++\n", - "and Fortran are presently still the performance winners. Numba gives\n", - "you potentially the power to speed up your applications with high\n", - "performance functions written directly in Python. In particular,\n", - "array-oriented and math-heavy Python code can achieve similar\n", - "performance to C, C++ and Fortran. However, even with these speed-ups,\n", - "for codes involving heavy Markov Chain Monte Carlo analyses and\n", - "optimizations of cost functions, C++/C or Fortran codes tend to\n", - "outperform Python codes. \n", - "\n", - "Presently thus, the community tends to let\n", - "code written in C++/C or Fortran do the heavy duty numerical\n", - "number crunching and leave the post-analysis of the data to the above\n", - "mentioned Python modules or software packages. However, with the developments taking place in for example the Python community, and seen\n", - "the changes during the last decade, the above situation may change swiftly in the not too distant future. \n", - "\n", - "Many of the examples we discuss in this series of lectures come with\n", - "existing data files or provide code examples which produce the data to\n", - "be analyzed. Most of the applications we will discuss deal with\n", - "small data sets (less than a terabyte of information) and can easily\n", - "be analyzed and tested on standard off the shelf laptops you find in general \n", - "stores.\n", - "\n", - "## Data handling, machine learning and ethical aspects\n", - "\n", - "In most of the cases we will study, we will either generate the data\n", - "to analyze ourselves (both for supervised learning and unsupervised\n", - "learning) or we will recur again and again to data present in say\n", - "**Scikit-Learn** or **Tensorflow**. Many of the examples we end up\n", - "dealing with are from a privacy and data protection point of view,\n", - "rather inoccuous and boring results of numerical\n", - "calculations. However, this does not hinder us from developing a sound\n", - "ethical attitude to the data we use, how we analyze the data and how\n", - "we handle the data.\n", - "\n", - "The most immediate and simplest possible ethical aspects deal with our\n", - "approach to the scientific process. Nowadays, with version control\n", - "software like [Git](https://git-scm.com/) and various online\n", - "repositories like [Github](https://github.com/),\n", - "[Gitlab](https://about.gitlab.com/) etc, we can easily make our codes\n", - "and data sets we have used, freely and easily accessible to a wider\n", - "community. This helps us almost automagically in making our science\n", - "reproducible. The large open-source development communities involved\n", - "in say [Scikit-Learn](http://scikit-learn.org/stable/),\n", - "[Tensorflow](https://www.tensorflow.org/),\n", - "[PyTorch](http://pytorch.org/) and [Keras](https://keras.io/), are\n", - "all excellent examples of this. The codes can be tested and improved\n", - "upon continuosly, helping thereby our scientific community at large in\n", - "developing data analysis and machine learning tools. It is much\n", - "easier today to gain traction and acceptance for making your science\n", - "reproducible. From a societal stand, this is an important element\n", - "since many of the developers are employees of large public institutions like\n", - "universities and research labs. Our fellow taxpayers do deserve to get\n", - "something back for their bucks.\n", - "\n", - "However, this more mechanical aspect of the ethics of science (in\n", - "particular the reproducibility of scientific results) is something\n", - "which is obvious and everybody should do so as part of the dialectics of\n", - "science. The fact that many scientists are not willing to share their codes or \n", - "data is detrimental to the scientific discourse.\n", - "\n", - "Before we proceed, we should add a disclaimer. Even though\n", - "we may dream of computers developing some kind of higher learning\n", - "capabilities, at the end (even if the artificial intelligence\n", - "community keeps touting our ears full of fancy futuristic avenues), it is we, yes you reading these lines,\n", - "who end up constructing and instructing, via various algorithms, the\n", - "machine learning approaches. Self-driving cars for example, rely on sofisticated\n", - "programs which take into account all possible situations a car can\n", - "encounter. In addition, extensive usage of training data from GPS\n", - "information, maps etc, are typically fed into the software for\n", - "self-driving cars. Adding to this various sensors and cameras that\n", - "feed information to the programs, there are zillions of ethical issues\n", - "which arise from this.\n", - "\n", - "For self-driving cars, where basically many of the standard machine\n", - "learning algorithms discussed here enter into the codes, at a certain\n", - "stage we have to make choices. Yes, we , the lads and lasses who wrote\n", - "a program for a specific brand of a self-driving car. As an example,\n", - "all carmakers have as their utmost priority the security of the\n", - "driver and the accompanying passengers. A famous European carmaker, which is\n", - "one of the leaders in the market of self-driving cars, had **if**\n", - "statements of the following type: suppose there are two obstacles in\n", - "front of you and you cannot avoid to collide with one of them. One of\n", - "the obstacles is a monstertruck while the other one is a kindergarten\n", - "class trying to cross the road. The self-driving car algo would then\n", - "opt for the hitting the small folks instead of the monstertruck, since\n", - "the likelihood of surving a collision with our future citizens, is\n", - "much higher.\n", - "\n", - "This leads to serious ethical aspects. Why should we opt for such an\n", - "option? Who decides and who is entitled to make such choices? Keep in\n", - "mind that many of the algorithms you will encounter in this series of\n", - "lectures or hear about later, are indeed based on simple programming\n", - "instructions. And you are very likely to be one of the people who may\n", - "end up writing such a code. Thus, developing a sound ethical attitude\n", - "to what we do, an approach well beyond the simple mechanistic one of\n", - "making our science available and reproducible, is much needed. The\n", - "example of the self-driving cars is just one of infinitely many cases\n", - "where we have to make choices. When you analyze data on economic\n", - "inequalities, who guarantees that you are not weighting some data in a\n", - "particular way, perhaps because you dearly want a specific conclusion\n", - "which may support your political views? Or what about the recent\n", - "claims that a famous IT company like Apple has a sexist bias on the\n", - "their recently [launched credit card](https://qz.com/1748321/the-role-of-goldman-sachs-algorithms-in-the-apple-credit-card-scandal/)?\n", - "\n", - "We do not have the answers here, nor will we venture into a deeper\n", - "discussions of these aspects, but we want you think over these topics\n", - "in a more overarching way. A statistical data analysis with its dry\n", - "numbers and graphs meant to guide the eye, does not necessarily\n", - "reflect the truth, whatever that is. As a scientist, and after a\n", - "university education, you are supposedly a better citizen, with an\n", - "improved critical view and understanding of the scientific method, and\n", - "perhaps some deeper understanding of the ethics of science at\n", - "large. Use these insights. Be a critical citizen. You owe it to our\n", - "society.\n", - "\n", - "\n", - "# Machine Learning Overview with Selectec Examples\n", - "\n", - "\n", - "## Introduction\n", - "\n", - "Our emphasis throughout this series of lectures \n", - "is on understanding the mathematical aspects of\n", - "different algorithms used in the fields of data analysis and machine learning. \n", - "\n", - "However, where possible we will emphasize the\n", - "importance of using available software. We start thus with a hands-on\n", - "and top-down approach to machine learning. The aim is thus to start with\n", - "relevant data or data we have produced \n", - "and use these to introduce statistical data analysis\n", - "concepts and machine learning algorithms before we delve into the\n", - "algorithms themselves. The examples we will use in the beginning, start with simple\n", - "polynomials with random noise added. We will use the Python\n", - "software package [Scikit-Learn](http://scikit-learn.org/stable/) and\n", - "introduce various machine learning algorithms to make fits of\n", - "the data and predictions. We move thereafter to more interesting\n", - "cases such as data from say experiments (below we will look at experimental nuclear binding energies as an example).\n", - "These are examples where we can easily set up the data and\n", - "then use machine learning algorithms included in for example\n", - "**Scikit-Learn**. \n", - "\n", - "These examples will serve us the purpose of getting\n", - "started. Furthermore, they allow us to catch more than two birds with\n", - "a stone. They will allow us to bring in some programming specific\n", - "topics and tools as well as showing the power of various Python \n", - "libraries for machine learning and statistical data analysis. \n", - "\n", - "Here, we will mainly focus on two\n", - "specific Python packages for Machine Learning, Scikit-Learn and\n", - "Tensorflow (see below for links etc). Moreover, the examples we\n", - "introduce will serve as inputs to many of our discussions later, as\n", - "well as allowing you to set up models and produce your own data and\n", - "get started with programming.\n", - "\n", - "\n", - "\n", - "## What is Machine Learning?\n", - "\n", - "Statistics, data science and machine learning form important fields of\n", - "research in modern science. They describe how to learn and make\n", - "predictions from data, as well as allowing us to extract important\n", - "correlations about physical process and the underlying laws of motion\n", - "in large data sets. The latter, big data sets, appear frequently in\n", - "essentially all disciplines, from the traditional Science, Technology,\n", - "Mathematics and Engineering fields to Life Science, Law, education\n", - "research, the Humanities and the Social Sciences. \n", - "\n", - "It has become more\n", - "and more common to see research projects on big data in for example\n", - "the Social Sciences where extracting patterns from complicated survey\n", - "data is one of many research directions. Having a solid grasp of data\n", - "analysis and machine learning is thus becoming central to scientific\n", - "computing in many fields, and competences and skills within the fields\n", - "of machine learning and scientific computing are nowadays strongly\n", - "requested by many potential employers. The latter cannot be\n", - "overstated, familiarity with machine learning has almost become a\n", - "prerequisite for many of the most exciting employment opportunities,\n", - "whether they are in bioinformatics, life science, physics or finance,\n", - "in the private or the public sector. This author has had several\n", - "students or met students who have been hired recently based on their\n", - "skills and competences in scientific computing and data science, often\n", - "with marginal knowledge of machine learning.\n", - "\n", - "Machine learning is a subfield of computer science, and is closely\n", - "related to computational statistics. It evolved from the study of\n", - "pattern recognition in artificial intelligence (AI) research, and has\n", - "made contributions to AI tasks like computer vision, natural language\n", - "processing and speech recognition. Many of the methods we will study are also \n", - "strongly rooted in basic mathematics and physics research. \n", - "\n", - "Ideally, machine learning represents the science of giving computers\n", - "the ability to learn without being explicitly programmed. The idea is\n", - "that there exist generic algorithms which can be used to find patterns\n", - "in a broad class of data sets without having to write code\n", - "specifically for each problem. The algorithm will build its own logic\n", - "based on the data. You should however always keep in mind that\n", - "machines and algorithms are to a large extent developed by humans. The\n", - "insights and knowledge we have about a specific system, play a central\n", - "role when we develop a specific machine learning algorithm. \n", - "\n", - "Machine learning is an extremely rich field, in spite of its young\n", - "age. The increases we have seen during the last three decades in\n", - "computational capabilities have been followed by developments of\n", - "methods and techniques for analyzing and handling large date sets,\n", - "relying heavily on statistics, computer science and mathematics. The\n", - "field is rather new and developing rapidly. Popular software packages\n", - "written in Python for machine learning like\n", - "[Scikit-learn](http://scikit-learn.org/stable/),\n", - "[Tensorflow](https://www.tensorflow.org/),\n", - "[PyTorch](http://pytorch.org/) and [Keras](https://keras.io/), all\n", - "freely available at their respective GitHub sites, encompass\n", - "communities of developers in the thousands or more. And the number of\n", - "code developers and contributors keeps increasing. Not all the\n", - "algorithms and methods can be given a rigorous mathematical\n", - "justification, opening up thereby large rooms for experimenting and\n", - "trial and error and thereby exciting new developments. However, a\n", - "solid command of linear algebra, multivariate theory, probability\n", - "theory, statistical data analysis, understanding errors and Monte\n", - "Carlo methods are central elements in a proper understanding of many\n", - "of algorithms and methods we will discuss.\n", - "\n", - "\n", - "\n", - "## Types of Machine Learning\n", - "\n", - "\n", - "The approaches to machine learning are many, but are often split into\n", - "two main categories. In *supervised learning* we know the answer to a\n", - "problem, and let the computer deduce the logic behind it. On the other\n", - "hand, *unsupervised learning* is a method for finding patterns and\n", - "relationship in data sets without any prior knowledge of the system.\n", - "Some authours also operate with a third category, namely\n", - "*reinforcement learning*. This is a paradigm of learning inspired by\n", - "behavioral psychology, where learning is achieved by trial-and-error,\n", - "solely from rewards and punishment.\n", - "\n", - "Another way to categorize machine learning tasks is to consider the\n", - "desired output of a system. Some of the most common tasks are:\n", - "\n", - " * Classification: Outputs are divided into two or more classes. The goal is to produce a model that assigns inputs into one of these classes. An example is to identify digits based on pictures of hand-written ones. Classification is typically supervised learning.\n", - "\n", - " * Regression: Finding a functional relationship between an input data set and a reference data set. The goal is to construct a function that maps input data to continuous output values.\n", - "\n", - " * Clustering: Data are divided into groups with certain common traits, without knowing the different groups beforehand. It is thus a form of unsupervised learning.\n", - "\n", - "The methods we cover have three main topics in common, irrespective of\n", - "whether we deal with supervised or unsupervised learning. The first\n", - "ingredient is normally our data set (which can be subdivided into\n", - "training and test data), the second item is a model which is normally a\n", - "function of some parameters. The model reflects our knowledge of the system (or lack thereof). As an example, if we know that our data show a behavior similar to what would be predicted by a polynomial, fitting our data to a polynomial of some degree would then determin our model. \n", - "\n", - "The last ingredient is a so-called **cost**\n", - "function which allows us to present an estimate on how good our model\n", - "is in reproducing the data it is supposed to train. \n", - "At the heart of basically all ML algorithms there are so-called minimization algorithms, often we end up with various variants of **gradient** methods.\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "## Software and needed installations\n", - "\n", - "We will make extensive use of Python as programming language and its\n", - "myriad of available libraries. You will find\n", - "Jupyter notebooks invaluable in your work. You can run **R**\n", - "codes in the Jupyter/IPython notebooks, with the immediate benefit of\n", - "visualizing your data. You can also use compiled languages like C++,\n", - "Rust, Julia, Fortran etc if you prefer. The focus in these lectures will be\n", - "on Python.\n", - "\n", - "\n", - "If you have Python installed (we strongly recommend Python3) and you feel\n", - "pretty familiar with installing different packages, we recommend that\n", - "you install the following Python packages via **pip** as \n", - "\n", - "1. pip install numpy scipy matplotlib ipython scikit-learn mglearn sympy pandas pillow \n", - "\n", - "For Python3, replace **pip** with **pip3**.\n", - "\n", - "For OSX users we recommend, after having installed Xcode, to\n", - "install **brew**. Brew allows for a seamless installation of additional\n", - "software via for example \n", - "\n", - "1. brew install python3\n", - "\n", - "For Linux users, with its variety of distributions like for example the widely popular Ubuntu distribution,\n", - "you can use **pip** as well and simply install Python as \n", - "\n", - "1. sudo apt-get install python3 (or python for pyhton2.7)\n", - "\n", - "etc etc. \n", - "\n", - "\n", - "\n", - "## Python installers\n", - "\n", - "If you don't want to perform these operations separately and venture\n", - "into the hassle of exploring how to set up dependencies and paths, we\n", - "recommend two widely used distrubutions which set up all relevant\n", - "dependencies for Python, namely \n", - "\n", - "* [Anaconda](https://docs.anaconda.com/), \n", - "\n", - "which is an open source\n", - "distribution of the Python and R programming languages for large-scale\n", - "data processing, predictive analytics, and scientific computing, that\n", - "aims to simplify package management and deployment. Package versions\n", - "are managed by the package management system **conda**. \n", - "\n", - "* [Enthought canopy](https://www.enthought.com/product/canopy/) \n", - "\n", - "is a Python\n", - "distribution for scientific and analytic computing distribution and\n", - "analysis environment, available for free and under a commercial\n", - "license.\n", - "\n", - "Furthermore, [Google's Colab](https://colab.research.google.com/notebooks/welcome.ipynb) is a free Jupyter notebook environment that requires \n", - "no setup and runs entirely in the cloud. Try it out!\n", - "\n", - "## Useful Python libraries\n", - "Here we list several useful Python libraries we strongly recommend (if you use anaconda many of these are already there)\n", - "\n", - "* [NumPy](https://www.numpy.org/) is a highly popular library for large, multi-dimensional arrays and matrices, along with a large collection of high-level mathematical functions to operate on these arrays\n", - "\n", - "* [The pandas](https://pandas.pydata.org/) library provides high-performance, easy-to-use data structures and data analysis tools \n", - "\n", - "* [Xarray](http://xarray.pydata.org/en/stable/) is a Python package that makes working with labelled multi-dimensional arrays simple, efficient, and fun!\n", - "\n", - "* [Scipy](https://www.scipy.org/) (pronounced “Sigh Pie”) is a Python-based ecosystem of open-source software for mathematics, science, and engineering. \n", - "\n", - "* [Matplotlib](https://matplotlib.org/) is a Python 2D plotting library which produces publication quality figures in a variety of hardcopy formats and interactive environments across platforms.\n", - "\n", - "* [Autograd](https://github.com/HIPS/autograd) can automatically differentiate native Python and Numpy code. It can handle a large subset of Python's features, including loops, ifs, recursion and closures, and it can even take derivatives of derivatives of derivatives\n", - "\n", - "* [SymPy](https://www.sympy.org/en/index.html) is a Python library for symbolic mathematics. \n", - "\n", - "* [scikit-learn](https://scikit-learn.org/stable/) has simple and efficient tools for machine learning, data mining and data analysis\n", - "\n", - "* [TensorFlow](https://www.tensorflow.org/) is a Python library for fast numerical computing created and released by Google\n", - "\n", - "* [Keras](https://keras.io/) is a high-level neural networks API, written in Python and capable of running on top of TensorFlow, CNTK, or Theano\n", - "\n", - "* And many more such as [pytorch](https://pytorch.org/), [Theano](https://pypi.org/project/Theano/) etc \n", - "\n", - "## Installing R, C++, cython or Julia\n", - "\n", - "You will also find it convenient to utilize **R**. We will mainly\n", - "use Python during our lectures and in various projects and exercises.\n", - "Those of you\n", - "already familiar with **R** should feel free to continue using **R**, keeping\n", - "however an eye on the parallel Python set ups. Similarly, if you are a\n", - "Python afecionado, feel free to explore **R** as well. Jupyter/Ipython\n", - "notebook allows you to run **R** codes interactively in your\n", - "browser. The software library **R** is really tailored for statistical data analysis\n", - "and allows for an easy usage of the tools and algorithms we will discuss in these\n", - "lectures.\n", - "\n", - "To install **R** with Jupyter notebook \n", - "[follow the link here](https://mpacer.org/maths/r-kernel-for-ipython-notebook)\n", - "\n", - "\n", - "\n", - "\n", - "## Installing R, C++, cython, Numba etc\n", - "\n", - "\n", - "For the C++ aficionados, Jupyter/IPython notebook allows you also to\n", - "install C++ and run codes written in this language interactively in\n", - "the browser. Since we will emphasize writing many of the algorithms\n", - "yourself, you can thus opt for either Python or C++ (or Fortran or other compiled languages) as programming\n", - "languages.\n", - "\n", - "To add more entropy, **cython** can also be used when running your\n", - "notebooks. It means that Python with the jupyter notebook\n", - "setup allows you to integrate widely popular softwares and tools for\n", - "scientific computing. Similarly, the \n", - "[Numba Python package](https://numba.pydata.org/) delivers increased performance\n", - "capabilities with minimal rewrites of your codes. With its\n", - "versatility, including symbolic operations, Python offers a unique\n", - "computational environment. Your jupyter notebook can easily be\n", - "converted into a nicely rendered **PDF** file or a Latex file for\n", - "further processing. For example, convert to latex as" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - " pycod jupyter nbconvert filename.ipynb --to latex \n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "And to add more versatility, the Python package [SymPy](http://www.sympy.org/en/index.html) is a Python library for symbolic mathematics. It aims to become a full-featured computer algebra system (CAS) and is entirely written in Python. \n", - "\n", - "Finally, if you wish to use the light mark-up language \n", - "[doconce](https://github.com/hplgit/doconce) you can convert a standard ascii text file into various HTML \n", - "formats, ipython notebooks, latex files, pdf files etc with minimal edits. These lectures were generated using **doconce**.\n", - "\n", - "\n", - "\n", - "## Numpy examples and Important Matrix and vector handling packages\n", - "\n", - "There are several central software libraries for linear algebra and eigenvalue problems. Several of the more\n", - "popular ones have been wrapped into ofter software packages like those from the widely used text **Numerical Recipes**. The original source codes in many of the available packages are often taken from the widely used\n", - "software package LAPACK, which follows two other popular packages\n", - "developed in the 1970s, namely EISPACK and LINPACK. We describe them shortly here.\n", - "\n", - " * LINPACK: package for linear equations and least square problems.\n", - "\n", - " * LAPACK:package for solving symmetric, unsymmetric and generalized eigenvalue problems. From LAPACK's website it is possible to download for free all source codes from this library. Both C/C++ and Fortran versions are available.\n", - "\n", - " * BLAS (I, II and III): (Basic Linear Algebra Subprograms) are routines that provide standard building blocks for performing basic vector and matrix operations. Blas I is vector operations, II vector-matrix operations and III matrix-matrix operations. Highly parallelized and efficient codes, all available for download from .\n", - "\n", - "## Basic Matrix Features\n", - "\n", - "**Matrix properties reminder.**" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\mathbf{A} =\n", - " \\begin{bmatrix} a_{11} & a_{12} & a_{13} & a_{14} \\\\\n", - " a_{21} & a_{22} & a_{23} & a_{24} \\\\\n", - " a_{31} & a_{32} & a_{33} & a_{34} \\\\\n", - " a_{41} & a_{42} & a_{43} & a_{44}\n", - " \\end{bmatrix}\\qquad\n", - "\\mathbf{I} =\n", - " \\begin{bmatrix} 1 & 0 & 0 & 0 \\\\\n", - " 0 & 1 & 0 & 0 \\\\\n", - " 0 & 0 & 1 & 0 \\\\\n", - " 0 & 0 & 0 & 1\n", - " \\end{bmatrix}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The inverse of a matrix is defined by" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\mathbf{A}^{-1} \\cdot \\mathbf{A} = I\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "
Relations Name matrix elements
$A = A^{T}$ symmetric $a_{ij} = a_{ji}$
$A = \\left (A^{T} \\right )^{-1}$ real orthogonal $\\sum_k a_{ik} a_{jk} = \\sum_k a_{ki} a_{kj} = \\delta_{ij}$
$A = A^{ * }$ real matrix $a_{ij} = a_{ij}^{ * }$
$A = A^{\\dagger}$ hermitian $a_{ij} = a_{ji}^{ * }$
$A = \\left (A^{\\dagger} \\right )^{-1}$ unitary $\\sum_k a_{ik} a_{jk}^{ * } = \\sum_k a_{ki}^{ * } a_{kj} = \\delta_{ij}$
\n", - "\n", - "\n", - "\n", - "\n", - "### Some famous Matrices\n", - "\n", - " * Diagonal if $a_{ij}=0$ for $i\\ne j$\n", - "\n", - " * Upper triangular if $a_{ij}=0$ for $i > j$\n", - "\n", - " * Lower triangular if $a_{ij}=0$ for $i < j$\n", - "\n", - " * Upper Hessenberg if $a_{ij}=0$ for $i > j+1$\n", - "\n", - " * Lower Hessenberg if $a_{ij}=0$ for $i < j+1$\n", - "\n", - " * Tridiagonal if $a_{ij}=0$ for $|i -j| > 1$\n", - "\n", - " * Lower banded with bandwidth $p$: $a_{ij}=0$ for $i > j+p$\n", - "\n", - " * Upper banded with bandwidth $p$: $a_{ij}=0$ for $i < j+p$\n", - "\n", - " * Banded, block upper triangular, block lower triangular....\n", - "\n", - "### More Basic Matrix Features\n", - "\n", - "**Some Equivalent Statements.**\n", - "\n", - "For an $N\\times N$ matrix $\\mathbf{A}$ the following properties are all equivalent\n", - "\n", - " * If the inverse of $\\mathbf{A}$ exists, $\\mathbf{A}$ is nonsingular.\n", - "\n", - " * The equation $\\mathbf{Ax}=0$ implies $\\mathbf{x}=0$.\n", - "\n", - " * The rows of $\\mathbf{A}$ form a basis of $R^N$.\n", - "\n", - " * The columns of $\\mathbf{A}$ form a basis of $R^N$.\n", - "\n", - " * $\\mathbf{A}$ is a product of elementary matrices.\n", - "\n", - " * $0$ is not eigenvalue of $\\mathbf{A}$.\n", - "\n", - "\n", - "\n", - "\n", - "## Numpy and arrays\n", - "[Numpy](http://www.numpy.org/) provides an easy way to handle arrays in Python. The standard way to import this library is as" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Here follows a simple example where we set up an array of ten elements, all determined by random numbers drawn according to the normal distribution," - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "n = 10\n", - "x = np.random.normal(size=n)\n", - "print(x)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We defined a vector $x$ with $n=10$ elements with its values given by the Normal distribution $N(0,1)$.\n", - "Another alternative is to declare a vector as follows" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "x = np.array([1, 2, 3])\n", - "print(x)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Here we have defined a vector with three elements, with $x_0=1$, $x_1=2$ and $x_2=3$. Note that both Python and C++\n", - "start numbering array elements from $0$ and on. This means that a vector with $n$ elements has a sequence of entities $x_0, x_1, x_2, \\dots, x_{n-1}$. We could also let (recommended) Numpy to compute the logarithms of a specific array as" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "x = np.log(np.array([4, 7, 8]))\n", - "print(x)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In the last example we used Numpy's unary function $np.log$. This function is\n", - "highly tuned to compute array elements since the code is vectorized\n", - "and does not require looping. We normaly recommend that you use the\n", - "Numpy intrinsic functions instead of the corresponding **log** function\n", - "from Python's **math** module. The looping is done explicitely by the\n", - "**np.log** function. The alternative, and slower way to compute the\n", - "logarithms of a vector would be to write" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "from math import log\n", - "x = np.array([4, 7, 8])\n", - "for i in range(0, len(x)):\n", - " x[i] = log(x[i])\n", - "print(x)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We note that our code is much longer already and we need to import the **log** function from the **math** module. \n", - "The attentive reader will also notice that the output is $[1, 1, 2]$. Python interprets automagically our numbers as integers (like the **automatic** keyword in C++). To change this we could define our array elements to be double precision numbers as" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "x = np.log(np.array([4, 7, 8], dtype = np.float64))\n", - "print(x)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "or simply write them as double precision numbers (Python uses 64 bits as default for floating point type variables), that is" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "x = np.log(np.array([4.0, 7.0, 8.0])\n", - "print(x)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "To check the number of bytes (remember that one byte contains eight bits for double precision variables), you can use simple use the **itemsize** functionality (the array $x$ is actually an object which inherits the functionalities defined in Numpy) as" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "x = np.log(np.array([4.0, 7.0, 8.0])\n", - "print(x.itemsize)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Matrices in Python\n", - "\n", - "Having defined vectors, we are now ready to try out matrices. We can\n", - "define a $3 \\times 3 $ real matrix $\\hat{A}$ as (recall that we user\n", - "lowercase letters for vectors and uppercase letters for matrices)" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ]))\n", - "print(A)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "If we use the **shape** function we would get $(3, 3)$ as output, that is verifying that our matrix is a $3\\times 3$ matrix. We can slice the matrix and print for example the first column (Python organized matrix elements in a row-major order, see below) as" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ]))\n", - "# print the first column, row-major order and elements start with 0\n", - "print(A[:,0])" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We can continue this was by printing out other columns or rows. The example here prints out the second column" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "A = np.log(np.array([ [4.0, 7.0, 8.0], [3.0, 10.0, 11.0], [4.0, 5.0, 7.0] ]))\n", - "# print the first column, row-major order and elements start with 0\n", - "print(A[1,:])" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Numpy contains many other functionalities that allow us to slice, subdivide etc etc arrays. We strongly recommend that you look up the [Numpy website for more details](http://www.numpy.org/). Useful functions when defining a matrix are the **np.zeros** function which declares a matrix of a given dimension and sets all elements to zero" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "n = 10\n", - "# define a matrix of dimension 10 x 10 and set all elements to zero\n", - "A = np.zeros( (n, n) )\n", - "print(A)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "or initializing all elements to" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "n = 10\n", - "# define a matrix of dimension 10 x 10 and set all elements to one\n", - "A = np.ones( (n, n) )\n", - "print(A)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "or as unitarily distributed random numbers (see the material on random number generators in the statistics part)" - ] - }, - { - "cell_type": "code", - "execution_count": 14, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "n = 10\n", - "# define a matrix of dimension 10 x 10 and set all elements to random numbers with x \\in [0, 1]\n", - "A = np.random.rand(n, n)\n", - "print(A)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "As we will see throughout these lectures, there are several extremely useful functionalities in Numpy.\n", - "As an example, consider the discussion of the covariance matrix. Suppose we have defined three vectors\n", - "$\\hat{x}, \\hat{y}, \\hat{z}$ with $n$ elements each. The covariance matrix is defined as" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\hat{\\Sigma} = \\begin{bmatrix} \\sigma_{xx} & \\sigma_{xy} & \\sigma_{xz} \\\\\n", - " \\sigma_{yx} & \\sigma_{yy} & \\sigma_{yz} \\\\\n", - " \\sigma_{zx} & \\sigma_{zy} & \\sigma_{zz} \n", - " \\end{bmatrix},\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where for example" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\sigma_{xy} =\\frac{1}{n} \\sum_{i=0}^{n-1}(x_i- \\overline{x})(y_i- \\overline{y}).\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The Numpy function **np.cov** calculates the covariance elements using the factor $1/(n-1)$ instead of $1/n$ since it assumes we do not have the exact mean values. \n", - "The following simple function uses the **np.vstack** function which takes each vector of dimension $1\\times n$ and produces a $3\\times n$ matrix $\\hat{W}$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\hat{W} = \\begin{bmatrix} x_0 & y_0 & z_0 \\\\\n", - " x_1 & y_1 & z_1 \\\\\n", - " x_2 & y_2 & z_2 \\\\\n", - " \\dots & \\dots & \\dots \\\\\n", - " x_{n-2} & y_{n-2} & z_{n-2} \\\\\n", - " x_{n-1} & y_{n-1} & z_{n-1}\n", - " \\end{bmatrix},\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "which in turn is converted into into the $3\\times 3$ covariance matrix\n", - "$\\hat{\\Sigma}$ via the Numpy function **np.cov()**. We note that we can also calculate\n", - "the mean value of each set of samples $\\hat{x}$ etc using the Numpy\n", - "function **np.mean(x)**. We can also extract the eigenvalues of the\n", - "covariance matrix through the **np.linalg.eig()** function." - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "# Importing various packages\n", - "import numpy as np\n", - "\n", - "n = 100\n", - "x = np.random.normal(size=n)\n", - "print(np.mean(x))\n", - "y = 4+3*x+np.random.normal(size=n)\n", - "print(np.mean(y))\n", - "z = x**3+np.random.normal(size=n)\n", - "print(np.mean(z))\n", - "W = np.vstack((x, y, z))\n", - "Sigma = np.cov(W)\n", - "print(Sigma)\n", - "Eigvals, Eigvecs = np.linalg.eig(Sigma)\n", - "print(Eigvals)" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "%matplotlib inline\n", - "\n", - "import numpy as np\n", - "import matplotlib.pyplot as plt\n", - "from scipy import sparse\n", - "eye = np.eye(4)\n", - "print(eye)\n", - "sparse_mtx = sparse.csr_matrix(eye)\n", - "print(sparse_mtx)\n", - "x = np.linspace(-10,10,100)\n", - "y = np.sin(x)\n", - "plt.plot(x,y,marker='x')\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Meet the Pandas\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "

\n", - "\n", - "\n", - "\n", - "\n", - "\n", - "Another useful Python package is\n", - "[pandas](https://pandas.pydata.org/), which is an open source library\n", - "providing high-performance, easy-to-use data structures and data\n", - "analysis tools for Python. **pandas** stands for panel data, a term borrowed from econometrics and is an efficient library for data analysis with an emphasis on tabular data.\n", - "**pandas** has two major classes, the **DataFrame** class with two-dimensional data objects and tabular data organized in columns and the class **Series** with a focus on one-dimensional data objects. Both classes allow you to index data easily as we will see in the examples below. \n", - "**pandas** allows you also to perform mathematical operations on the data, spanning from simple reshapings of vectors and matrices to statistical operations. \n", - "\n", - "The following simple example shows how we can, in an easy way make tables of our data. Here we define a data set which includes names, place of birth and date of birth, and displays the data in an easy to read way. We will see repeated use of **pandas**, in particular in connection with classification of data." - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import pandas as pd\n", - "from IPython.display import display\n", - "data = {'First Name': [\"Frodo\", \"Bilbo\", \"Aragorn II\", \"Samwise\"],\n", - " 'Last Name': [\"Baggins\", \"Baggins\",\"Elessar\",\"Gamgee\"],\n", - " 'Place of birth': [\"Shire\", \"Shire\", \"Eriador\", \"Shire\"],\n", - " 'Date of Birth T.A.': [2968, 2890, 2931, 2980]\n", - " }\n", - "data_pandas = pd.DataFrame(data)\n", - "display(data_pandas)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In the above we have imported **pandas** with the shorthand **pd**, the latter has become the standard way we import **pandas**. We make then a list of various variables\n", - "and reorganize the aboves lists into a **DataFrame** and then print out a neat table with specific column labels as *Name*, *place of birth* and *date of birth*.\n", - "Displaying these results, we see that the indices are given by the default numbers from zero to three.\n", - "**pandas** is extremely flexible and we can easily change the above indices by defining a new type of indexing as" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "data_pandas = pd.DataFrame(data,index=['Frodo','Bilbo','Aragorn','Sam'])\n", - "display(data_pandas)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Thereafter we display the content of the row which begins with the index **Aragorn**" - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "display(data_pandas.loc['Aragorn'])" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We can easily append data to this, for example" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "new_hobbit = {'First Name': [\"Peregrin\"],\n", - " 'Last Name': [\"Took\"],\n", - " 'Place of birth': [\"Shire\"],\n", - " 'Date of Birth T.A.': [2990]\n", - " }\n", - "data_pandas=data_pandas.append(pd.DataFrame(new_hobbit, index=['Pippin']))\n", - "display(data_pandas)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Here are other examples where we use the **DataFrame** functionality to handle arrays, now with more interesting features for us, namely numbers. We set up a matrix \n", - "of dimensionality $10\\times 5$ and compute the mean value and standard deviation of each column. Similarly, we can perform mathematial operations like squaring the matrix elements and many other operations." - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "import pandas as pd\n", - "from IPython.display import display\n", - "np.random.seed(100)\n", - "# setting up a 10 x 5 matrix\n", - "rows = 10\n", - "cols = 5\n", - "a = np.random.randn(rows,cols)\n", - "df = pd.DataFrame(a)\n", - "display(df)\n", - "print(df.mean())\n", - "print(df.std())\n", - "display(df**2)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Thereafter we can select specific columns only and plot final results" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "df.columns = ['First', 'Second', 'Third', 'Fourth', 'Fifth']\n", - "df.index = np.arange(10)\n", - "\n", - "display(df)\n", - "print(df['Second'].mean() )\n", - "print(df.info())\n", - "print(df.describe())\n", - "\n", - "from pylab import plt, mpl\n", - "plt.style.use('seaborn')\n", - "mpl.rcParams['font.family'] = 'serif'\n", - "\n", - "df.cumsum().plot(lw=2.0, figsize=(10,6))\n", - "plt.show()\n", - "\n", - "\n", - "df.plot.bar(figsize=(10,6), rot=15)\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We can produce a $4\\times 4$ matrix" - ] - }, - { - "cell_type": "code", - "execution_count": 23, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "b = np.arange(16).reshape((4,4))\n", - "print(b)\n", - "df1 = pd.DataFrame(b)\n", - "print(df1)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "and many other operations. \n", - "\n", - "The **Series** class is another important class included in\n", - "**pandas**. You can view it as a specialization of **DataFrame** but where\n", - "we have just a single column of data. It shares many of the same features as _DataFrame. As with **DataFrame**,\n", - "most operations are vectorized, achieving thereby a high performance when dealing with computations of arrays, in particular labeled arrays.\n", - "As we will see below it leads also to a very concice code close to the mathematical operations we may be interested in.\n", - "For multidimensional arrays, we recommend strongly [xarray](http://xarray.pydata.org/en/stable/). **xarray** has much of the same flexibility as **pandas**, but allows for the extension to higher dimensions than two. We will see examples later of the usage of both **pandas** and **xarray**. \n", - "\n", - "\n", - "\n", - "## Reading Data and fitting\n", - "\n", - "In order to study various Machine Learning algorithms, we need to\n", - "access data. Acccessing data is an essential step in all machine\n", - "learning algorithms. In particular, setting up the so-called **design\n", - "matrix** (to be defined below) is often the first element we need in\n", - "order to perform our calculations. To set up the design matrix means\n", - "reading (and later, when the calculations are done, writing) data\n", - "in various formats, The formats span from reading files from disk,\n", - "loading data from databases and interacting with online sources\n", - "like web application programming interfaces (APIs).\n", - "\n", - "In handling various input formats, as discussed above, we will mainly stay with **pandas**,\n", - "a Python package which allows us, in a seamless and painless way, to\n", - "deal with a multitude of formats, from standard **csv** (comma separated\n", - "values) files, via **excel**, **html** to **hdf5** formats. With **pandas**\n", - "and the **DataFrame** and **Series** functionalities we are able to convert text data\n", - "into the calculational formats we need for a specific algorithm. And our code is going to be \n", - "pretty close the basic mathematical expressions.\n", - "\n", - "Our first data set is going to be a classic from nuclear physics, namely all\n", - "available data on binding energies. Don't be intimidated if you are not familiar with nuclear physics. It serves simply as an example here of a data set. \n", - "\n", - "We will show some of the\n", - "strengths of packages like **Scikit-Learn** in fitting nuclear binding energies to\n", - "specific functions using linear regression first. Then, as a teaser, we will show you how \n", - "you can easily implement other algorithms like decision trees and random forests and neural networks.\n", - "\n", - "But before we really start with nuclear physics data, let's just look at some simpler polynomial fitting cases, such as,\n", - "(don't be offended) fitting straight lines!\n", - "\n", - "\n", - "### Simple linear regression model using **scikit-learn**\n", - "\n", - "We start with perhaps our simplest possible example, using **Scikit-Learn** to perform linear regression analysis on a data set produced by us. \n", - "\n", - "What follows is a simple Python code where we have defined a function\n", - "$y$ in terms of the variable $x$. Both are defined as vectors with $100$ entries. \n", - "The numbers in the vector $\\hat{x}$ are given\n", - "by random numbers generated with a uniform distribution with entries\n", - "$x_i \\in [0,1]$ (more about probability distribution functions\n", - "later). These values are then used to define a function $y(x)$\n", - "(tabulated again as a vector) with a linear dependence on $x$ plus a\n", - "random noise added via the normal distribution.\n", - "\n", - "\n", - "The Numpy functions are imported used the **import numpy as np**\n", - "statement and the random number generator for the uniform distribution\n", - "is called using the function **np.random.rand()**, where we specificy\n", - "that we want $100$ random variables. Using Numpy we define\n", - "automatically an array with the specified number of elements, $100$ in\n", - "our case. With the Numpy function **randn()** we can compute random\n", - "numbers with the normal distribution (mean value $\\mu$ equal to zero and\n", - "variance $\\sigma^2$ set to one) and produce the values of $y$ assuming a linear\n", - "dependence as function of $x$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "y = 2x+N(0,1),\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where $N(0,1)$ represents random numbers generated by the normal\n", - "distribution. From **Scikit-Learn** we import then the\n", - "**LinearRegression** functionality and make a prediction $\\tilde{y} =\n", - "\\alpha + \\beta x$ using the function **fit(x,y)**. We call the set of\n", - "data $(\\hat{x},\\hat{y})$ for our training data. The Python package\n", - "**scikit-learn** has also a functionality which extracts the above\n", - "fitting parameters $\\alpha$ and $\\beta$ (see below). Later we will\n", - "distinguish between training data and test data.\n", - "\n", - "For plotting we use the Python package\n", - "[matplotlib](https://matplotlib.org/) which produces publication\n", - "quality figures. Feel free to explore the extensive\n", - "[gallery](https://matplotlib.org/gallery/index.html) of examples. In\n", - "this example we plot our original values of $x$ and $y$ as well as the\n", - "prediction **ypredict** ($\\tilde{y}$), which attempts at fitting our\n", - "data with a straight line.\n", - "\n", - "The Python code follows here." - ] - }, - { - "cell_type": "code", - "execution_count": 24, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "# Importing various packages\n", - "import numpy as np\n", - "import matplotlib.pyplot as plt\n", - "from sklearn.linear_model import LinearRegression\n", - "\n", - "x = np.random.rand(100,1)\n", - "y = 2*x+np.random.randn(100,1)\n", - "linreg = LinearRegression()\n", - "linreg.fit(x,y)\n", - "xnew = np.array([[0],[1]])\n", - "ypredict = linreg.predict(xnew)\n", - "\n", - "plt.plot(xnew, ypredict, \"r-\")\n", - "plt.plot(x, y ,'ro')\n", - "plt.axis([0,1.0,0, 5.0])\n", - "plt.xlabel(r'$x$')\n", - "plt.ylabel(r'$y$')\n", - "plt.title(r'Simple Linear Regression')\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "This example serves several aims. It allows us to demonstrate several\n", - "aspects of data analysis and later machine learning algorithms. The\n", - "immediate visualization shows that our linear fit is not\n", - "impressive. It goes through the data points, but there are many\n", - "outliers which are not reproduced by our linear regression. We could\n", - "now play around with this small program and change for example the\n", - "factor in front of $x$ and the normal distribution. Try to change the\n", - "function $y$ to" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "y = 10x+0.01 \\times N(0,1),\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where $x$ is defined as before. Does the fit look better? Indeed, by\n", - "reducing the role of the noise given by the normal distribution we see immediately that\n", - "our linear prediction seemingly reproduces better the training\n", - "set. However, this testing 'by the eye' is obviouly not satisfactory in the\n", - "long run. Here we have only defined the training data and our model, and \n", - "have not discussed a more rigorous approach to the **cost** function.\n", - "\n", - "We need more rigorous criteria in defining whether we have succeeded or\n", - "not in modeling our training data. You will be surprised to see that\n", - "many scientists seldomly venture beyond this 'by the eye' approach. A\n", - "standard approach for the *cost* function is the so-called $\\chi^2$\n", - "function (a variant of the mean-squared error (MSE))" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\chi^2 = \\frac{1}{n}\n", - "\\sum_{i=0}^{n-1}\\frac{(y_i-\\tilde{y}_i)^2}{\\sigma_i^2},\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where $\\sigma_i^2$ is the variance (to be defined later) of the entry\n", - "$y_i$. We may not know the explicit value of $\\sigma_i^2$, it serves\n", - "however the aim of scaling the equations and make the cost function\n", - "dimensionless. \n", - "\n", - "Minimizing the cost function is a central aspect of\n", - "our discussions to come. Finding its minima as function of the model\n", - "parameters ($\\alpha$ and $\\beta$ in our case) will be a recurring\n", - "theme in these series of lectures. Essentially all machine learning\n", - "algorithms we will discuss center around the minimization of the\n", - "chosen cost function. This depends in turn on our specific\n", - "model for describing the data, a typical situation in supervised\n", - "learning. Automatizing the search for the minima of the cost function is a\n", - "central ingredient in all algorithms. Typical methods which are\n", - "employed are various variants of **gradient** methods. These will be\n", - "discussed in more detail later. Again, you'll be surprised to hear that\n", - "many practitioners minimize the above function ''by the eye', popularly dubbed as \n", - "'chi by the eye'. That is, change a parameter and see (visually and numerically) that \n", - "the $\\chi^2$ function becomes smaller. \n", - "\n", - "There are many ways to define the cost function. A simpler approach is to look at the relative difference between the training data and the predicted data, that is we define \n", - "the relative error (why would we prefer the MSE instead of the relative error?) as" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\epsilon_{\\mathrm{relative}}= \\frac{\\vert \\hat{y} -\\hat{\\tilde{y}}\\vert}{\\vert \\hat{y}\\vert}.\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The squared cost function results in an arithmetic mean-unbiased\n", - "estimator, and the absolute-value cost function results in a\n", - "median-unbiased estimator (in the one-dimensional case, and a\n", - "geometric median-unbiased estimator for the multi-dimensional\n", - "case). The squared cost function has the disadvantage that it has the tendency\n", - "to be dominated by outliers.\n", - "\n", - "We can modify easily the above Python code and plot the relative error instead" - ] - }, - { - "cell_type": "code", - "execution_count": 25, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np\n", - "import matplotlib.pyplot as plt\n", - "from sklearn.linear_model import LinearRegression\n", - "\n", - "x = np.random.rand(100,1)\n", - "y = 5*x+0.01*np.random.randn(100,1)\n", - "linreg = LinearRegression()\n", - "linreg.fit(x,y)\n", - "ypredict = linreg.predict(x)\n", - "\n", - "plt.plot(x, np.abs(ypredict-y)/abs(y), \"ro\")\n", - "plt.axis([0,1.0,0.0, 0.5])\n", - "plt.xlabel(r'$x$')\n", - "plt.ylabel(r'$\\epsilon_{\\mathrm{relative}}$')\n", - "plt.title(r'Relative error')\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Depending on the parameter in front of the normal distribution, we may\n", - "have a small or larger relative error. Try to play around with\n", - "different training data sets and study (graphically) the value of the\n", - "relative error.\n", - "\n", - "As mentioned above, **Scikit-Learn** has an impressive functionality.\n", - "We can for example extract the values of $\\alpha$ and $\\beta$ and\n", - "their error estimates, or the variance and standard deviation and many\n", - "other properties from the statistical data analysis. \n", - "\n", - "Here we show an\n", - "example of the functionality of **Scikit-Learn**." - ] - }, - { - "cell_type": "code", - "execution_count": 26, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import numpy as np \n", - "import matplotlib.pyplot as plt \n", - "from sklearn.linear_model import LinearRegression \n", - "from sklearn.metrics import mean_squared_error, r2_score, mean_squared_log_error, mean_absolute_error\n", - "\n", - "x = np.random.rand(100,1)\n", - "y = 2.0+ 5*x+0.5*np.random.randn(100,1)\n", - "linreg = LinearRegression()\n", - "linreg.fit(x,y)\n", - "ypredict = linreg.predict(x)\n", - "print('The intercept alpha: \\n', linreg.intercept_)\n", - "print('Coefficient beta : \\n', linreg.coef_)\n", - "# The mean squared error \n", - "print(\"Mean squared error: %.2f\" % mean_squared_error(y, ypredict))\n", - "# Explained variance score: 1 is perfect prediction \n", - "print('Variance score: %.2f' % r2_score(y, ypredict))\n", - "# Mean squared log error \n", - "print('Mean squared log error: %.2f' % mean_squared_log_error(y, ypredict) )\n", - "# Mean absolute error \n", - "print('Mean absolute error: %.2f' % mean_absolute_error(y, ypredict))\n", - "plt.plot(x, ypredict, \"r-\")\n", - "plt.plot(x, y ,'ro')\n", - "plt.axis([0.0,1.0,1.5, 7.0])\n", - "plt.xlabel(r'$x$')\n", - "plt.ylabel(r'$y$')\n", - "plt.title(r'Linear Regression fit ')\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The function **coef** gives us the parameter $\\beta$ of our fit while **intercept** yields \n", - "$\\alpha$. Depending on the constant in front of the normal distribution, we get values near or far from $alpha =2$ and $\\beta =5$. Try to play around with different parameters in front of the normal distribution. The function **meansquarederror** gives us the mean square error, a risk metric corresponding to the expected value of the squared (quadratic) error or loss defined as" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "MSE(\\hat{y},\\hat{\\tilde{y}}) = \\frac{1}{n}\n", - "\\sum_{i=0}^{n-1}(y_i-\\tilde{y}_i)^2,\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The smaller the value, the better the fit. Ideally we would like to\n", - "have an MSE equal zero. The attentive reader has probably recognized\n", - "this function as being similar to the $\\chi^2$ function defined above.\n", - "\n", - "The **r2score** function computes $R^2$, the coefficient of\n", - "determination. It provides a measure of how well future samples are\n", - "likely to be predicted by the model. Best possible score is 1.0 and it\n", - "can be negative (because the model can be arbitrarily worse). A\n", - "constant model that always predicts the expected value of $\\hat{y}$,\n", - "disregarding the input features, would get a $R^2$ score of $0.0$.\n", - "\n", - "If $\\tilde{\\hat{y}}_i$ is the predicted value of the $i-th$ sample and $y_i$ is the corresponding true value, then the score $R^2$ is defined as" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "R^2(\\hat{y}, \\tilde{\\hat{y}}) = 1 - \\frac{\\sum_{i=0}^{n - 1} (y_i - \\tilde{y}_i)^2}{\\sum_{i=0}^{n - 1} (y_i - \\bar{y})^2},\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where we have defined the mean value of $\\hat{y}$ as" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\bar{y} = \\frac{1}{n} \\sum_{i=0}^{n - 1} y_i.\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Another quantity taht we will meet again in our discussions of regression analysis is \n", - " the mean absolute error (MAE), a risk metric corresponding to the expected value of the absolute error loss or what we call the $l1$-norm loss. In our discussion above we presented the relative error.\n", - "The MAE is defined as follows" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\text{MAE}(\\hat{y}, \\hat{\\tilde{y}}) = \\frac{1}{n} \\sum_{i=0}^{n-1} \\left| y_i - \\tilde{y}_i \\right|.\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We present the \n", - "squared logarithmic (quadratic) error" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\text{MSLE}(\\hat{y}, \\hat{\\tilde{y}}) = \\frac{1}{n} \\sum_{i=0}^{n - 1} (\\log_e (1 + y_i) - \\log_e (1 + \\tilde{y}_i) )^2,\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where $\\log_e (x)$ stands for the natural logarithm of $x$. This error\n", - "estimate is best to use when targets having exponential growth, such\n", - "as population counts, average sales of a commodity over a span of\n", - "years etc. \n", - "\n", - "\n", - "Finally, another cost function is the Huber cost function used in robust regression.\n", - "It is less sensitive to outliers in data than the squared error cost function.\n", - "A variant for classification is also sometimes used, a quantity we will meet later." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "L_{\\delta }(a)={\\begin{cases}{\\frac {1}{2}}{a^{2}}&{\\text{for }}|a|\\leq \\delta ,\\\\\\delta (|a|-{\\frac {1}{2}}\\delta ),&{\\text{otherwise.}}\\end{cases}}}L_{\\delta }(a)={\\begin{cases}{\\frac {1}{2}}{a^{2}}&{\\text{for }}|a|\\leq \\delta ,\\\\\\delta (|a|-{\\frac {1}{2}}\\delta ),&{\\text{otherwise.}}\\end{cases}}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We will discuss in more\n", - "detail these and other functions in the various lectures. We conclude this part with another example. Instead of \n", - "a linear $x$-dependence we study now a cubic polynomial and use the polynomial regression analysis tools of scikit-learn." - ] - }, - { - "cell_type": "code", - "execution_count": 27, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import matplotlib.pyplot as plt\n", - "import numpy as np\n", - "import random\n", - "from sklearn.linear_model import Ridge\n", - "from sklearn.preprocessing import PolynomialFeatures\n", - "from sklearn.pipeline import make_pipeline\n", - "from sklearn.linear_model import LinearRegression\n", - "\n", - "x=np.linspace(0.02,0.98,200)\n", - "noise = np.asarray(random.sample((range(200)),200))\n", - "y=x**3*noise\n", - "yn=x**3*100\n", - "poly3 = PolynomialFeatures(degree=3)\n", - "X = poly3.fit_transform(x[:,np.newaxis])\n", - "clf3 = LinearRegression()\n", - "clf3.fit(X,y)\n", - "\n", - "Xplot=poly3.fit_transform(x[:,np.newaxis])\n", - "poly3_plot=plt.plot(x, clf3.predict(Xplot), label='Cubic Fit')\n", - "plt.plot(x,yn, color='red', label=\"True Cubic\")\n", - "plt.scatter(x, y, label='Data', color='orange', s=15)\n", - "plt.legend()\n", - "plt.show()\n", - "\n", - "def error(a):\n", - " for i in y:\n", - " err=(y-yn)/yn\n", - " return abs(np.sum(err))/len(err)\n", - "\n", - "print (error(y))" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### To our real data: nuclear binding energies. Brief reminder on masses and binding energies\n", - "\n", - "Let us now dive into nuclear physics and remind ourselves briefly about some basic features about binding\n", - "energies. A basic quantity which can be measured for the ground\n", - "states of nuclei is the atomic mass $M(N, Z)$ of the neutral atom with\n", - "atomic mass number $A$ and charge $Z$. The number of neutrons is $N$. There are indeed several sophisticated experiments worldwide which allow us to measure this quantity to high precision (parts per million even). \n", - "\n", - "Atomic masses are usually tabulated in terms of the mass excess defined by" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "\\Delta M(N, Z) = M(N, Z) - uA,\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where $u$ is the Atomic Mass Unit" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "u = M(^{12}\\mathrm{C})/12 = 931.4940954(57) \\hspace{0.1cm} \\mathrm{MeV}/c^2.\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The nucleon masses are" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "m_p = 1.00727646693(9)u,\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "and" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "m_n = 939.56536(8)\\hspace{0.1cm} \\mathrm{MeV}/c^2 = 1.0086649156(6)u.\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In the [2016 mass evaluation of by W.J.Huang, G.Audi, M.Wang, F.G.Kondev, S.Naimi and X.Xu](http://nuclearmasses.org/resources_folder/Wang_2017_Chinese_Phys_C_41_030003.pdf)\n", - "there are data on masses and decays of 3437 nuclei.\n", - "\n", - "The nuclear binding energy is defined as the energy required to break\n", - "up a given nucleus into its constituent parts of $N$ neutrons and $Z$\n", - "protons. In terms of the atomic masses $M(N, Z)$ the binding energy is\n", - "defined by" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "BE(N, Z) = ZM_H c^2 + Nm_n c^2 - M(N, Z)c^2 ,\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where $M_H$ is the mass of the hydrogen atom and $m_n$ is the mass of the neutron.\n", - "In terms of the mass excess the binding energy is given by" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "BE(N, Z) = Z\\Delta_H c^2 + N\\Delta_n c^2 -\\Delta(N, Z)c^2 ,\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where $\\Delta_H c^2 = 7.2890$ MeV and $\\Delta_n c^2 = 8.0713$ MeV.\n", - "\n", - "\n", - "A popular and physically intuitive model which can be used to parametrize \n", - "the experimental binding energies as function of $A$, is the so-called \n", - "**liquid drop model**. The ansatz is based on the following expression" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "$$\n", - "BE(N,Z) = a_1A-a_2A^{2/3}-a_3\\frac{Z^2}{A^{1/3}}-a_4\\frac{(N-Z)^2}{A},\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "where $A$ stands for the number of nucleons and the $a_i$s are parameters which are determined by a fit \n", - "to the experimental data. \n", - "\n", - "\n", - "\n", - "\n", - "To arrive at the above expression we have assumed that we can make the following assumptions:\n", - "\n", - " * There is a volume term $a_1A$ proportional with the number of nucleons (the energy is also an extensive quantity). When an assembly of nucleons of the same size is packed together into the smallest volume, each interior nucleon has a certain number of other nucleons in contact with it. This contribution is proportional to the volume.\n", - "\n", - " * There is a surface energy term $a_2A^{2/3}$. The assumption here is that a nucleon at the surface of a nucleus interacts with fewer other nucleons than one in the interior of the nucleus and hence its binding energy is less. This surface energy term takes that into account and is therefore negative and is proportional to the surface area.\n", - "\n", - " * There is a Coulomb energy term $a_3\\frac{Z^2}{A^{1/3}}$. The electric repulsion between each pair of protons in a nucleus yields less binding. \n", - "\n", - " * There is an asymmetry term $a_4\\frac{(N-Z)^2}{A}$. This term is associated with the Pauli exclusion principle and reflects the fact that the proton-neutron interaction is more attractive on the average than the neutron-neutron and proton-proton interactions.\n", - "\n", - "We could also add a so-called pairing term, which is a correction term that\n", - "arises from the tendency of proton pairs and neutron pairs to\n", - "occur. An even number of particles is more stable than an odd number. \n", - "\n", - "\n", - "### Organizing our data\n", - "\n", - "Let us start with reading and organizing our data. \n", - "We start with the compilation of masses and binding energies from 2016.\n", - "After having downloaded this file to our own computer, we are now ready to read the file and start structuring our data.\n", - "\n", - "\n", - "We start with preparing folders for storing our calculations and the data file over masses and binding energies. We import also various modules that we will find useful in order to present various Machine Learning methods. Here we focus mainly on the functionality of **scikit-learn**." - ] - }, - { - "cell_type": "code", - "execution_count": 28, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "# Common imports\n", - "import numpy as np\n", - "import pandas as pd\n", - "import matplotlib.pyplot as plt\n", - "import sklearn.linear_model as skl\n", - "from sklearn.model_selection import train_test_split\n", - "from sklearn.metrics import mean_squared_error, r2_score, mean_absolute_error\n", - "import os\n", - "\n", - "# Where to save the figures and data files\n", - "PROJECT_ROOT_DIR = \"Results\"\n", - "FIGURE_ID = \"Results/FigureFiles\"\n", - "DATA_ID = \"DataFiles/\"\n", - "\n", - "if not os.path.exists(PROJECT_ROOT_DIR):\n", - " os.mkdir(PROJECT_ROOT_DIR)\n", - "\n", - "if not os.path.exists(FIGURE_ID):\n", - " os.makedirs(FIGURE_ID)\n", - "\n", - "if not os.path.exists(DATA_ID):\n", - " os.makedirs(DATA_ID)\n", - "\n", - "def image_path(fig_id):\n", - " return os.path.join(FIGURE_ID, fig_id)\n", - "\n", - "def data_path(dat_id):\n", - " return os.path.join(DATA_ID, dat_id)\n", - "\n", - "def save_fig(fig_id):\n", - " plt.savefig(image_path(fig_id) + \".png\", format='png')\n", - "\n", - "infile = open(data_path(\"MassEval2016.dat\"),'r')" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Before we proceed, we define also a function for making our plots. You can obviously avoid this and simply set up various **matplotlib** commands every time you need them. You may however find it convenient to collect all such commands in one function and simply call this function." - ] - }, - { - "cell_type": "code", - "execution_count": 29, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from pylab import plt, mpl\n", - "plt.style.use('seaborn')\n", - "mpl.rcParams['font.family'] = 'serif'\n", - "\n", - "def MakePlot(x,y, styles, labels, axlabels):\n", - " plt.figure(figsize=(10,6))\n", - " for i in range(len(x)):\n", - " plt.plot(x[i], y[i], styles[i], label = labels[i])\n", - " plt.xlabel(axlabels[0])\n", - " plt.ylabel(axlabels[1])\n", - " plt.legend(loc=0)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Our next step is to read the data on experimental binding energies and\n", - "reorganize them as functions of the mass number $A$, the number of\n", - "protons $Z$ and neutrons $N$ using **pandas**. Before we do this it is\n", - "always useful (unless you have a binary file or other types of compressed\n", - "data) to actually open the file and simply take a look at it!\n", - "\n", - "\n", - "In particular, the program that outputs the final nuclear masses is written in Fortran with a specific format. It means that we need to figure out the format and which columns contain the data we are interested in. Pandas comes with a function that reads formatted output. After having admired the file, we are now ready to start massaging it with **pandas**. The file begins with some basic format information." - ] - }, - { - "cell_type": "code", - "execution_count": 30, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "\"\"\" \n", - "This is taken from the data file of the mass 2016 evaluation. \n", - "All files are 3436 lines long with 124 character per line. \n", - " Headers are 39 lines long. \n", - " col 1 : Fortran character control: 1 = page feed 0 = line feed \n", - " format : a1,i3,i5,i5,i5,1x,a3,a4,1x,f13.5,f11.5,f11.3,f9.3,1x,a2,f11.3,f9.3,1x,i3,1x,f12.5,f11.5 \n", - " These formats are reflected in the pandas widths variable below, see the statement \n", - " widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1), \n", - " Pandas has also a variable header, with length 39 in this case. \n", - "\"\"\"" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The data we are interested in are in columns 2, 3, 4 and 11, giving us\n", - "the number of neutrons, protons, mass numbers and binding energies,\n", - "respectively. We add also for the sake of completeness the element name. The data are in fixed-width formatted lines and we will\n", - "covert them into the **pandas** DataFrame structure." - ] - }, - { - "cell_type": "code", - "execution_count": 31, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "# Read the experimental data with Pandas\n", - "Masses = pd.read_fwf(infile, usecols=(2,3,4,6,11),\n", - " names=('N', 'Z', 'A', 'Element', 'Ebinding'),\n", - " widths=(1,3,5,5,5,1,3,4,1,13,11,11,9,1,2,11,9,1,3,1,12,11,1),\n", - " header=39,\n", - " index_col=False)\n", - "\n", - "# Extrapolated values are indicated by '#' in place of the decimal place, so\n", - "# the Ebinding column won't be numeric. Coerce to float and drop these entries.\n", - "Masses['Ebinding'] = pd.to_numeric(Masses['Ebinding'], errors='coerce')\n", - "Masses = Masses.dropna()\n", - "# Convert from keV to MeV.\n", - "Masses['Ebinding'] /= 1000\n", - "\n", - "# Group the DataFrame by nucleon number, A.\n", - "Masses = Masses.groupby('A')\n", - "# Find the rows of the grouped DataFrame with the maximum binding energy.\n", - "Masses = Masses.apply(lambda t: t[t.Ebinding==t.Ebinding.max()])" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We have now read in the data, grouped them according to the variables we are interested in. \n", - "We see how easy it is to reorganize the data using **pandas**. If we\n", - "were to do these operations in C/C++ or Fortran, we would have had to\n", - "write various functions/subroutines which perform the above\n", - "reorganizations for us. Having reorganized the data, we can now start\n", - "to make some simple fits using both the functionalities in **numpy** and\n", - "**Scikit-Learn** afterwards. \n", - "\n", - "Now we define five variables which contain\n", - "the number of nucleons $A$, the number of protons $Z$ and the number of neutrons $N$, the element name and finally the energies themselves." - ] - }, - { - "cell_type": "code", - "execution_count": 32, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "A = Masses['A']\n", - "Z = Masses['Z']\n", - "N = Masses['N']\n", - "Element = Masses['Element']\n", - "Energies = Masses['Ebinding']\n", - "print(Masses)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The next step, and we will define this mathematically later, is to set up the so-called **design matrix**. We will throughout call this matrix $\\boldsymbol{X}$.\n", - "It has dimensionality $p\\times n$, where $n$ is the number of data points and $p$ are the so-called predictors. In our case here they are given by the number of polynomials in $A$ we wish to include in the fit." - ] - }, - { - "cell_type": "code", - "execution_count": 33, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "# Now we set up the design matrix X\n", - "X = np.zeros((len(A),5))\n", - "X[:,0] = 1\n", - "X[:,1] = A\n", - "X[:,2] = A**(2.0/3.0)\n", - "X[:,3] = A**(-1.0/3.0)\n", - "X[:,4] = A**(-1.0)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "With **scikitlearn** we are now ready to use linear regression and fit our data." - ] - }, - { - "cell_type": "code", - "execution_count": 34, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "clf = skl.LinearRegression().fit(X, Energies)\n", - "fity = clf.predict(X)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Pretty simple! \n", - "Now we can print measures of how our fit is doing, the coefficients from the fits and plot the final fit together with our data." - ] - }, - { - "cell_type": "code", - "execution_count": 35, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "# The mean squared error \n", - "print(\"Mean squared error: %.2f\" % mean_squared_error(Energies, fity))\n", - "# Explained variance score: 1 is perfect prediction \n", - "print('Variance score: %.2f' % r2_score(Energies, fity))\n", - "# Mean absolute error \n", - "print('Mean absolute error: %.2f' % mean_absolute_error(Energies, fity))\n", - "print(clf.coef_, clf.intercept_)\n", - "\n", - "Masses['Eapprox'] = fity\n", - "# Generate a plot comparing the experimental with the fitted values values.\n", - "fig, ax = plt.subplots()\n", - "ax.set_xlabel(r'$A = N + Z$')\n", - "ax.set_ylabel(r'$E_\\mathrm{bind}\\,/\\mathrm{MeV}$')\n", - "ax.plot(Masses['A'], Masses['Ebinding'], alpha=0.7, lw=2,\n", - " label='Ame2016')\n", - "ax.plot(Masses['A'], Masses['Eapprox'], alpha=0.7, lw=2, c='m',\n", - " label='Fit')\n", - "ax.legend()\n", - "save_fig(\"Masses2016\")\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Seeing the wood for the trees\n", - "\n", - "As a teaser, let us now see how we can do this with decision trees using **scikit-learn**. Later we will switch to so-called **random forests**!" - ] - }, - { - "cell_type": "code", - "execution_count": 36, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "\n", - "#Decision Tree Regression\n", - "from sklearn.tree import DecisionTreeRegressor\n", - "regr_1=DecisionTreeRegressor(max_depth=5)\n", - "regr_2=DecisionTreeRegressor(max_depth=7)\n", - "regr_3=DecisionTreeRegressor(max_depth=9)\n", - "regr_1.fit(X, Energies)\n", - "regr_2.fit(X, Energies)\n", - "regr_3.fit(X, Energies)\n", - "\n", - "\n", - "y_1 = regr_1.predict(X)\n", - "y_2 = regr_2.predict(X)\n", - "y_3=regr_3.predict(X)\n", - "Masses['Eapprox'] = y_3\n", - "# Plot the results\n", - "plt.figure()\n", - "plt.plot(A, Energies, color=\"blue\", label=\"Data\", linewidth=2)\n", - "plt.plot(A, y_1, color=\"red\", label=\"max_depth=5\", linewidth=2)\n", - "plt.plot(A, y_2, color=\"green\", label=\"max_depth=7\", linewidth=2)\n", - "plt.plot(A, y_3, color=\"m\", label=\"max_depth=9\", linewidth=2)\n", - "\n", - "plt.xlabel(\"$A$\")\n", - "plt.ylabel(\"$E$[MeV]\")\n", - "plt.title(\"Decision Tree Regression\")\n", - "plt.legend()\n", - "save_fig(\"Masses2016Trees\")\n", - "plt.show()\n", - "print(Masses)\n", - "print(np.mean( (Energies-y_1)**2))" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### And what about using neural networks?\n", - "\n", - "The **seaborn** package allows us to visualize data in an efficient way. Note that we use **scikit-learn**'s multi-layer perceptron (or feed forward neural network) \n", - "functionality." - ] - }, - { - "cell_type": "code", - "execution_count": 37, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from sklearn.neural_network import MLPRegressor\n", - "from sklearn.metrics import accuracy_score\n", - "import seaborn as sns\n", - "\n", - "X_train = X\n", - "Y_train = Energies\n", - "n_hidden_neurons = 100\n", - "epochs = 100\n", - "# store models for later use\n", - "eta_vals = np.logspace(-5, 1, 7)\n", - "lmbd_vals = np.logspace(-5, 1, 7)\n", - "# store the models for later use\n", - "DNN_scikit = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)\n", - "train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", - "sns.set()\n", - "for i, eta in enumerate(eta_vals):\n", - " for j, lmbd in enumerate(lmbd_vals):\n", - " dnn = MLPRegressor(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", - " DNN_scikit[i][j] = dnn\n", - " train_accuracy[i][j] = dnn.score(X_train, Y_train)\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()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## A first summary\n", - "\n", - "The aim behind these introductory words was to present to you various\n", - "Python libraries and their functionalities, in particular libraries like\n", - "**numpy**, **pandas**, **xarray** and **matplotlib** and other that make our life much easier\n", - "in handling various data sets and visualizing data. \n", - "\n", - "Furthermore,\n", - "**Scikit-Learn** allows us with few lines of code to implement popular\n", - "Machine Learning algorithms for supervised learning. Later we will meet **Tensorflow**, a powerful library for deep learning. \n", - "Now it is time to dive more into the details of various methods. We will start with linear regression and try to take a deeper look at what it entails.\n", - "\n", - "\n", - "# Review of Basic Statistics" - ] - } - ], - "metadata": {}, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/doc/LectureNotes/gaussian.pdf b/doc/LectureNotes/gaussian.pdf deleted file mode 100644 index 45124938ad1a1d3cda319c704f1f53b32318c0c5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 229831 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 diff --git a/doc/LectureNotes/ipynb-book-src.tar.gz b/doc/LectureNotes/ipynb-book-src.tar.gz deleted file mode 100644 index 9199e05c61904b53c685cda0370a075adcca225d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 103631 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