Basics-2-Numpy.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Numpy -  multidimensional data arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Parts of this notebook have been taken from:\n",
    "\n",
    "[http://github.com/jrjohansson/scientific-python-lectures](http://github.com/jrjohansson/scientific-python-lectures).\n",
    "\n",
    "The other notebooks in this lecture series are indexed at [http://jrjohansson.github.io](http://jrjohansson.github.io)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# what is this line all about?!? Answer in lecture 4\n",
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `numpy` package (module) is used in almost all numerical computation using Python. It is a package that provide high-performance vector, matrix and higher-dimensional data structures for Python. It is implemented in C and Fortran so when calculations are vectorized (formulated with vectors and matrices), performance is very good. \n",
    "\n",
    "To use `numpy` you need to import the module, using for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from numpy import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the `numpy` package the terminology used for vectors, matrices and higher-dimensional data sets is *array*. \n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating `numpy` arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are a number of ways to initialize new numpy arrays, for example from\n",
    "\n",
    "* a Python list or tuples\n",
    "* using functions that are dedicated to generating numpy arrays, such as `arange`, `linspace`, etc.\n",
    "* reading data from files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### From lists"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, to create new vector and matrix arrays from Python lists we can use the `numpy.array` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3, 4])"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# a vector: the argument to the array function is a Python list\n",
    "v = array([1,2,3,4])\n",
    "\n",
    "v"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[1, 2],\n",
       "       [3, 4]])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# a matrix: the argument to the array function is a nested Python list\n",
    "M = array([[1, 2], [3, 4]])\n",
    "\n",
    "M"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `v` and `M` objects are both of the type `ndarray` that the `numpy` module provides."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(numpy.ndarray, numpy.ndarray)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(v), type(M)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The difference between the `v` and `M` arrays is only their shapes. We can get information about the shape of an array by using the `ndarray.shape` property."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(4,)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2, 2)"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The number of elements in the array is available through the `ndarray.size` property:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M.size"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Equivalently, we could use the function `numpy.shape` and `numpy.size`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2, 2)"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "shape(M)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "size(M)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So far the `numpy.ndarray` looks awefully much like a Python list (or nested list). Why not simply use Python lists for computations instead of creating a new array type? \n",
    "\n",
    "There are several reasons:\n",
    "\n",
    "* Python lists are very general. They can contain any kind of object. They are dynamically typed. They do not support mathematical functions such as matrix and dot multiplications, etc. Implementing such functions for Python lists would not be very efficient because of the dynamic typing.\n",
    "* Numpy arrays are **statically typed** and **homogeneous**. The type of the elements is determined when the array is created.\n",
    "* Numpy arrays are memory efficient.\n",
    "* Because of the static typing, fast implementation of mathematical functions such as multiplication and addition of `numpy` arrays can be implemented in a compiled language (C and Fortran is used).\n",
    "\n",
    "Using the `dtype` (data type) property of an `ndarray`, we can see what type the data of an array has:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dtype('int64')"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M.dtype"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We get an error if we try to assign a value of the wrong type to an element in a numpy array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "invalid literal for int() with base 10: 'hello'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-12-a09d72434238>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mM\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;36m0\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;36m0\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m\"hello\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m: invalid literal for int() with base 10: 'hello'"
     ]
    }
   ],
   "source": [
    "M[0,0] = \"hello\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want, we can explicitly define the type of the array data when we create it, using the `dtype` keyword argument: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 1.+0.j,  2.+0.j],\n",
       "       [ 3.+0.j,  4.+0.j]])"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M = array([[1, 2], [3, 4]], dtype=complex)\n",
    "\n",
    "M"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Common data types that can be used with `dtype` are: `int`, `float`, `complex`, `bool`, `object`, etc.\n",
    "\n",
    "We can also explicitly define the bit size of the data types, for example: `int64`, `int16`, `float128`, `complex128`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using array-generating functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For larger arrays it is inpractical to initialize the data manually, using explicit python lists. Instead we can use one of the many functions in `numpy` that generate arrays of different forms. Some of the more common are:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### arange"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# create a range\n",
    "\n",
    "x = arange(0, 10, 1) # arguments: start, stop, step\n",
    "\n",
    "x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ -1.00000000e+00,  -9.00000000e-01,  -8.00000000e-01,\n",
       "        -7.00000000e-01,  -6.00000000e-01,  -5.00000000e-01,\n",
       "        -4.00000000e-01,  -3.00000000e-01,  -2.00000000e-01,\n",
       "        -1.00000000e-01,  -2.22044605e-16,   1.00000000e-01,\n",
       "         2.00000000e-01,   3.00000000e-01,   4.00000000e-01,\n",
       "         5.00000000e-01,   6.00000000e-01,   7.00000000e-01,\n",
       "         8.00000000e-01,   9.00000000e-01])"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = arange(-1, 1, 0.1)\n",
    "\n",
    "x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### linspace and logspace"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([  0.        ,   0.41666667,   0.83333333,   1.25      ,\n",
       "         1.66666667,   2.08333333,   2.5       ,   2.91666667,\n",
       "         3.33333333,   3.75      ,   4.16666667,   4.58333333,\n",
       "         5.        ,   5.41666667,   5.83333333,   6.25      ,\n",
       "         6.66666667,   7.08333333,   7.5       ,   7.91666667,\n",
       "         8.33333333,   8.75      ,   9.16666667,   9.58333333,  10.        ])"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# using linspace, both end points ARE included\n",
    "linspace(0, 10, 25)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([  1.00000000e+00,   3.03773178e+00,   9.22781435e+00,\n",
       "         2.80316249e+01,   8.51525577e+01,   2.58670631e+02,\n",
       "         7.85771994e+02,   2.38696456e+03,   7.25095809e+03,\n",
       "         2.20264658e+04])"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "logspace(0, 10, 10, base=e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### random data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from numpy import random"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.15356402,  0.18126019,  0.5672519 ,  0.26131585,  0.40549883],\n",
       "       [ 0.75403689,  0.56774012,  0.73307861,  0.13507975,  0.69659278],\n",
       "       [ 0.6903098 ,  0.10823981,  0.61743085,  0.90641554,  0.57611238],\n",
       "       [ 0.09819983,  0.06803204,  0.49746888,  0.69279608,  0.87614952],\n",
       "       [ 0.96934054,  0.39599994,  0.67983657,  0.8514684 ,  0.4817975 ]])"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# uniform random numbers in [0,1]\n",
    "random.rand(5,5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[-0.85787966, -1.44743778, -0.83359773, -1.48793241,  0.61137902],\n",
       "       [ 1.24535395, -1.00631442,  2.23274518, -1.41915065, -1.46442896],\n",
       "       [ 0.67612735, -0.20391907,  0.12702284,  0.2929514 , -0.80397464],\n",
       "       [ 0.68524216,  1.18068275,  1.6313341 ,  0.58981366,  1.9303117 ],\n",
       "       [ 0.47892556, -1.35905484, -0.80537731,  0.53486909,  0.00462168]])"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# standard normal distributed random numbers\n",
    "random.randn(5,5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### diag"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[1, 0, 0],\n",
       "       [0, 2, 0],\n",
       "       [0, 0, 3]])"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# a diagonal matrix\n",
    "diag([1,2,3])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[0, 1, 0, 0],\n",
       "       [0, 0, 2, 0],\n",
       "       [0, 0, 0, 3],\n",
       "       [0, 0, 0, 0]])"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# diagonal with offset from the main diagonal\n",
    "diag([1,2,3], k=1) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### zeros and ones"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.,  0.,  0.],\n",
       "       [ 0.,  0.,  0.],\n",
       "       [ 0.,  0.,  0.]])"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "zeros((3,3))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 1.,  1.,  1.],\n",
       "       [ 1.,  1.,  1.],\n",
       "       [ 1.,  1.,  1.]])"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ones((3,3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## File I/O"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Comma-separated values (CSV)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A very common file format for data files is comma-separated values (CSV), or related formats such as TSV (tab-separated values). To read data from such files into Numpy arrays we can use the `numpy.genfromtxt` function. For example, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1800  1  1    -6.1    -6.1    -6.1 1\r\n",
      "1800  1  2   -15.4   -15.4   -15.4 1\r\n",
      "1800  1  3   -15.0   -15.0   -15.0 1\r\n",
      "1800  1  4   -19.3   -19.3   -19.3 1\r\n",
      "1800  1  5   -16.8   -16.8   -16.8 1\r\n",
      "1800  1  6   -11.4   -11.4   -11.4 1\r\n",
      "1800  1  7    -7.6    -7.6    -7.6 1\r\n",
      "1800  1  8    -7.1    -7.1    -7.1 1\r\n",
      "1800  1  9   -10.1   -10.1   -10.1 1\r\n",
      "1800  1 10    -9.5    -9.5    -9.5 1\r\n"
     ]
    }
   ],
   "source": [
    "!head stockholm_td_adj.dat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "data = genfromtxt('stockholm_td_adj.dat')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(77431, 7)"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/maurizio/anaconda3/lib/python3.6/site-packages/matplotlib/font_manager.py:280: UserWarning: Matplotlib is building the font cache using fc-list. This may take a moment.\n",
      "  'Matplotlib is building the font cache using fc-list. '\n"
     ]
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f41110cb6a0>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots(figsize=(14,4))\n",
    "ax.plot(data[:,0]+data[:,1]/12.0+data[:,2]/365, data[:,5])\n",
    "ax.axis('tight')\n",
    "ax.set_title('tempeatures in Stockholm')\n",
    "ax.set_xlabel('year')\n",
    "ax.set_ylabel('temperature (C)');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using `numpy.savetxt` we can store a Numpy array to a file in CSV format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.05789482,  0.66121923,  0.80632966],\n",
       "       [ 0.03723929,  0.45584679,  0.30440743],\n",
       "       [ 0.32259358,  0.54707745,  0.41637897]])"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M = random.rand(3,3)\n",
    "\n",
    "M"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "savetxt(\"random-matrix.csv\", M)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "5.789481752752834165e-02 6.612192311939966149e-01 8.063296621590848590e-01\r\n",
      "3.723928870415726955e-02 4.558467870903764041e-01 3.044074335790650787e-01\r\n",
      "3.225935779856078378e-01 5.470774549225028149e-01 4.163789697297007875e-01\r\n"
     ]
    }
   ],
   "source": [
    "!cat random-matrix.csv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.05789 0.66122 0.80633\r\n",
      "0.03724 0.45585 0.30441\r\n",
      "0.32259 0.54708 0.41638\r\n"
     ]
    }
   ],
   "source": [
    "savetxt(\"random-matrix.csv\", M, fmt='%.5f') # fmt specifies the format\n",
    "\n",
    "!cat random-matrix.csv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Numpy's native file format"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Useful when storing and reading back numpy array data. Use the functions `numpy.save` and `numpy.load`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "random-matrix.npy: data\r\n"
     ]
    }
   ],
   "source": [
    "save(\"random-matrix.npy\", M)\n",
    "\n",
    "!file random-matrix.npy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.05789482,  0.66121923,  0.80632966],\n",
       "       [ 0.03723929,  0.45584679,  0.30440743],\n",
       "       [ 0.32259358,  0.54707745,  0.41637897]])"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load(\"random-matrix.npy\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## More properties of the numpy arrays"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M.itemsize # bytes per element"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "72"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M.nbytes # number of bytes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M.ndim # number of dimensions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Manipulating arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Indexing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can index elements in an array using square brackets and indices:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# v is a vector, and has only one dimension, taking one index\n",
    "v[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.4558467870903764"
      ]
     },
     "execution_count": 39,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# M is a matrix, or a 2 dimensional array, taking two indices \n",
    "M[1,1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we omit an index of a multidimensional array it returns the whole row (or, in general, a N-1 dimensional array) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.05789482,  0.66121923,  0.80632966],\n",
       "       [ 0.03723929,  0.45584679,  0.30440743],\n",
       "       [ 0.32259358,  0.54707745,  0.41637897]])"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0.03723929,  0.45584679,  0.30440743])"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same thing can be achieved with using `:` instead of an index: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0.03723929,  0.45584679,  0.30440743])"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M[1,:] # row 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0.66121923,  0.45584679,  0.54707745])"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M[:,1] # column 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can assign new values to elements in an array using indexing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "M[0,0] = 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 1.        ,  0.66121923,  0.80632966],\n",
       "       [ 0.03723929,  0.45584679,  0.30440743],\n",
       "       [ 0.32259358,  0.54707745,  0.41637897]])"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# also works for rows and columns\n",
    "M[1,:] = 0\n",
    "M[:,2] = -1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 1.        ,  0.66121923, -1.        ],\n",
       "       [ 0.        ,  0.        , -1.        ],\n",
       "       [ 0.32259358,  0.54707745, -1.        ]])"
      ]
     },
     "execution_count": 47,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Index slicing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Index slicing is the technical name for the syntax `M[lower:upper:step]` to extract part of an array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3, 4, 5])"
      ]
     },
     "execution_count": 48,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A = array([1,2,3,4,5])\n",
    "A"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([2, 3])"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A[1:3]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Array slices are *mutable*: if they are assigned a new value the original array from which the slice was extracted is modified:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1, -2, -3,  4,  5])"
      ]
     },
     "execution_count": 50,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A[1:3] = [-2,-3]\n",
    "\n",
    "A"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can omit any of the three parameters in `M[lower:upper:step]`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1, -2, -3,  4,  5])"
      ]
     },
     "execution_count": 51,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A[::] # lower, upper, step all take the default values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1, -3,  5])"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A[::2] # step is 2, lower and upper defaults to the beginning and end of the array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1, -2, -3])"
      ]
     },
     "execution_count": 53,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A[:3] # first three elements"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([4, 5])"
      ]
     },
     "execution_count": 54,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A[3:] # elements from index 3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Negative indices counts from the end of the array (positive index from the begining):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "A = array([1,2,3,4,5])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A[-1] # the last element in the array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([3, 4, 5])"
      ]
     },
     "execution_count": 57,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A[-3:] # the last three elements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Index slicing works exactly the same way for multidimensional arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0,  1,  2,  3,  4],\n",
       "       [10, 11, 12, 13, 14],\n",
       "       [20, 21, 22, 23, 24],\n",
       "       [30, 31, 32, 33, 34],\n",
       "       [40, 41, 42, 43, 44]])"
      ]
     },
     "execution_count": 58,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A = array([[n+m*10 for n in range(5)] for m in range(5)])\n",
    "\n",
    "A"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[11, 12, 13],\n",
       "       [21, 22, 23],\n",
       "       [31, 32, 33]])"
      ]
     },
     "execution_count": 59,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# a block from the original array\n",
    "A[1:4, 1:4]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0,  2,  4],\n",
       "       [20, 22, 24],\n",
       "       [40, 42, 44]])"
      ]
     },
     "execution_count": 60,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# strides\n",
    "A[::2, ::2]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Fancy indexing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fancy indexing is the name for when an array or list is used in-place of an index: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[10, 11, 12, 13, 14],\n",
       "       [20, 21, 22, 23, 24],\n",
       "       [30, 31, 32, 33, 34]])"
      ]
     },
     "execution_count": 61,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "row_indices = [1, 2, 3]\n",
    "A[row_indices]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([11, 22, 34])"
      ]
     },
     "execution_count": 62,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "col_indices = [1, 2, -1] # remember, index -1 means the last element\n",
    "A[row_indices, col_indices]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also use index masks: If the index mask is an Numpy array of data type `bool`, then an element is selected (True) or not (False) depending on the value of the index mask at the position of each element: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 1, 2, 3, 4])"
      ]
     },
     "execution_count": 63,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "B = array([n for n in range(5)])\n",
    "B"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 2])"
      ]
     },
     "execution_count": 64,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "row_mask = array([True, False, True, False, False])\n",
    "B[row_mask]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 2])"
      ]
     },
     "execution_count": 65,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# same thing\n",
    "row_mask = array([1,0,1,0,0], dtype=bool)\n",
    "B[row_mask]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This feature is very useful to conditionally select elements from an array, using for example comparison operators:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0. ,  0.5,  1. ,  1.5,  2. ,  2.5,  3. ,  3.5,  4. ,  4.5,  5. ,\n",
       "        5.5,  6. ,  6.5,  7. ,  7.5,  8. ,  8.5,  9. ,  9.5])"
      ]
     },
     "execution_count": 66,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = arange(0, 10, 0.5)\n",
    "x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([False, False, False, False, False, False, False, False, False,\n",
       "       False, False,  True,  True,  True,  True, False, False, False,\n",
       "       False, False], dtype=bool)"
      ]
     },
     "execution_count": 67,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mask = (5 < x) * (x < 7.5)\n",
    "\n",
    "mask"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 5.5,  6. ,  6.5,  7. ])"
      ]
     },
     "execution_count": 68,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x[mask]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Functions for extracting data from arrays and creating arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### where"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The index mask can be converted to position index using the `where` function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 69,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([11, 12, 13, 14]),)"
      ]
     },
     "execution_count": 69,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "indices = where(mask)\n",
    "\n",
    "indices"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 70,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 5.5,  6. ,  6.5,  7. ])"
      ]
     },
     "execution_count": 70,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x[indices] # this indexing is equivalent to the fancy indexing x[mask]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### diag"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the diag function we can also extract the diagonal and subdiagonals of an array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 71,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0, 11, 22, 33, 44])"
      ]
     },
     "execution_count": 71,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "diag(A)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 72,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([10, 21, 32, 43])"
      ]
     },
     "execution_count": 72,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "diag(A, -1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### choose"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Constructs an array by picking elements from several arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 5, -2,  5, -2])"
      ]
     },
     "execution_count": 73,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "which = [1, 0, 1, 0]\n",
    "choices = [[-2,-2,-2,-2], [5,5,5,5]]\n",
    "\n",
    "choose(which, choices)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Linear algebra"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Vectorizing code is the key to writing efficient numerical calculation with Python/Numpy. That means that as much as possible of a program should be formulated in terms of matrix and vector operations, like matrix-matrix multiplication."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Scalar-array operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use the usual arithmetic operators to multiply, add, subtract, and divide arrays with scalar numbers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "v1 = arange(0, 5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 75,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 2, 4, 6, 8])"
      ]
     },
     "execution_count": 75,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v1 * 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 76,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([2, 3, 4, 5, 6])"
      ]
     },
     "execution_count": 76,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v1 + 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 77,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([[ 0,  2,  4,  6,  8],\n",
       "        [20, 22, 24, 26, 28],\n",
       "        [40, 42, 44, 46, 48],\n",
       "        [60, 62, 64, 66, 68],\n",
       "        [80, 82, 84, 86, 88]]), array([[ 2,  3,  4,  5,  6],\n",
       "        [12, 13, 14, 15, 16],\n",
       "        [22, 23, 24, 25, 26],\n",
       "        [32, 33, 34, 35, 36],\n",
       "        [42, 43, 44, 45, 46]]))"
      ]
     },
     "execution_count": 77,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A * 2, A + 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Element-wise array-array operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we add, subtract, multiply and divide arrays with each other, the default behaviour is **element-wise** operations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 78,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[   0,    1,    4,    9,   16],\n",
       "       [ 100,  121,  144,  169,  196],\n",
       "       [ 400,  441,  484,  529,  576],\n",
       "       [ 900,  961, 1024, 1089, 1156],\n",
       "       [1600, 1681, 1764, 1849, 1936]])"
      ]
     },
     "execution_count": 78,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A * A # element-wise multiplication"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 79,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0,  1,  4,  9, 16])"
      ]
     },
     "execution_count": 79,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v1 * v1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we multiply arrays with compatible shapes, we get an element-wise multiplication of each row:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 80,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((5, 5), (5,))"
      ]
     },
     "execution_count": 80,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A.shape, v1.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 81,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[  0,   1,   4,   9,  16],\n",
       "       [  0,  11,  24,  39,  56],\n",
       "       [  0,  21,  44,  69,  96],\n",
       "       [  0,  31,  64,  99, 136],\n",
       "       [  0,  41,  84, 129, 176]])"
      ]
     },
     "execution_count": 81,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A * v1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Matrix algebra"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What about matrix mutiplication? There are two ways. We can either use the `dot` function, which applies a matrix-matrix, matrix-vector, or inner vector multiplication to its two arguments: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 82,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 300,  310,  320,  330,  340],\n",
       "       [1300, 1360, 1420, 1480, 1540],\n",
       "       [2300, 2410, 2520, 2630, 2740],\n",
       "       [3300, 3460, 3620, 3780, 3940],\n",
       "       [4300, 4510, 4720, 4930, 5140]])"
      ]
     },
     "execution_count": 82,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dot(A, A)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 83,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 30, 130, 230, 330, 430])"
      ]
     },
     "execution_count": 83,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dot(A, v1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 84,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "30"
      ]
     },
     "execution_count": 84,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dot(v1, v1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, we can cast the array objects to the type `matrix`. This changes the behavior of the standard arithmetic operators `+, -, *` to use matrix algebra."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 85,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "M = matrix(A)\n",
    "v = matrix(v1).T # make it a column vector"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 86,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "matrix([[0],\n",
       "        [1],\n",
       "        [2],\n",
       "        [3],\n",
       "        [4]])"
      ]
     },
     "execution_count": 86,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 87,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "matrix([[ 300,  310,  320,  330,  340],\n",
       "        [1300, 1360, 1420, 1480, 1540],\n",
       "        [2300, 2410, 2520, 2630, 2740],\n",
       "        [3300, 3460, 3620, 3780, 3940],\n",
       "        [4300, 4510, 4720, 4930, 5140]])"
      ]
     },
     "execution_count": 87,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M * M"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 88,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "matrix([[ 30],\n",
       "        [130],\n",
       "        [230],\n",
       "        [330],\n",
       "        [430]])"
      ]
     },
     "execution_count": 88,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M * v"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 89,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "matrix([[30]])"
      ]
     },
     "execution_count": 89,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# inner product\n",
    "v.T * v"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 90,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "matrix([[ 30],\n",
       "        [131],\n",
       "        [232],\n",
       "        [333],\n",
       "        [434]])"
      ]
     },
     "execution_count": 90,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# with matrix objects, standard matrix algebra applies\n",
    "v + M*v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we try to add, subtract or multiply objects with incomplatible shapes we get an error:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 91,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "v = matrix([1,2,3,4,5,6]).T"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 92,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((5, 5), (6, 1))"
      ]
     },
     "execution_count": 92,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "shape(M), shape(v)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 93,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "shapes (5,5) and (6,1) not aligned: 5 (dim 1) != 6 (dim 0)",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-93-995fb48ad0cc>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mM\u001b[0m \u001b[0;34m*\u001b[0m \u001b[0mv\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m~/anaconda3/lib/python3.6/site-packages/numpy/matrixlib/defmatrix.py\u001b[0m in \u001b[0;36m__mul__\u001b[0;34m(self, other)\u001b[0m\n\u001b[1;32m    307\u001b[0m         \u001b[0;32mif\u001b[0m \u001b[0misinstance\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mother\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m(\u001b[0m\u001b[0mN\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mndarray\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mlist\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mtuple\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    308\u001b[0m             \u001b[0;31m# This promotes 1-D vectors to row vectors\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 309\u001b[0;31m             \u001b[0;32mreturn\u001b[0m \u001b[0mN\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mdot\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mself\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0masmatrix\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mother\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    310\u001b[0m         \u001b[0;32mif\u001b[0m \u001b[0misscalar\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mother\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;32mor\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0mhasattr\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mother\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m'__rmul__'\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    311\u001b[0m             \u001b[0;32mreturn\u001b[0m \u001b[0mN\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mdot\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mself\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mother\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mValueError\u001b[0m: shapes (5,5) and (6,1) not aligned: 5 (dim 1) != 6 (dim 0)"
     ]
    }
   ],
   "source": [
    "M * v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See also the related functions: `inner`, `outer`, `cross`, `kron`, `tensordot`. Try for example `help(kron)`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Data processing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Often it is useful to store datasets in Numpy arrays. Numpy provides a number of functions to calculate statistics of datasets in arrays. \n",
    "\n",
    "For example, let's calculate some properties from the Stockholm temperature dataset used above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 94,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(77431, 7)"
      ]
     },
     "execution_count": 94,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# reminder, the tempeature dataset is stored in the data variable:\n",
    "shape(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### mean"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 95,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6.1971096847515854"
      ]
     },
     "execution_count": 95,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# the temperature data is in column 3\n",
    "mean(data[:,3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The daily mean temperature in Stockholm over the last 200 years has been about 6.2 C."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### standard deviations and variance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 96,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(8.2822716213405734, 68.596023209663414)"
      ]
     },
     "execution_count": 96,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "std(data[:,3]), var(data[:,3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### min and max"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 97,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-25.800000000000001"
      ]
     },
     "execution_count": 97,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# lowest daily average temperature\n",
    "data[:,3].min()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 98,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "28.300000000000001"
      ]
     },
     "execution_count": 98,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# highest daily average temperature\n",
    "data[:,3].max()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### sum, prod, and trace"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 99,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])"
      ]
     },
     "execution_count": 99,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "d = arange(0, 10)\n",
    "d"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 100,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "45"
      ]
     },
     "execution_count": 100,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# sum up all elements\n",
    "sum(d)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 101,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3628800"
      ]
     },
     "execution_count": 101,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# product of all elements\n",
    "prod(d+1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 102,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0,  1,  3,  6, 10, 15, 21, 28, 36, 45])"
      ]
     },
     "execution_count": 102,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# cummulative sum\n",
    "cumsum(d)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([      1,       2,       6,      24,     120,     720,    5040,\n",
       "         40320,  362880, 3628800])"
      ]
     },
     "execution_count": 103,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# cummulative product\n",
    "cumprod(d+1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 104,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "110"
      ]
     },
     "execution_count": 104,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# same as: diag(A).sum()\n",
    "trace(A)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reshaping, resizing and stacking arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The shape of an Numpy array can be modified without copying the underlaying data, which makes it a fast operation even for large arrays."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 105,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0,  1,  2,  3,  4],\n",
       "       [10, 11, 12, 13, 14],\n",
       "       [20, 21, 22, 23, 24],\n",
       "       [30, 31, 32, 33, 34],\n",
       "       [40, 41, 42, 43, 44]])"
      ]
     },
     "execution_count": 105,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 106,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "n, m = A.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 107,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0,  1,  2,  3,  4, 10, 11, 12, 13, 14, 20, 21, 22, 23, 24, 30, 31,\n",
       "        32, 33, 34, 40, 41, 42, 43, 44]])"
      ]
     },
     "execution_count": 107,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "B = A.reshape((1,n*m))\n",
    "B"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 108,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 5,  5,  5,  5,  5, 10, 11, 12, 13, 14, 20, 21, 22, 23, 24, 30, 31,\n",
       "        32, 33, 34, 40, 41, 42, 43, 44]])"
      ]
     },
     "execution_count": 108,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "B[0,0:5] = 5 # modify the array\n",
    "\n",
    "B"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 109,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 5,  5,  5,  5,  5],\n",
       "       [10, 11, 12, 13, 14],\n",
       "       [20, 21, 22, 23, 24],\n",
       "       [30, 31, 32, 33, 34],\n",
       "       [40, 41, 42, 43, 44]])"
      ]
     },
     "execution_count": 109,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A # and the original variable is also changed. B is only a different view of the same data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also use the function `flatten` to make a higher-dimensional array into a vector. But this function create a copy of the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 110,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 5,  5,  5,  5,  5, 10, 11, 12, 13, 14, 20, 21, 22, 23, 24, 30, 31,\n",
       "       32, 33, 34, 40, 41, 42, 43, 44])"
      ]
     },
     "execution_count": 110,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "B = A.flatten()\n",
    "\n",
    "B"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 111,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([10, 10, 10, 10, 10, 10, 11, 12, 13, 14, 20, 21, 22, 23, 24, 30, 31,\n",
       "       32, 33, 34, 40, 41, 42, 43, 44])"
      ]
     },
     "execution_count": 111,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "B[0:5] = 10\n",
    "\n",
    "B"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 112,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 5,  5,  5,  5,  5],\n",
       "       [10, 11, 12, 13, 14],\n",
       "       [20, 21, 22, 23, 24],\n",
       "       [30, 31, 32, 33, 34],\n",
       "       [40, 41, 42, 43, 44]])"
      ]
     },
     "execution_count": 112,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A # now A has not changed, because B's data is a copy of A's, not refering to the same data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Copy and \"deep copy\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To achieve high performance, assignments in Python usually do not copy the underlaying objects. This is important for example when objects are passed between functions, to avoid an excessive amount of memory copying when it is not necessary (technical term: pass by reference). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 113,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[1, 2],\n",
       "       [3, 4]])"
      ]
     },
     "execution_count": 113,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A = array([[1, 2], [3, 4]])\n",
    "\n",
    "A"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 114,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# now B is referring to the same array data as A \n",
    "B = A "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 115,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[10,  2],\n",
       "       [ 3,  4]])"
      ]
     },
     "execution_count": 115,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# changing B affects A\n",
    "B[0,0] = 10\n",
    "\n",
    "B"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 116,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[10,  2],\n",
       "       [ 3,  4]])"
      ]
     },
     "execution_count": 116,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want to avoid this behavior, so that when we get a new completely independent object `B` copied from `A`, then we need to do a so-called \"deep copy\" using the function `copy`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 117,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "B = copy(A)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 118,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[-5,  2],\n",
       "       [ 3,  4]])"
      ]
     },
     "execution_count": 118,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# now, if we modify B, A is not affected\n",
    "B[0,0] = -5\n",
    "\n",
    "B"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 119,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[10,  2],\n",
       "       [ 3,  4]])"
      ]
     },
     "execution_count": 119,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Iterating over array elements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Generally, we want to avoid iterating over the elements of arrays whenever we can (at all costs). The reason is that in a interpreted language like Python (or MATLAB), iterations are really slow compared to vectorized operations. \n",
    "\n",
    "However, sometimes iterations are unavoidable. For such cases, the Python `for` loop is the most convenient way to iterate over an array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 120,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n",
      "2\n",
      "3\n",
      "4\n"
     ]
    }
   ],
   "source": [
    "v = array([1,2,3,4])\n",
    "\n",
    "for element in v:\n",
    "    print(element)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 121,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "row [1 2]\n",
      "1\n",
      "2\n",
      "row [3 4]\n",
      "3\n",
      "4\n"
     ]
    }
   ],
   "source": [
    "M = array([[1,2], [3,4]])\n",
    "\n",
    "for row in M:\n",
    "    print(\"row\", row)\n",
    "    \n",
    "    for element in row:\n",
    "        print(element)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we need to iterate over each element of an array and modify its elements, it is convenient to use the `enumerate` function to obtain both the element and its index in the `for` loop: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 122,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "row_idx 0 row [1 2]\n",
      "col_idx 0 element 1\n",
      "col_idx 1 element 2\n",
      "row_idx 1 row [3 4]\n",
      "col_idx 0 element 3\n",
      "col_idx 1 element 4\n"
     ]
    }
   ],
   "source": [
    "for row_idx, row in enumerate(M):\n",
    "    print(\"row_idx\", row_idx, \"row\", row)\n",
    "    \n",
    "    for col_idx, element in enumerate(row):\n",
    "        print(\"col_idx\", col_idx, \"element\", element)\n",
    "       \n",
    "        # update the matrix M: square each element\n",
    "        M[row_idx, col_idx] = element ** 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 123,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 1,  4],\n",
       "       [ 9, 16]])"
      ]
     },
     "execution_count": 123,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# each element in M is now squared\n",
    "M"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Vectorizing functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As mentioned several times by now, to get good performance we should try to avoid looping over elements in our vectors and matrices, and instead use vectorized algorithms. The first step in converting a scalar algorithm to a vectorized algorithm is to make sure that the functions we write work with vector inputs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 124,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def Theta(x):\n",
    "    \"\"\"\n",
    "    Scalar implemenation of the Heaviside step function.\n",
    "    \"\"\"\n",
    "    if x >= 0:\n",
    "        return 1\n",
    "    else:\n",
    "        return 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 125,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-125-6658efdd2f22>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mTheta\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0marray\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m-\u001b[0m\u001b[0;36m3\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m-\u001b[0m\u001b[0;36m2\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m-\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;36m0\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;36m2\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;36m3\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m<ipython-input-124-9a0cb13d93d4>\u001b[0m in \u001b[0;36mTheta\u001b[0;34m(x)\u001b[0m\n\u001b[1;32m      3\u001b[0m     \u001b[0mScalar\u001b[0m \u001b[0mimplemenation\u001b[0m \u001b[0mof\u001b[0m \u001b[0mthe\u001b[0m \u001b[0mHeaviside\u001b[0m \u001b[0mstep\u001b[0m \u001b[0mfunction\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      4\u001b[0m     \"\"\"\n\u001b[0;32m----> 5\u001b[0;31m     \u001b[0;32mif\u001b[0m \u001b[0mx\u001b[0m \u001b[0;34m>=\u001b[0m \u001b[0;36m0\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      6\u001b[0m         \u001b[0;32mreturn\u001b[0m \u001b[0;36m1\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      7\u001b[0m     \u001b[0;32melse\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mValueError\u001b[0m: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()"
     ]
    }
   ],
   "source": [
    "Theta(array([-3,-2,-1,0,1,2,3]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OK, that didn't work because we didn't write the `Theta` function so that it can handle a vector input... \n",
    "\n",
    "To get a vectorized version of Theta we can use the Numpy function `vectorize`. In many cases it can automatically vectorize a function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 126,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "Theta_vec = vectorize(Theta)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 127,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 0, 0, 1, 1, 1, 1])"
      ]
     },
     "execution_count": 127,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Theta_vec(array([-3,-2,-1,0,1,2,3]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also implement the function to accept a vector input from the beginning (requires more effort but might give better performance):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 128,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def Theta(x):\n",
    "    \"\"\"\n",
    "    Vector-aware implemenation of the Heaviside step function.\n",
    "    \"\"\"\n",
    "    return 1 * (x >= 0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 129,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 0, 0, 1, 1, 1, 1])"
      ]
     },
     "execution_count": 129,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Theta(array([-3,-2,-1,0,1,2,3]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 130,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(0, 1)"
      ]
     },
     "execution_count": 130,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# still works for scalars as well\n",
    "Theta(-1.2), Theta(2.6)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using arrays in conditions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When using arrays in conditions,for example `if` statements and other boolean expressions, one needs to use `any` or `all`, which requires that any or all elements in the array evalutes to `True`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 131,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 1,  4],\n",
       "       [ 9, 16]])"
      ]
     },
     "execution_count": 131,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 132,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "at least one element in M is larger than 5\n"
     ]
    }
   ],
   "source": [
    "if (M > 5).any():\n",
    "    print(\"at least one element in M is larger than 5\")\n",
    "else:\n",
    "    print(\"no element in M is larger than 5\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 133,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "all elements in M are not larger than 5\n"
     ]
    }
   ],
   "source": [
    "if (M > 5).all():\n",
    "    print(\"all elements in M are larger than 5\")\n",
    "else:\n",
    "    print(\"all elements in M are not larger than 5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Type casting"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since Numpy arrays are *statically typed*, the type of an array does not change once created. But we can explicitly cast an array of some type to another using the `astype` functions (see also the similar `asarray` function). This always create a new array of new type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 134,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dtype('int64')"
      ]
     },
     "execution_count": 134,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M.dtype"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 135,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[  1.,   4.],\n",
       "       [  9.,  16.]])"
      ]
     },
     "execution_count": 135,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M2 = M.astype(float)\n",
    "\n",
    "M2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 136,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dtype('float64')"
      ]
     },
     "execution_count": 136,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M2.dtype"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 137,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ True,  True],\n",
       "       [ True,  True]], dtype=bool)"
      ]
     },
     "execution_count": 137,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "M3 = M.astype(bool)\n",
    "\n",
    "M3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Let's talk about speed\n",
    "\n",
    "#### Say that we want to do something on a matrix, for example keeping only values higher than a threshold"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 160,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.23546808,  0.0352588 ,  0.66179581, ...,  0.96980351,\n",
       "         0.15712592,  0.24425445],\n",
       "       [ 0.37382733,  0.86337864,  0.21906961, ...,  0.85269583,\n",
       "         0.42278961,  0.71758059],\n",
       "       [ 0.35975998,  0.53332745,  0.98166478, ...,  0.75175107,\n",
       "         0.79121302,  0.83045878],\n",
       "       ..., \n",
       "       [ 0.40626926,  0.27096246,  0.54969797, ...,  0.93332057,\n",
       "         0.16149099,  0.30982478],\n",
       "       [ 0.28669572,  0.57411381,  0.62642928, ...,  0.82057438,\n",
       "         0.88882099,  0.86694087],\n",
       "       [ 0.67462119,  0.54867147,  0.35225068, ...,  0.29559694,\n",
       "         0.19375853,  0.76522314]])"
      ]
     },
     "execution_count": 160,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "threshold = 0.7\n",
    "\n",
    "big_matrix = random.random((10000,10000))\n",
    "big_matrix"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution 1 - Loops"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 161,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Loop takes 38.81 seconds\n"
     ]
    }
   ],
   "source": [
    "import time\n",
    "\n",
    "big_matrix_copy = big_matrix.copy()\n",
    "\n",
    "start_time = time.time()\n",
    "\n",
    "for row_index in range(big_matrix.shape[0]):\n",
    "    for colum_index in range(big_matrix.shape[1]):\n",
    "        \n",
    "        if big_matrix_copy[row_index,colum_index]<threshold:\n",
    "            big_matrix_copy[row_index,colum_index] = 0.0\n",
    "        \n",
    "print(\"Loop takes {:.2f} seconds\".format(time.time()-start_time))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 162,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.        ,  0.        ,  0.        , ...,  0.96980351,\n",
       "         0.        ,  0.        ],\n",
       "       [ 0.        ,  0.86337864,  0.        , ...,  0.85269583,\n",
       "         0.        ,  0.71758059],\n",
       "       [ 0.        ,  0.        ,  0.98166478, ...,  0.75175107,\n",
       "         0.79121302,  0.83045878],\n",
       "       ..., \n",
       "       [ 0.        ,  0.        ,  0.        , ...,  0.93332057,\n",
       "         0.        ,  0.        ],\n",
       "       [ 0.        ,  0.        ,  0.        , ...,  0.82057438,\n",
       "         0.88882099,  0.86694087],\n",
       "       [ 0.        ,  0.        ,  0.        , ...,  0.        ,\n",
       "         0.        ,  0.76522314]])"
      ]
     },
     "execution_count": 162,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "big_matrix_copy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution 2 - Vectorization with boolean indexing"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 164,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Vectorization takes 0.73 seconds\n"
     ]
    }
   ],
   "source": [
    "start_time = time.time()\n",
    "\n",
    "big_matrix_copy = big_matrix.copy()\n",
    "\n",
    "big_matrix_copy[big_matrix_copy<threshold]= 0.0\n",
    "        \n",
    "print(\"Vectorization takes {:.2f} seconds\".format(time.time()-start_time))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 165,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.        ,  0.        ,  0.        , ...,  0.96980351,\n",
       "         0.        ,  0.        ],\n",
       "       [ 0.        ,  0.86337864,  0.        , ...,  0.85269583,\n",
       "         0.        ,  0.71758059],\n",
       "       [ 0.        ,  0.        ,  0.98166478, ...,  0.75175107,\n",
       "         0.79121302,  0.83045878],\n",
       "       ..., \n",
       "       [ 0.        ,  0.        ,  0.        , ...,  0.93332057,\n",
       "         0.        ,  0.        ],\n",
       "       [ 0.        ,  0.        ,  0.        , ...,  0.82057438,\n",
       "         0.88882099,  0.86694087],\n",
       "       [ 0.        ,  0.        ,  0.        , ...,  0.        ,\n",
       "         0.        ,  0.76522314]])"
      ]
     },
     "execution_count": 165,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "big_matrix_copy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### In this case vectorization is >50x faster than loops, it will easily be much faster in a more realistic and complex computation\n",
    "\n",
    "### Take home message: NEVER use loops for computational tasks that can be easily vectorized"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further reading"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* http://numpy.scipy.org\n",
    "* http://scipy.org/Tentative_NumPy_Tutorial\n",
    "* http://scipy.org/NumPy_for_Matlab_Users - A Numpy guide for MATLAB users."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}