04_numpy.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Numpy\n",
    "\n",
    "\n",
    "This section introduces you to [`numpy`](http://www.numpy.org/), Python's\n",
    "numerical computing library.\n",
    "\n",
    "\n",
    "Numpy is not actually part of the standard Python library. But it is a\n",
    "fundamental part of the Python ecosystem - it forms the basis for many\n",
    "important Python libraries, and it (along with its partners\n",
    "[`scipy`](https://www.scipy.org/), [`matplotlib`](https://matplotlib.org/) and\n",
    "[`pandas`](https://pandas.pydata.org/)) is what makes Python an attractive\n",
    "alternative to Matlab as a scientific computing platform.\n",
    "\n",
    "\n",
    "The `fslpython` environment currently includes [Numpy\n",
    "1.11.1](https://docs.scipy.org/doc/numpy-1.11.0/index.html), which is a little\n",
    "out of date, but we will update it for the next release of FSL.\n",
    "\n",
    "\n",
    "## Contents\n",
    "\n",
    "\n",
    "* [The Python list versus the Numpy array](#the-python-list-versus-the-numpy-array)\n",
    "* [Numpy basics](#numpy-basics)\n",
    " * [Creating arrays](#creating-arrays)\n",
    " * [Loading text files](#loading-text-files)\n",
    " * [Array properties](#array-properties)\n",
    " * [Descriptive statistics](#descriptive-statistics)\n",
    " * [Reshaping and rearranging arrays](#reshaping-and-rearranging-arrays)\n",
    "* [Operating on arrays](#operating-on-arrays)\n",
    " * [Scalar operations](#scalar-operations)\n",
    " * [Multi-variate operations](#multi-variate-operations)\n",
    " * [Matrix multplication](#matrix-multiplication)\n",
    " * [Broadcasting](#broadcasting)\n",
    " * [Linear algebra](#linear-algebra)\n",
    "* [Array indexing](#array-indexing)\n",
    " * [Indexing multi-dimensional arrays](#indexing-multi-dimensional-arrays)\n",
    " * [Boolean indexing](#boolean-indexing)\n",
    " * [Coordinate array indexing](#coordinate-array-indexing)\n",
    "* [Exercises](#exercises)\n",
    " * [Load an array from a file and do stuff with it](#load-an-array-from-a-file-and-do-stuff-with-it)\n",
    " * [Concatenate affine transforms](#concatenate-affine-transforms)\n",
    "\n",
    "* [Appendix A: Generating random numbers](#appendix-generating-random-numbers)\n",
    "* [Appendix B: Importing Numpy](#appendix-importing-numpy)\n",
    "* [Appendix C: Vectors in Numpy](#appendix-vectors-in-numpy)\n",
    "\n",
    "* [Useful references](#useful-references)\n",
    "\n",
    "\n",
    "<a class=\"anchor\" id=\"the-python-list-versus-the-numpy-array\"></a>\n",
    "## The Python list versus the Numpy array\n",
    "\n",
    "\n",
    "Numpy adds a new data type to the Python language - the `array` (more\n",
    "specifically, the `ndarray`). A Numpy `array` is a N-dimensional array of\n",
    "homogeneously-typed numerical data.\n",
    "\n",
    "\n",
    "You have already been introduced to the Python `list`, which you can easily\n",
    "use to store a handful of numbers (or anything else):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = [10, 8, 12, 14, 7, 6, 11]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You could also emulate a 2D or ND matrix by using lists of lists, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "xyz_coords = [[-11.4,   1.0,  22.6],\n",
    "              [ 22.7, -32.8,  19.1],\n",
    "              [ 62.8, -18.2, -34.5]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For simple tasks, you could stick with processing your data using python\n",
    "lists, and the built-in\n",
    "[`math`](https://docs.python.org/3.5/library/math.html) library. And this\n",
    "might be tempting, because it does look quite a lot like what you might type\n",
    "into Matlab.\n",
    "\n",
    "\n",
    "But __BEWARE!__ A Python list is a terrible data structure for scientific\n",
    "computing!\n",
    "\n",
    "\n",
    "This is a major source of confusion for people who are learning Python, and\n",
    "are trying to write efficient code. It is _crucial_ to be able to distinguish\n",
    "between a Python list and a Numpy array.\n",
    "\n",
    "\n",
    "___Python list == Matlab cell array:___ A list in Python is akin to a cell\n",
    "array in Matlab - they can store anything, but are extremely inefficient, and\n",
    "unwieldy when you have more than a couple of dimensions.\n",
    "\n",
    "\n",
    "___Numy array == Matlab matrix:___ These are in contrast to the Numpy array\n",
    "and Matlab matrix, which are both thin wrappers around a contiguous chunk of\n",
    "memory, and which provide blazing-fast performance (because behind the scenes\n",
    "in both Numpy and Matlab, it's C, C++ and FORTRAN all the way down).\n",
    "\n",
    "\n",
    "So you should strongly consider turning those lists into Numpy arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "data = np.array([10, 8, 12, 14, 7, 6, 11])\n",
    "\n",
    "xyz_coords = np.array([[-11.4,   1.0,  22.6],\n",
    "                       [ 22.7, -32.8,  19.1],\n",
    "                       [ 62.8, -18.2, -34.5]])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you look carefully at the code above, you will notice that we are still\n",
    "actually using Python lists. We have declared our data sets in exactly the\n",
    "same way as we did earlier, by denoting them with square brackets `[` and `]`.\n",
    "\n",
    "\n",
    "The key difference here is that these lists immediately get converted into\n",
    "Numpy arrays, by passing them to the `np.array` function.  To clarify this\n",
    "point, we could rewrite this code in the following equivalent manner:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "# Define our data sets as python lists\n",
    "data       = [10, 8, 12, 14, 7, 6, 11]\n",
    "xyz_coords = [[-11.4,   1.0,  22.6],\n",
    "              [ 22.7, -32.8,  19.1],\n",
    "              [ 62.8, -18.2, -34.5]]\n",
    "\n",
    "# Convert them to numpy arrays\n",
    "data       = np.array(data)\n",
    "xyz_coords = np.array(xyz_coords)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course, in practice, we would never create a Numpy array in this way - we\n",
    "will be loading our data from text or binary files directly into a Numpy\n",
    "array, thus completely bypassing the use of Python lists and the costly\n",
    "list-to-array conversion.  I'm emphasising this to help you understand the\n",
    "difference between Python lists and Numpy arrays. Apologies if you've already\n",
    "got it, forgiveness please.\n",
    "\n",
    "\n",
    "<a class=\"anchor\" id=\"numpy-basics\"></a>\n",
    "## Numpy basics\n",
    "\n",
    "\n",
    "Let's get started."
   ]
  },
  {
   "cell_type": "code",