01 - Numpy - The essentials.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's start by importing numpy and checking our version (yours may be a little different -- that's ok)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "print(np.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create first array\n",
    "\n",
    "The simplest way to create a small array (*ndarray* or just *array* in numpy terminology) is to specify the values in a list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = np.array([1,2,3,4])  # 1-d array\n",
    "print(a)\n",
    "\n",
    "b = np.array([[1,2],[3,4]])  # 2-d array\n",
    "print(b)\n",
    "\n",
    "c = np.array([[1,2],[3,4]], dtype=np.float64)  # 2-d array of a given 'data-type'\n",
    "print(c)\n",
    "\n",
    "# The outputs in the notebook may look like list, but they aren't lists\n",
    "print(type(c))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Common ways to initialize ndarrays\n",
    "\n",
    "Other than specifying the values explicitly like above (which is rarely practical), we can initialise an ndarray of a given **shape** in several ways:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create an array of 0s\n",
    "a = np.zeros((3, 2))\n",
    "\n",
    "# Create an array of 1s\n",
    "b = np.ones((2, 3))\n",
    "\n",
    "# Create an uninitialized array of random values\n",
    "c = np.empty((2, 2))\n",
    "\n",
    "# Create a 1D array of values from 0 to n-1 (like Python's range function)\n",
    "d = np.arange(10)\n",
    "\n",
    "# Create a range of N evenly-spaced values from 0 to n\n",
    "e = np.linspace(0, 10, 5)\n",
    "\n",
    "# Create an identity matrix\n",
    "f = np.eye(4)  # Square, so we only need to specify the no. of rows\n",
    "\n",
    "# Create an array of uniformly distributed random numbers in [0, 1)\n",
    "g = np.random.random((2, 3))\n",
    "\n",
    "print('np.zeros((3,2))       = \\n%s\\n' % np.zeros((3,2)))\n",
    "print('np.ones((2,3))        = \\n%s\\n' % np.ones((2,3)))\n",
    "print('np.empty((2,3))       = \\n%s\\n' % np.empty((2,3)))\n",
    "print('np.arange(5)          = \\n%s\\n' % np.arange(5))\n",
    "print('np.linspace(0,10,5)   = \\n%s\\n' % np.linspace(0,10,5))\n",
    "print('np.eye(4)             = \\n%s\\n' % np.eye(4))\n",
    "print('np.random.random(3,4) = \\n%s\\n' % np.random.random((3,4)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# A 2x2 array of random numbers from a normal distribution with mean=0 and std=1\n",
    "print('np.random.randn(2,2)  = \\n%s\\n' % np.random.randn((2,2)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Oops - what happened? Let's take a quick peek at the documentation - https://numpy.org/doc/stable/\n",
    "\n",
    "Notice the slight difference in how we're supposed to call `ones` and `rand`.\n",
    "\n",
    "In general, when specifying the shape of an array, the general rule of thumb is to specify a tuple of integers (referred to as the *shape* or *size* parameter in the documentation)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Useful attributes for inspecting an ndarray"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# VERY helpful to see the 'shape' of an ndarray to make sure you have what you expect.\n",
    "# This is what most professional programmers rely on for debugging purposes.\n",
    "a = np.array([[1, 0, 1], [0, 1, 0]])\n",
    "print(a.shape)\n",
    "# We will keep inspecting the shape of arrays regularly to maintain sanity!\n",
    "\n",
    "# No. of dimensions of an ndarray\n",
    "# This is also called 'rank' of the ndarray in the numpy world\n",
    "# (Not to be confused with the 'rank' of a matrix which is a concept in linear algebra)\n",
    "print(a.ndim)\n",
    "\n",
    "# Total no. of elements in an ndarray - product of shape values\n",
    "print(a.size)\n",
    "\n",
    "# The data-type of an ndarray\n",
    "print(a.dtype)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Arrays have an attribute `ndim` that reflects the dimension.  In Numpy, each dimension is called an **axis** (starting with axis-0, then axis-1), and they indicate the direction you're *moving along*.\n",
    "\n",
    "![np1d](images/np1d.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![np2d](images/np2d.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![np3d](images/np3d.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For 3D arrays, it's useful to picture axis0 as **tabs on a spreadsheet**\n",
    "\n",
    "```\n",
    "   |      -- axis2 -->\n",
    "   |    |\n",
    "   |  axis1  [0, 1]\n",
    "   |    |    [2, 3]\n",
    "   |    V\n",
    "axis0\n",
    "   |      -- axis2 -->\n",
    "   |    |\n",
    "   |  axis1  [4, 5]\n",
    "   |    |    [6, 7]\n",
    "   V    V\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### dtypes\n",
    "\n",
    "Unlike lists, Numpy arrays *MUST* have elements that are all of the same type.  The type is reflected in an array attribute `dtype`. Most common data types are supported by Numpy. For a complete list, see [Numpy Data Types](https://numpy.org/doc/stable/user/basics.types.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = np.array([[1,2,3],[4,5,6]], dtype=np.int8)\n",
    "b = np.array([[1,2,3],[4,5,6]], dtype=np.float64)\n",
    "print(a.dtype)\n",
    "print(b.dtype)\n",
    "\n",
    "c = a.astype(np.float32)\n",
    "print(c.dtype)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reshape as a quick way to create n-dimensional arrays"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = np.arange(300)\n",
    "print(a.shape)\n",
    "\n",
    "b = a.reshape(30, 10)\n",
    "print(b.shape)\n",
    "\n",
    "c = a.reshape(30, 5, 2)\n",
    "print(c.shape)\n",
    "\n",
    "# Use -1 to auto-calculate\n",
    "d = a.reshape(3, 10, 2, -1)\n",
    "print(d.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Vectorized operations with arrays\n",
    "\n",
    "Basic arithmetic operations on arrays (+, -, x, /, exponentiation, modular arithmetic) are performed *elementwise*.  The lingo for this is to say that array operations are **vectorized** (that just means they work elementwise by default).\n",
    "\n",
    "So for instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "arr01 = np.array([5,6,7,8,9,10])\n",
    "arr02 = np.array([15,26,37,48,59,60])\n",
    "print(arr01 + arr02)\n",
    "print(arr01 - arr02)\n",
    "print(arr01 * arr02)\n",
    "# You get the picture"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Right now we'll only look at vectorized operations on arrays of the same shape. In the next notebook we'll see how these operations work on arrays of different shapes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise 1\n",
    "\n",
    "Given `n`, create two `n x n` matrices `A` and `B` of random values and verify the following mathematical identity:\n",
    "\n",
    "$$\n",
    "    (A + B)^{T} = A^{T} + B^{T}\n",
    "$$\n",
    "\n",
    "Numpy Functions that might come in handy here are `np.random.random` and `np.allclose`. Also, remember that ndarrays have a `transpose()` *method*, or a `T` *property* that returns the transpose.\n",
    "\n",
    "(https://numpy.org/doc/stable/)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ----------------------- #\n",
    "# COMPLETE THIS CODE\n",
    "# ----------------------- #"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Accessing elements\n",
    "In native Python, the indexing operator, the brackets **[]**, select items from a container. This is most commonly done in tuples, lists and dictionaries. ndarrays use the same operator for selection. \n",
    "\n",
    "For the following examples we'll use the following random 10x5 array of floats."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.random.seed(123)\n",
    "array = np.random.randn(10, 5)\n",
    "array = array.round(2)\n",
    "array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# To select a single element simply place the index of the row and column\n",
    "# inside the brackets separated by a comma.\n",
    "# Select the element at 4th row, 3rd column\n",
    "\n",
    "# Get in the habit of counting from 0 - 0th row, 1st row .. etc\n",
    "array[4, 3]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# select all the rows of the 4th column\n",
    "array[:, 4]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Use slice notation to select a block of data\n",
    "array[5:10, 2:5]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# start:stop:step notation\n",
    "array[3:10:5, ::2]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Slicing doesn't copy - we're only \"viewing\" a window to our original data\n",
    "np.shares_memory(array[5:10, :], array)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Slices (or regular indexing) can appear on the LHS of assignments\n",
    "# allowing us to change the underlying data across all arrays!\n",
    "# THIS IS THE SOURCE OF MANY MANY BUGS! BE CAREFUL!\n",
    "array[1:3, 2:4] = 0\n",
    "print(array)\n",
    "\n",
    "# Wait - how did numpy do the intuitive thing even though the RHS was a scalar?\n",
    "# Broadcasting! We'll come back to that."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Underlying memory layout of a 2D array\n",
    "\n",
    "### Row Major (or 'C' ordering)\n",
    "![row_major](images/row-major-2D.png)\n",
    "\n",
    "Matlab/R/Julia use column-major (or 'Fortran' ordering)\n",
    "![column_major](images/column-major-2D.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "A = np.arange(12)  #1D\n",
    "print(A)\n",
    "\n",
    "A4x3 = A.reshape(4, 3)  #2D, in row-major order ('C' order) by default\n",
    "print(A4x3)\n",
    "\n",
    "A4x3F = A.reshape(4, 3, order='F') #2D, column-major like Fortran\n",
    "print(A4x3F)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Crucially, *all three of these arrays share the same underlying data!*  Here are some ways to do the object introspection to prove it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(A.flags)  # A \"owns\" the data...\n",
    "\n",
    "# But none of the others do\n",
    "print(A4x3.flags)\n",
    "print(A4x3.flags['OWNDATA'])  # for brevity\n",
    "print(A4x3F.flags)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![array_attributes](images/array_attributes.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# .base attribute is None if you own your data\n",
    "print(A.base)\n",
    "print(A4x3.base)\n",
    "A4x3.base is A4x3F.base  # These two share a common base"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Another way to tell if two arrays share any memory\n",
    "np.shares_memory(A, A4x3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This is all in bytes\n",
    "# strides = \"How much do we need to move to get to the next element on each axis?\"\n",
    "print(A.strides)\n",
    "print(A4x3.strides)\n",
    "print(A4x3F.strides)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So a reshape is essentially instantaneous, a non-operation or \"no-op\".  All it does is change your *view* of the data."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise 2\n",
    "\n",
    "Validate that the following operations work copy-free."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Arow = A.reshape(1, 12)\n",
    "print(Arow, Arow.ndim)\n",
    "\n",
    "Acol = A.reshape(12, 1)\n",
    "print(Acol, Acol.ndim)\n",
    "\n",
    "print(A4x3.ravel())     # Makes array 1D\n",
    "print(Acol.squeeze())   # Eliminates any axes of length 1\n",
    "print(A4x3.T)           # Transpose\n",
    "print(A.view(np.int32)) # Reinterpret the bytes as 32-bit integers rather than 64-bit\n",
    "\n",
    "# ----------------------- #\n",
    "# COMPLETE THIS CODE\n",
    "# ----------------------- #"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Incidentally, you can always make a copy using an array's `.copy()` method.  Just be mindful of your memory budget."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "A2 = A.copy()\n",
    "np.shares_memory(A2,A)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What does row-major mean for higher-dimensional arrays?\n",
    "\n",
    "For >2 dimensions, our notation of *row* and *column* breaks down. But remember the following statement (Python programmers end up repeating this in their head many times a day!)\n",
    "\n",
    "**In row-major layout of multi-dimensional arrays, the last index is the fastest changing**\n",
    "\n",
    "### Exercise 3\n",
    "\n",
    "Create a 3-d array that \"looks\" like the following. Print the values of the 3 faces you see here to verify you did this correctly.\n",
    "\n",
    "![np3d](images/np3d.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ----------------------- #\n",
    "# COMPLETE THIS CODE\n",
    "# ----------------------- #"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Some more ways of assembling N-dimensional arrays"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = np.arange(6)\n",
    "print(a)\n",
    "print(a.shape)\n",
    "\n",
    "# Horizontal stack\n",
    "b = np.hstack([a, a])\n",
    "print(b)\n",
    "print(b.shape)\n",
    "\n",
    "# Vertical stack\n",
    "c = np.vstack([a, a])\n",
    "print(c)\n",
    "print(c.shape)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add a new dimension at the end\n",
    "d = c[:, :, np.newaxis]\n",
    "print(d.shape)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Depth stack\n",
    "e = np.dstack([d, d])\n",
    "print(e.shape)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}