{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Structured Data: NumPy's Structured Arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While often our data can be well represented by a homogeneous array of values, sometimes this is not the case. This chapter demonstrates the use of NumPy's *structured arrays* and *record arrays*, which provide efficient storage for compound, heterogeneous data.  While the patterns shown here are useful for simple operations, scenarios like this often lend themselves to the use of Pandas ``DataFrame``s, which we'll explore in [Part 3](03.00-Introduction-to-Pandas.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Imagine that we have several categories of data on a number of people (say, name, age, and weight), and we'd like to store these values for use in a Python program.\n",
    "It would be possible to store these in three separate arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "name = ['Alice', 'Bob', 'Cathy', 'Doug']\n",
    "age = [25, 45, 37, 19]\n",
    "weight = [55.0, 85.5, 68.0, 61.5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But this is a bit clumsy. There's nothing here that tells us that the three arrays are related; NumPy's structured arrays allow us to do this more naturally by using a single structure to store all of this data.\n",
    "\n",
    "Recall that previously we created a simple array using an expression like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "x = np.zeros(4, dtype=int)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can similarly create a structured array using a compound data type specification:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[('name', '<U10'), ('age', '<i4'), ('weight', '<f8')]\n"
     ]
    }
   ],
   "source": [
    "# Use a compound data type for structured arrays\n",
    "data = np.zeros(4, dtype={'names':('name', 'age', 'weight'),\n",
    "                          'formats':('U10', 'i4', 'f8')})\n",
    "print(data.dtype)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here `'U10'` translates to \"Unicode string of maximum length 10,\" `'i4'` translates to \"4-byte (i.e., 32-bit) integer,\" and `'f8'` translates to \"8-byte (i.e., 64-bit) float.\"\n",
    "We'll discuss other options for these type codes in the following section.\n",
    "\n",
    "Now that we've created an empty container array, we can fill the array with our lists of values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[('Alice', 25, 55. ) ('Bob', 45, 85.5) ('Cathy', 37, 68. )\n",
      " ('Doug', 19, 61.5)]\n"
     ]
    }
   ],
   "source": [
    "data['name'] = name\n",
    "data['age'] = age\n",
    "data['weight'] = weight\n",
    "print(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we had hoped, the data is now conveniently arranged in one structured array.\n",
    "\n",
    "The handy thing with structured arrays is that we can now refer to values either by index or by name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array(['Alice', 'Bob', 'Cathy', 'Doug'], dtype='<U10')"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get all names\n",
    "data['name']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('Alice', 25, 55.)"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get first row of data\n",
    "data[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Doug'"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get the name from the last row\n",
    "data[-1]['name']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using Boolean masking, we can even do some more sophisticated operations, such as filtering on age:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array(['Alice', 'Doug'], dtype='<U10')"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get names where age is under 30\n",
    "data[data['age'] < 30]['name']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you'd like to do any operations that are any more complicated than these, you should probably consider the Pandas package, covered in [Part 4](04.00-Introduction-To-Matplotlib.ipynb).\n",
    "As you'll see, Pandas provides a `DataFrame` object, which is a structure built on NumPy arrays that offers a variety of useful data manipulation functionality similar to what you've seen here, as well as much, much more."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exploring Structured Array Creation\n",
    "\n",
    "Structured array data types can be specified in a number of ways.\n",
    "Earlier, we saw the dictionary method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dtype([('name', '<U10'), ('age', '<i4'), ('weight', '<f8')])"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.dtype({'names':('name', 'age', 'weight'),\n",
    "          'formats':('U10', 'i4', 'f8')})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For clarity, numerical types can be specified using Python types or NumPy `dtype`s instead:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dtype([('name', '<U10'), ('age', '<i8'), ('weight', '<f4')])"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.dtype({'names':('name', 'age', 'weight'),\n",
    "          'formats':((np.str_, 10), int, np.float32)})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A compound type can also be specified as a list of tuples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dtype([('name', 'S10'), ('age', '<i4'), ('weight', '<f8')])"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.dtype([('name', 'S10'), ('age', 'i4'), ('weight', 'f8')])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the names of the types do not matter to you, you can specify the types alone in a comma-separated string:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dtype([('f0', 'S10'), ('f1', '<i4'), ('f2', '<f8')])"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.dtype('S10,i4,f8')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The shortened string format codes may not be immediately intuitive, but they are built on simple principles.\n",
    "The first (optional) character `<` or `>`, means \"little endian\" or \"big endian,\" respectively, and specifies the ordering convention for significant bits.\n",
    "The next character specifies the type of data: characters, bytes, ints, floating points, and so on (see the table below).\n",
    "The last character or characters represent the size of the object in bytes.\n",
    "\n",
    "| Character    | Description           | Example                           |\n",
    "| ---------    | -----------           | -------                           | \n",
    "| `'b'`        | Byte                  | `np.dtype('b')`                   |\n",
    "| `'i'`        | Signed integer        | `np.dtype('i4') == np.int32`      |\n",
    "| `'u'`        | Unsigned integer      | `np.dtype('u1') == np.uint8`      |\n",
    "| `'f'`        | Floating point        | `np.dtype('f8') == np.int64`      |\n",
    "| `'c'`        | Complex floating point| `np.dtype('c16') == np.complex128`|\n",
    "| `'S'`, `'a'` | String                | `np.dtype('S5')`                  |\n",
    "| `'U'`        | Unicode string        | `np.dtype('U') == np.str_`        |\n",
    "| `'V'`        | Raw data (void)       | `np.dtype('V') == np.void`        |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## More Advanced Compound Types\n",
    "\n",
    "It is possible to define even more advanced compound types.\n",
    "For example, you can create a type where each element contains an array or matrix of values.\n",
    "Here, we'll create a data type with a `mat` component consisting of a $3\\times 3$ floating-point matrix:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(0, [[0., 0., 0.], [0., 0., 0.], [0., 0., 0.]])\n",
      "[[0. 0. 0.]\n",
      " [0. 0. 0.]\n",
      " [0. 0. 0.]]\n"
     ]
    }
   ],
   "source": [
    "tp = np.dtype([('id', 'i8'), ('mat', 'f8', (3, 3))])\n",
    "X = np.zeros(1, dtype=tp)\n",
    "print(X[0])\n",
    "print(X['mat'][0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now each element in the `X` array consists of an `id` and a $3\\times 3$ matrix.\n",
    "Why would you use this rather than a simple multidimensional array, or perhaps a Python dictionary?\n",
    "One reason is that this NumPy `dtype` directly maps onto a C structure definition, so the buffer containing the array content can be accessed directly within an appropriately written C program.\n",
    "If you find yourself writing a Python interface to a legacy C or Fortran library that manipulates structured data, structured arrays can provide a powerful interface."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Record Arrays: Structured Arrays with a Twist\n",
    "\n",
    "NumPy also provides record arrays (instances of the `np.recarray` class), which are almost identical to the structured arrays just described, but with one additional feature: fields can be accessed as attributes rather than as dictionary keys.\n",
    "Recall that we previously accessed the ages in our sample dataset by writing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([25, 45, 37, 19], dtype=int32)"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data['age']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we view our data as a record array instead, we can access this with slightly fewer keystrokes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([25, 45, 37, 19], dtype=int32)"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data_rec = data.view(np.recarray)\n",
    "data_rec.age"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The downside is that for record arrays, there is some extra overhead involved in accessing the fields, even when using the same syntax:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "121 ns ± 1.4 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)\n",
      "2.41 µs ± 15.7 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)\n",
      "3.98 µs ± 20.5 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%timeit data['age']\n",
    "%timeit data_rec['age']\n",
    "%timeit data_rec.age"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Whether the more convenient notation is worth the (slight) overhead will depend on your own application."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## On to Pandas\n",
    "\n",
    "This chapter on structured and record arrays is purposely located at the end of this part of the book, because it leads so well into the next package we will cover: Pandas.\n",
    "Structured arrays can come in handy in certain situations, like when you're using NumPy arrays to map onto binary data formats in C, Fortran, or another language.\n",
    "But for day-to-day use of structured data, the Pandas package is a much better choice; we'll explore it in depth in the chapters that follow."
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "jupytext": {
   "formats": "ipynb,md"
  },
  "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.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}