Lecture_07.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-03-11T01:38:13.070076Z",
     "start_time": "2020-03-11T01:38:11.603428Z"
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from IPython.display import Image # Just ignore this one for now...  next lecture, you will learn about it.\n",
    "import os"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##  Lecture 7\n",
    "\n",
    "### Learning objectives\n",
    "\n",
    "- Learn more ways to create **NumPy** `ndarray`’s\n",
    "- Learn how to create and manipulate 2-dimensional `ndarray`’s.\n",
    "- Learn some new methods of the `ndarray` class.\n",
    "- Learn how to convert between the `ndarray` and `list` objects.\n",
    "- Learn how to write an `ndarray` to a file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "\n",
    "### 7.1 NumPy and N-dimensional arrays\n",
    "\n",
    "We briefly mentioned **arrays** in the last lecture but quickly moved into plotting (because that is more fun). But **arrays** are essential to our computational happiness, so we need to bite the bullet and learn about them now. \n",
    "\n",
    "**Arrays**  in **NumPy**  are somewhat  similar to  lists but there are important differences with advantages and disadvantages.\n",
    "Unlike lists,   **arrays** are usually all of the same data type (`dtype`), usually numbers (integers or floats) and at times characters.  A \"feature\" of arrays is that the size,  shape and type are fixed when it's created. \n",
    "\n",
    "Remember, we can define a list:\n",
    "\n",
    "```python\n",
    "L = []\n",
    "```\n",
    "\n",
    "then append to it as desired using the `L.append()` method. It is more complicated (but still possible) to **extend** arrays. \n",
    "\n",
    "Why use arrays when you can use lists?  Arrays are far more computationally efficient than lists, particularly for things like matrix math.  You can perform calculations on the entire array in one go instead of looping through element by element as for lists.  \n",
    "\n",
    "To make things a little confusing, there are  several different data objects that are loosely called arrays, e.g., arrays, character arrays and matrices.  These are all subclasses of `ndarray` (N-dimensional array).  We will just worry about **arrays** in this course.  \n",
    "\n",
    "Apart from reading in a data file with **NumPy**, as we did in the last lecture, there are many different ways of creating arrays.  Here are a few examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[1 2 3]\n",
      " [4 2 0]\n",
      " [1 1 2]]\n"
     ]
    }
   ],
   "source": [
    "# Define the values with the function array( ). For example a 3x3 array.\n",
    "A = np.array([[1, 2, 3], [4, 2, 0], [1, 1, 2]])\n",
    "print(A)\n",
    "\n",
    "# Notice how there are no commas in displayed output of an array."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we learned in the last lecture, **NumPy** can also generate an array using the `np.arange()` function which works in a manner similar to `range()` but creates an array with floats or integers. `range()` makes a list generator.  \n",
    "\n",
    "This is just a reminder from Lecture 6:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "List made by range(): [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n",
      "Array made by np.arange(integers): [0 1 2 3 4 5 6 7 8 9]\n",
      "Array made by np.arange(numbers):\n",
      " [0.  0.2 0.4 0.6 0.8 1.  1.2 1.4 1.6 1.8 2.  2.2 2.4 2.6 2.8 3.  3.2 3.4\n",
      " 3.6 3.8 4.  4.2 4.4 4.6 4.8 5.  5.2 5.4 5.6 5.8 6.  6.2 6.4 6.6 6.8 7.\n",
      " 7.2 7.4 7.6 7.8 8.  8.2 8.4 8.6 8.8 9.  9.2 9.4 9.6 9.8]\n"
     ]
    }
   ],
   "source": [
    "# Use list(range()) to generate a one-dimensional (1D) list that ranges \n",
    "# from the first arguement up to (but not including) the second, that\n",
    "# increments by the third:\n",
    "# We learned that range() creates a list generator for integers\n",
    "B = list(range(10)) \n",
    "print(\"List made by range():\", B)\n",
    "B_integers = np.arange(0, 10, 1) # arange() is an np function that creates an array of integers.\n",
    "print(\"Array made by np.arange(integers):\", B_integers)\n",
    "B_real = np.arange(0, 10, 0.2) #  arange() with with floats.\n",
    "print(\"Array made by np.arange(numbers):\\n\", B_real) # Notice the \"\\n\"? That creates a new line in the text string.\n",
    "# Notice that while \"range()\" makes a list of integers, \n",
    "# arange makes an array of integers or real numbers.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are several ways to create special arrays, for example, arrays initialized by zeroes, ones, or any other value: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0. 0. 0.]\n",
      " [0. 0. 0.]]\n"
     ]
    }
   ],
   "source": [
    "D = np.zeros((2, 3)) # Notice the size is specified by a tuple of numbers of rows and columns.\n",
    "print(D)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[1. 1. 1.]\n",
      " [1. 1. 1.]]\n"
     ]
    }
   ],
   "source": [
    "E = np.ones((2, 3))\n",
    "print(E)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get any other value, just multiply your \"ones\" array by whatever number you want:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[42. 42. 42.]\n",
      " [42. 42. 42.]]\n"
     ]
    }
   ],
   "source": [
    "print(E*42)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you might have guessed, `np.arange(start, end, step)` generates numbers between two endpoints (`start` and up to but not including `end`) that are spaced by `step`. \n",
    "\n",
    "At times, it is useful to have $N$ numbers equally spaced between two endpoints. For this, we use the function `np.linspace(start, end, N)` which generates an array starting with `start`, going up to (and including!) `end` with $N$ linearly spaced elements:  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "F: [ 0.          0.76923077  1.53846154  2.30769231  3.07692308  3.84615385\n",
      "  4.61538462  5.38461538  6.15384615  6.92307692  7.69230769  8.46153846\n",
      "  9.23076923 10.        ]\n",
      "length of F: 14\n"
     ]
    }
   ],
   "source": [
    "F = np.linspace(0, 10, 14) # Returns 14 numbers (floats) from 0 to 10, including 0 and 10.\n",
    "print(\"F:\", F)\n",
    "print(\"length of F:\", len(F))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To summarize: \n",
    "\n",
    "`np.linspace()` creates an array with $N$ evenly spaced elements starting at `start` and including the `end` value, while `np.arange()` creates an array with elements at `step` intervals between `start` up to but NOT including the `end` value.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another trick for creating arrays, is to use the `np.loadtxt()` function, which you encountered in Lecture 6. It reads data file and inserts the result into an array. \n",
    "This example uses a \"relative\" path to define the location of the file. \n",
    "The term relative means the directory structure `Datasets/RecentEarthquakes` is assumed to exist relative to the directory where this notebook resides."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[  66.07 -149.03]\n",
      " [  38.83 -122.8 ]\n",
      " [  32.92 -115.47]\n",
      " [  47.63 -122.51]\n",
      " [  60.97 -151.24]\n",
      " [  37.65 -118.85]\n",
      " [  53.2  -161.3 ]\n",
      " [  19.41 -155.28]\n",
      " [  38.84 -122.83]\n",
      " [  36.88  -89.12]]\n"
     ]
    }
   ],
   "source": [
    "newarray = np.loadtxt('Datasets/RecentEarthquakes/earthquakeLocations.txt')\n",
    "print(newarray)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7.2 A few words about array types\n",
    "\n",
    "In the last example, **NumPy** figured out what array type was required - it decided to make  a floating point array without our having to specify the type.  But what if we wanted an integer array with numbers from 0. to 9. instead?  \n",
    "\n",
    "There are a few solutions to this. First, we could use _integers_ in the `np.arange()` call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.arange(0, 10, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, we could specify the array type with the `dtype` argument, where `dtype` can be for example `int` or `float` (among others)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]\n",
      "[0 1 2 3 4 5 6 7 8 9]\n"
     ]
    }
   ],
   "source": [
    "print(np.arange(0, 10, 1, dtype='float'))\n",
    "print(np.arange(0, 10, 1, dtype='int'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, what is an _object_ array?  That would be an array that allows different data types:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[1, 2, 3],\n",
       "       [4, 2, 0],\n",
       "       ['Xiao Long', 'Jill', 'Jose']], dtype=object)"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.array([[1, 2, 3], [4, 2, 0],['Xiao Long', 'Jill', 'Jose']], dtype='object')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But object arrays have their own limitations, e.g., you can't multiply the array by anything.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, what happens if we define an array without **initializing** it?\n",
    "Let's make a 2x2 array of the `dtype=float`.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0.00000000e+000 1.29074460e-231]\n",
      " [9.88131292e-324 2.78134232e-309]]\n"
     ]
    }
   ],
   "source": [
    "G = np.ndarray(shape=(2,2), dtype=float) \n",
    "print(G)   "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So... the array was initialized with teeny tiny numbers but not necessarily zeros. \n",
    "Uninitialized values in an `ndarray` are literally _garbage_ - these values should never be interpretted, nor should they ever be used to compute anything."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7.3 Array attributes\n",
    "\n",
    "Like other Python objects we have already encountered, arrays also have _attributes_ and _methods_. As before,  _attributes_ do not have parentheses while _methods_ do.  \n",
    "\n",
    "We will start by looking at `ndarray` _attributes_  which report on the state of the array. \n",
    "\n",
    "As an example, we can find out what the data type of an array is with the attribute `ndarray.dtype`:   \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dtype('float64')"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "D.dtype"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you may have already figured out, arrays have dimensions and shape. Dimensions define the number of axes, as in the illustration below. \n",
    "\n",
    "Rember our first array, `A`? It  had two dimensions (axis 0 and 1). We can use the attribute `ndim` to find find this out:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/jpeg": "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S2+d/nrcQnaCx7DPHNfJJ/bJ8Agkf8Id8Rjg4/5E7VP/AIzX1sRkEAkZ7jqK+R2/Zd8WsxY/Hn4njJJ4v9OA59v7PrLW/kXpY9y+GPxO0j4q6Jc69oul65pUFtdNaNFr2mT6VcO6ojlkiuFV2jw4AcDBYEdQa9Hrzf4YfD/Ufh1olzo+p+L9f8Zy3F21yL3xFNDPcxKyIghQwQwKIwULAFSdzNz0A9Iq5WvoSr9TmPGfg3w38QvCuqeCfGFn/aGi6zbvaX1r5kkPmwv95d8TJIufVWB96+LvhB8NfAfwq/bM8XeFvh1odp4f0r/hXOjXBtbNNiNM+o3StI2SSzsqKCxJJwM19peM9U8R6J4V1TVvCGh/8JLrVpbPLY6R9rjsPtsy/di+0zAxxbv77AgV+dun67+2LY/HnWPjUf2dndNV8MWXh0ad/wAJrowaM2dzNced52cHf5u3ZsGNudxzgTSko1k/J3+cJJfi/lcKsXKk15q3ylFv8F87H6cUVk6DeapqGh6df65p/wDZOo3NrDNeWHnLc/ZLh0DSQ+cgCS+W5K71GGxkcGtanKLi2mEZXSaCiiikMKKKKACiiigAooooAKKKKACiiigAooooAKKKKAP/0v38ooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooA//T/fyiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigD/9k=\n",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Image(filename='Figures/ndim.jpg') # Just ignore this - I just want to show you the pretty picture."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The dimensions of A are: 2\n"
     ]
    }
   ],
   "source": [
    "A = np.array([[1, 2, 3], [4, 2, 0], [1, 1, 2]]) # Redeclare A for good measure.\n",
    "print(\"The dimensions of A are:\", A.ndim)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "Notice how `np.zeros()`, `np.ones()` and `np.ndarray()` used a tuple referred to via the keyword `shape` in order to define the arrays in the examples above. The shape of an array tells us how many elements are along each axis. Python returns a tuple with the shape information if we use the `shape` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3, 3)"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7.4 Array methods\n",
    "\n",
    "`ndarray`'s, like `list`, have numerous _methods_ however they are different than the  _methods_ we learned about for lists.  For example, you can append to an array (such a method is defined), but the results may surprise you."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "D:\n",
      " [[0. 0. 0.]\n",
      " [0. 0. 0.]]\n",
      "\n",
      "\n",
      "D after append:\n",
      " [0. 0. 0. 0. 0. 0. 2. 2. 2.]\n"
     ]
    }
   ],
   "source": [
    "print('D:\\n', D) # The \\n denotes a carriage return and starts a new line\n",
    "print('\\n')\n",
    "print('D after append:\\n', np.append(D, [2, 2, 2]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See how we now have a 1-D array?  Not exactly what you expected?  We can deal with that problem by reshaping the array, as we shall see.  But first, you can also **concatenate** arrays which may be a simpler way to extend your array: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0. 0. 0.]\n",
      " [0. 0. 0.]\n",
      " [1. 1. 1.]\n",
      " [1. 1. 1.]]\n"
     ]
    }
   ],
   "source": [
    "print(np.concatenate((D, E)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To solve the shape problem (2-D versus 1-D), you can  re-arrange a 1-D array into a 2-D array (as long as the total number of elements is the same). To do that, we use the `ndarray.reshape()` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "B_real:\n",
      " [0.  0.2 0.4 0.6 0.8 1.  1.2 1.4 1.6 1.8 2.  2.2 2.4 2.6 2.8 3.  3.2 3.4\n",
      " 3.6 3.8 4.  4.2 4.4 4.6 4.8 5.  5.2 5.4 5.6 5.8 6.  6.2 6.4 6.6 6.8 7.\n",
      " 7.2 7.4 7.6 7.8 8.  8.2 8.4 8.6 8.8 9.  9.2 9.4 9.6 9.8]\n",
      "\n",
      "\n",
      "B_real after reshaping:\n",
      " [[0.  0.2 0.4 0.6 0.8 1.  1.2 1.4 1.6 1.8]\n",
      " [2.  2.2 2.4 2.6 2.8 3.  3.2 3.4 3.6 3.8]\n",
      " [4.  4.2 4.4 4.6 4.8 5.  5.2 5.4 5.6 5.8]\n",
      " [6.  6.2 6.4 6.6 6.8 7.  7.2 7.4 7.6 7.8]\n",
      " [8.  8.2 8.4 8.6 8.8 9.  9.2 9.4 9.6 9.8]]\n"
     ]
    }
   ],
   "source": [
    "# We can take a 1-D array with 50 elements and reshape it into, say a 5 X 10 2-D array:\n",
    "B_real_2D = B_real.reshape((5, 10))\n",
    "print('B_real:\\n', B_real)\n",
    "print(\"\\n\")\n",
    "print('B_real after reshaping:\\n', B_real_2D)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can go the other way, by taking a 2-D (or more) array and turning it into one long 1-D array using `ndarray.flatten()`.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0.  0.2 0.4 0.6 0.8 1.  1.2 1.4 1.6 1.8 2.  2.2 2.4 2.6 2.8 3.  3.2 3.4\n",
      " 3.6 3.8 4.  4.2 4.4 4.6 4.8 5.  5.2 5.4 5.6 5.8 6.  6.2 6.4 6.6 6.8 7.\n",
      " 7.2 7.4 7.6 7.8 8.  8.2 8.4 8.6 8.8 9.  9.2 9.4 9.6 9.8]\n"
     ]
    }
   ],
   "source": [
    "B_real_1D = B_real_2D.flatten()\n",
    "print(B_real_1D)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another super useful array method is `ndarray.transpose()` (equivalent to `ndarray.T()`) which swaps rows and columns:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "B_real_2D:\n",
      " [[0.  0.2 0.4 0.6 0.8 1.  1.2 1.4 1.6 1.8]\n",
      " [2.  2.2 2.4 2.6 2.8 3.  3.2 3.4 3.6 3.8]\n",
      " [4.  4.2 4.4 4.6 4.8 5.  5.2 5.4 5.6 5.8]\n",
      " [6.  6.2 6.4 6.6 6.8 7.  7.2 7.4 7.6 7.8]\n",
      " [8.  8.2 8.4 8.6 8.8 9.  9.2 9.4 9.6 9.8]]\n",
      "\n",
      "\n",
      "B_real_2D transposed:\n",
      " [[0.  2.  4.  6.  8. ]\n",
      " [0.2 2.2 4.2 6.2 8.2]\n",
      " [0.4 2.4 4.4 6.4 8.4]\n",
      " [0.6 2.6 4.6 6.6 8.6]\n",
      " [0.8 2.8 4.8 6.8 8.8]\n",
      " [1.  3.  5.  7.  9. ]\n",
      " [1.2 3.2 5.2 7.2 9.2]\n",
      " [1.4 3.4 5.4 7.4 9.4]\n",
      " [1.6 3.6 5.6 7.6 9.6]\n",
      " [1.8 3.8 5.8 7.8 9.8]]\n"
     ]
    }
   ],
   "source": [
    "print('B_real_2D:\\n', B_real_2D)\n",
    "print(\"\\n\")\n",
    "print('B_real_2D transposed:\\n', B_real_2D.transpose())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7.5 Slicing and indexing ndarrays \n",
    "\n",
    "The syntax for slicing an `ndarray` is similar to that for a `list`:  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[1 2 3]\n",
      " [4 2 0]]\n"
     ]
    }
   ],
   "source": [
    "B = A[0:2] # Access the top two rows of A\n",
    "print(B)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7.6 Masking Arrays\n",
    "\n",
    "We can also 'mask' arrays. This is a handy thing a bit like doing an `if` statement for an array. For example, we could make an array of numbers,  say, times, between 0 and 10 minutes and then search just for the times greater than 5 minutes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-03-11T01:42:51.363862Z",
     "start_time": "2020-03-11T01:42:51.345503Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[ 6.  7.  8.  9. 10.]\n"
     ]
    }
   ],
   "source": [
    "time = np.linspace(0, 10, 11)\n",
    "lateTime = time[time > 5.0]\n",
    "print(lateTime)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If two arrays are the same shape, we can use one array to mask another array. For example, we could make an array of distances traveled at a constant speed of 20 miles per hour, and mask to show only the distances for the last 5 minutes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-03-11T01:45:53.159150Z",
     "start_time": "2020-03-11T01:45:53.152847Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[2.         2.33333333 2.66666667 3.         3.33333333]\n"
     ]
    }
   ],
   "source": [
    "distance = time / 3.0\n",
    "lateDistance = distance[time > 5.0]\n",
    "print(lateDistance)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "How does this work? We can peek into this by looking at the result when we print (`time > 5.0`). It turns out that this creates an array of values given by either `True` or `False` which tells the program what elements of the array to choose."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-03-11T01:48:53.391190Z",
     "start_time": "2020-03-11T01:48:53.384706Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[False False False False False False  True  True  True  True  True]\n"
     ]
    }
   ],
   "source": [
    "boolTime = time > 5.0\n",
    "print(boolTime)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "For many more methods and attributes of `ndarray`'s, visit the NumPy Reference website:  http://docs.scipy.org/doc/numpy/reference/.   \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7.7 Converting between data structures\n",
    "\n",
    "We can convert from an `ndarray` to a `list`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Original array: \t <class 'numpy.ndarray'>\n",
      "[[1 2 3]\n",
      " [4 2 0]\n",
      " [1 1 2]]\n",
      "List form: \t\t <class 'list'>\n",
      "[[1, 2, 3], [4, 2, 0], [1, 1, 2]]\n"
     ]
    }
   ],
   "source": [
    "print(\"Original array: \\t\", type(A)) # The '\\t' inserts a tab space character.\n",
    "print(A)\n",
    "\n",
    "L = A.tolist() # Convert ndarray to list.\n",
    "\n",
    "print(\"List form: \\t\\t\", type(L))\n",
    "print(L)\n",
    "# Notice the commas, the array turned into a list of three lists."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To convert a `list` to an `ndarray`, to this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A_from_L:\n",
      "[[1 2 3]\n",
      " [4 2 0]\n",
      " [1 1 2]]\n"
     ]
    }
   ],
   "source": [
    "A_from_L = np.array(L) # From a list\n",
    "print('A_from_L:')\n",
    "print(A_from_L)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or from a `tuple` to an `ndarray`:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A_from_T:\n",
      "[4 2]\n"
     ]
    }
   ],
   "source": [
    "A_from_T = np.array((4, 2)) # From a tuple \n",
    "print('A_from_T:')\n",
    "print(A_from_T)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7.8 Saving NumPy arrays as a text file\n",
    "\n",
    "Having created, sliced and diced an array, it is often handy to save the data to a file for later use. We can do that with the command `np.savetxt()`.\n",
    "\n",
    "Let's save our `A` array to a file called `A.txt`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.savetxt('A.txt', A)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to inspect the contents of the file created, comment the code below and re-run the code cell above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "# And clean up\n",
    "os.remove('A.txt')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### References\n",
    "\n",
    "1. For many more methods and attributes of `ndarray`'s, visit the NumPy Reference website:  https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html.\n",
    "2. Learn about NumPy data types (`dtype` arg) here: https://numpy.org/doc/stable/reference/arrays.dtypes.html"
   ]
  }
 ],
 "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.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}