NumPy_3-Array_Oriented_Programming_With_Arrays.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h1 id=\"tocheading\">Table of Contents and Notebook Setup</h1>\n",
    "<div id=\"toc\"></div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "$.getScript('https://kmahelona.github.io/ipython_notebook_goodies/ipython_notebook_toc.js')"
      ],
      "text/plain": [
       "<IPython.core.display.Javascript object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%javascript\n",
    "$.getScript('https://kmahelona.github.io/ipython_notebook_goodies/ipython_notebook_toc.js')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The common expression for replacing explicit loops with array expressions is commonly referred to as <i> vectorization. </i> In general, python vectorized operations will often be one or two orders of magnitude faster than their pure python equivalents."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a simple example, suppose we want to compute $z=\\sqrt{x^2 +y^2}$ across a regular grid of values. The np.meshgrid function takes two 1D arrays and returns two 2D matrices corresponding to all the pairs of (x, y) in the two arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "points = np.arange(-5, 5, 0.01)\n",
    "xs, ys = np.meshgrid(points, points)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can compute the value of $z$ across the grid:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 7.07106781,  7.06400028,  7.05693985, ...,  7.04988652,\n",
       "         7.05693985,  7.06400028],\n",
       "       [ 7.06400028,  7.05692568,  7.04985815, ...,  7.04279774,\n",
       "         7.04985815,  7.05692568],\n",
       "       [ 7.05693985,  7.04985815,  7.04278354, ...,  7.03571603,\n",
       "         7.04278354,  7.04985815],\n",
       "       ..., \n",
       "       [ 7.04988652,  7.04279774,  7.03571603, ...,  7.0286414 ,\n",
       "         7.03571603,  7.04279774],\n",
       "       [ 7.05693985,  7.04985815,  7.04278354, ...,  7.03571603,\n",
       "         7.04278354,  7.04985815],\n",
       "       [ 7.06400028,  7.05692568,  7.04985815, ...,  7.04279774,\n",
       "         7.04985815,  7.05692568]])"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "zs = np.sqrt(xs**2+ys**2)\n",
    "zs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets create a visualization <i> of the array </i> using matplotlib:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\nTU5W/n/pZdylbhHM5wAAAABJRU5ErkJggg==\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x120b32390>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.imshow(zs, cmap=plt.cm.gray); plt.colorbar()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This maps out the array; not the contour plot which is shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\nB2dB7//ahdj8AAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x119dc3e80>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.contourf(xs, ys, np.sqrt(xs**2+ys**2), 20, cmap=plt.cm.gray); plt.colorbar()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Expressing Conditional Logic as Array Operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The numpy.where() function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is where vectorized notation becomes extremely useful and speeds up computation processes by orders of magnitude. \n",
    "\n",
    "Suppose we have two arrays, x and y, and a logical condition array. Suppose we want to take the value in x if the logic array is true and y otherwise. Hardcoded, this would look like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1.1000000000000001, 2.2000000000000002, 1.3, 1.3999999999999999, 1.5]"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x_arr = np.array([1.1, 1.2, 1.3, 1.4, 1.5])\n",
    "y_arr = np.array([2.1, 2.2, 2.3, 2.4, 2.5])\n",
    "logic_arr = [True, False, True, True, True]\n",
    "\n",
    "result = [(x if c else y) for (x, y, c) in zip(x_arr, y_arr, logic_arr)]\n",
    "result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This operation is bad for multiple reasons. Firstly it is not fast for large arrays (all the work is being done in the interpretted python code). Secondly, it does't work for multidimensional arrays."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The 'numpy.where' function gets around this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1.1,  2.2,  1.3,  1.4,  1.5])"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.where(logic_arr, x_arr, y_arr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The second and third arguments don't need to be arrays; they can also be scalars."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 0, 1, 1, 1])"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.where(logic_arr, 1, 0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using the numpy.where() Function for Multidimensional Arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose we generate an array of random values and we want to replace all the positive values with 2 and all the negative values with -2. That task can be accomplished as such:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[-2, -2, -2, -2],\n",
       "       [ 2,  2, -2,  2],\n",
       "       [-2, -2, -2, -2],\n",
       "       [-2,  2,  2, -2]])"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr=np.random.randn(4,4)\n",
    "\n",
    "np.where(arr > 0, 2, -2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Maybe we only want to set the positive values to 2 and leave the negative values as is. For this, we simply put"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[-1.15510372, -0.11350281, -2.86889573, -1.53008866],\n",
       "       [ 2.        ,  2.        , -0.44298618,  2.        ],\n",
       "       [-1.3088984 , -1.86790419, -0.51733743, -2.29391859],\n",
       "       [-0.51954329,  2.        ,  2.        , -0.52059729]])"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.where(arr > 0, 2, arr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The last argument 'arr' tells the function that where the logical condition isn't true, leave the array as is."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Mathematical and Statistical Methods"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Operations Across Columns and Rows"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A set of functions that compute statistics about an entire array or along its axes are accessible as methods of the array class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 2.27875203,  0.55908222, -1.15416693, -0.35170972],\n",
       "       [ 0.71971218,  0.41673629, -1.01383459, -1.15827976],\n",
       "       [-0.99435714,  1.43362721, -1.11078581,  1.29128574],\n",
       "       [-0.47915822, -0.32523819,  0.19283097,  0.14041619],\n",
       "       [-0.31445045, -0.97885446,  1.39959584,  0.15222086]])"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr = np.random.randn(5,4)\n",
    "arr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.035171213663824932"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.mean(arr)\n",
    "arr.mean() #equivalent"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The methods are particularily useful in that we can choose the axis we like."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0.3329894 , -0.25891647,  0.1549425 , -0.11778731,  0.06462795])"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr.mean(axis=1) #across the columns"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1.21049841,  1.10535307, -1.68636051,  0.07393331])"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr.sum(axis=0) #down the rows"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Functions the Aggregate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions like cumsum() and cumprod() do not aggregrate, they instead return an array of the same size."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1,  4,  8, 14, 21, 29])"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr = np.array([1,3,4,6,7,8])\n",
    "arr.cumsum()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In multidimensional arrays, accumulation functions return an array of the same size as well, but the partial aggregrates are computed along a specific axis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[0, 1, 2],\n",
       "       [3, 4, 5],\n",
       "       [6, 7, 8]])"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr = np.arange(9).reshape((3,3))\n",
    "arr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0,  1,  2],\n",
       "       [ 3,  5,  7],\n",
       "       [ 9, 12, 15]])"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr.cumsum(axis=0) #down the rows"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0,  1,  3],\n",
       "       [ 3,  7, 12],\n",
       "       [ 6, 13, 21]])"
      ]
     },
     "execution_count": 39,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr.cumsum(axis=1) #across the columns"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Methods for Boolean Arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Counting Occurences of a Logical Statement in an Array"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Boolean values are coerced to 1 if True and 0 if False. Sum can thus be used to count True values in a boolean array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "49"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr=np.random.randn(100)\n",
    "(arr>0).sum()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also use 'any' and 'all' to check for boolean values in an array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "bools = np.array([False, False, True, False])\n",
    "\n",
    "print(bools.any())\n",
    "print(bools.all())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Sorting"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sorting 1D"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NumPy arrays can be sorted in-place using the sort method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0.77136532, -0.94246812,  0.25230917, -0.62054798, -2.3599155 ])"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr = np.random.randn(5)\n",
    "arr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([-2.3599155 , -0.94246812, -0.62054798,  0.25230917,  0.77136532])"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr.sort()\n",
    "arr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sorting Higher Dimensional"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like before, we must choose an axis to sort along."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[-0.85429423,  2.18855122, -0.27705508],\n",
       "       [ 2.05510688,  0.69444916,  0.66546695],\n",
       "       [-0.24196734,  0.01627874, -0.23757773],\n",
       "       [ 0.39127044,  0.79968423, -0.24622783],\n",
       "       [ 1.68799421, -1.16487195, -0.39775485]])"
      ]
     },
     "execution_count": 47,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr = np.random.randn(5,3)\n",
    "arr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[-0.85429423, -0.27705508,  2.18855122],\n",
       "       [ 0.66546695,  0.69444916,  2.05510688],\n",
       "       [-0.24196734, -0.23757773,  0.01627874],\n",
       "       [-0.24622783,  0.39127044,  0.79968423],\n",
       "       [-1.16487195, -0.39775485,  1.68799421]])"
      ]
     },
     "execution_count": 50,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "arr.sort(1) #across columns\n",
    "arr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Unique and Other Set Logic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NumPy has other basic set operations for one dimensional ndarrays. One is np.unique that returns the sorted unique values in an array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "names = np.array(['Bob','Joe','Bob','Will','Adam',])"
   ]
  }
 ],
 "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}