numpy/02.08-Sorting.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--BOOK_INFORMATION-->\n",
    "<img align=\"left\" style=\"padding-right:10px;\" src=\"figures/PDSH-cover-small.png\">\n",
    "*This notebook contains an excerpt from the [Python Data Science Handbook](http://shop.oreilly.com/product/0636920034919.do) by Jake VanderPlas; the content is available [on GitHub](https://github.com/jakevdp/PythonDataScienceHandbook).*\n",
    "\n",
    "*The text is released under the [CC-BY-NC-ND license](https://creativecommons.org/licenses/by-nc-nd/3.0/us/legalcode), and code is released under the [MIT license](https://opensource.org/licenses/MIT). If you find this content useful, please consider supporting the work by [buying the book](http://shop.oreilly.com/product/0636920034919.do)!*\n",
    "\n",
    "*No changes were made to the contents of this notebook from the original.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "< [Fancy Indexing](02.07-Fancy-Indexing.ipynb) | [Contents](Index.ipynb) | [Structured Data: NumPy's Structured Arrays](02.09-Structured-Data-NumPy.ipynb) >"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Sorting Arrays"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Up to this point we have been concerned mainly with tools to access and operate on array data with NumPy.\n",
    "This section covers algorithms related to sorting values in NumPy arrays.\n",
    "These algorithms are a favorite topic in introductory computer science courses: if you've ever taken one, you probably have had dreams (or, depending on your temperament, nightmares) about *insertion sorts*, *selection sorts*, *merge sorts*, *quick sorts*, *bubble sorts*, and many, many more.\n",
    "All are means of accomplishing a similar task: sorting the values in a list or array.\n",
    "\n",
    "For example, a simple *selection sort* repeatedly finds the minimum value from a list, and makes swaps until the list is sorted. We can code this in just a few lines of Python:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "def selection_sort(x):\n",
    "    for i in range(len(x)):\n",
    "        swap = i + np.argmin(x[i:])\n",
    "        (x[i], x[swap]) = (x[swap], x[i])\n",
    "    return x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3, 4, 5])"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = np.array([2, 1, 4, 3, 5])\n",
    "selection_sort(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As any first-year computer science major will tell you, the selection sort is useful for its simplicity, but is much too slow to be useful for larger arrays.\n",
    "For a list of $N$ values, it requires $N$ loops, each of which does on order $\\sim N$ comparisons to find the swap value.\n",
    "In terms of the \"big-O\" notation often used to characterize these algorithms (see [Big-O Notation](#Aside:-Big-O-Notation)), selection sort averages $\\mathcal{O}[N^2]$: if you double the number of items in the list, the execution time will go up by about a factor of four.\n",
    "\n",
    "Even selection sort, though, is much better than my all-time favorite sorting algorithms, the *bogosort*:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def bogosort(x):\n",
    "    while np.any(x[:-1] > x[1:]):\n",
    "        np.random.shuffle(x)\n",
    "    return x"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3, 4, 5])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = np.array([2, 1, 4, 3, 5])\n",
    "bogosort(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This silly sorting method relies on pure chance: it repeatedly applies a random shuffling of the array until the result happens to be sorted.\n",
    "With an average scaling of $\\mathcal{O}[N \\times N!]$, (that's *N* times *N* factorial) this should–quite obviously–never be used for any real computation.\n",
    "\n",
    "Fortunately, Python contains built-in sorting algorithms that are *much* more efficient than either of the simplistic algorithms just shown. We'll start by looking at the Python built-ins, and then take a look at the routines included in NumPy and optimized for NumPy arrays."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Fast Sorting in NumPy: ``np.sort`` and ``np.argsort``\n",
    "\n",
    "Although Python has built-in ``sort`` and ``sorted`` functions to work with lists, we won't discuss them here because NumPy's ``np.sort`` function turns out to be much more efficient and useful for our purposes.\n",
    "By default ``np.sort`` uses an $\\mathcal{O}[N\\log N]$, *quicksort* algorithm, though *mergesort* and *heapsort* are also available. For most applications, the default quicksort is more than sufficient.\n",
    "\n",
    "To return a sorted version of the array without modifying the input, you can use ``np.sort``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3, 4, 5])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = np.array([2, 1, 4, 3, 5])\n",
    "np.sort(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you prefer to sort the array in-place, you can instead use the ``sort`` method of arrays:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1 2 3 4 5]\n"
     ]
    }
   ],
   "source": [
    "x.sort()\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A related function is ``argsort``, which instead returns the *indices* of the sorted elements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1 0 3 2 4]\n"
     ]
    }
   ],
   "source": [
    "x = np.array([2, 1, 4, 3, 5])\n",
    "i = np.argsort(x)\n",
    "print(i)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first element of this result gives the index of the smallest element, the second value gives the index of the second smallest, and so on.\n",
    "These indices can then be used (via fancy indexing) to construct the sorted array if desired:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3, 4, 5])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x[i]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sorting along rows or columns"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A useful feature of NumPy's sorting algorithms is the ability to sort along specific rows or columns of a multidimensional array using the ``axis`` argument. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[6 3 7 4 6 9]\n",
      " [2 6 7 4 3 7]\n",
      " [7 2 5 4 1 7]\n",
      " [5 1 4 0 9 5]]\n"
     ]
    }
   ],
   "source": [
    "rand = np.random.RandomState(42)\n",
    "X = rand.randint(0, 10, (4, 6))\n",
    "print(X)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[2, 1, 4, 0, 1, 5],\n",
       "       [5, 2, 5, 4, 3, 7],\n",
       "       [6, 3, 7, 4, 6, 7],\n",
       "       [7, 6, 7, 4, 9, 9]])"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# sort each column of X\n",
    "np.sort(X, axis=0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[3, 4, 6, 6, 7, 9],\n",
       "       [2, 3, 4, 6, 7, 7],\n",
       "       [1, 2, 4, 5, 7, 7],\n",
       "       [0, 1, 4, 5, 5, 9]])"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# sort each row of X\n",
    "np.sort(X, axis=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keep in mind that this treats each row or column as an independent array, and any relationships between the row or column values will be lost!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Partial Sorts: Partitioning\n",
    "\n",
    "Sometimes we're not interested in sorting the entire array, but simply want to find the *k* smallest values in the array. NumPy provides this in the ``np.partition`` function. ``np.partition`` takes an array and a number *K*; the result is a new array with the smallest *K* values to the left of the partition, and the remaining values to the right, in arbitrary order:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([2, 1, 3, 4, 6, 5, 7])"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = np.array([7, 2, 3, 1, 6, 5, 4])\n",
    "np.partition(x, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the first three values in the resulting array are the three smallest in the array, and the remaining array positions contain the remaining values.\n",
    "Within the two partitions, the elements have arbitrary order.\n",
    "\n",
    "Similarly to sorting, we can partition along an arbitrary axis of a multidimensional array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[3, 4, 6, 7, 6, 9],\n",
       "       [2, 3, 4, 7, 6, 7],\n",
       "       [1, 2, 4, 5, 7, 7],\n",
       "       [0, 1, 4, 5, 9, 5]])"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.partition(X, 2, axis=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result is an array where the first two slots in each row contain the smallest values from that row, with the remaining values filling the remaining slots.\n",
    "\n",
    "Finally, just as there is a ``np.argsort`` that computes indices of the sort, there is a ``np.argpartition`` that computes indices of the partition.\n",
    "We'll see this in action in the following section."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example: k-Nearest Neighbors\n",
    "\n",
    "Let's quickly see how we might use this ``argsort`` function along multiple axes to find the nearest neighbors of each point in a set.\n",
    "We'll start by creating a random set of 10 points on a two-dimensional plane.\n",
    "Using the standard convention, we'll arrange these in a $10\\times 2$ array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "X = rand.rand(10, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get an idea of how these points look, let's quickly scatter plot them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAe4AAAFVCAYAAAApGgzgAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAHWtJREFUeJzt3W9wVOXd//HPQliWZTdQanzQTggoRFpwUiFqBaOd6Wb0\n1swosIkBJhlHRx2nsZ0BO5aZKnGmTJAOfWBj+qA2piASJOS+q1uqndwgM02dmyRj0OAvsWOdyLRP\nMlaz+bObP+T8HgAL4U+ynOyfXHveryftnuvK5vt1dT/nnCvnHJdlWZYAAIAR5qS7AAAAED+CGwAA\ngxDcAAAYhOAGAMAgBDcAAAYhuAEAMMiMgvv06dOqqKi4ansoFFJZWZm2bt2q6urqmfwKAABwGdvB\n/frrr+uXv/ylxsbGJm0fGRnRq6++qjfffFNvvfWWBgYGdOLEiRkXCgAAZhDceXl5eu21167a7na7\n1djYKLfbLUkaHx/X/Pnz7VcIAABibAd3cXGx5s6de9V2l8ulJUuWSJIOHDigSCSi9evX268QAADE\nZCXjTS3L0t69e9Xb26va2tq4f8blciWjHAAAMsaMg/tatzp/8cUX5fF4VFdXF/f7uFwu9fUNzLQc\nY+Xk+Onfof07uXeJ/unfuf3n5Pht/dyMg/viUXIoFFIkEtHq1avV3NysdevWqaKiQi6XS5WVlQoE\nAjP9VQAAON6Mgvu73/2uGhsbJUklJSWx7Z9++unMqgIAANfEDVgAADAIwQ0AgEEIbgAADEJwAwBg\nEIIbAACDENwAABiE4AYAwCAENwAABiG4AQAwCMENAIBBCG4AAAxCcAMAYBCCGwAAgxDcAAAYhOAG\nAMAgBDcAAAYhuAEAMAjBDQCAQQhuAAAMQnADAGAQghsAAIMQ3AAAGITgBgDAIAQ3AAAGIbgBADAI\nwQ0AgEEIbgAADEJwAwBgEIIbAACDENwAABiE4AYAwCAENwAABiG4AQAwCMENAIBBCG4AAAxCcAMA\nYJAZBffp06dVUVFx1fbjx48rGAyqvLxcR44cmcmvAAAAl8my+4Ovv/66/vSnP2nhwoWTto+Pj2vP\nnj1qbm7W/PnztWXLFv34xz/WkiVLZlwsAABOZ/uIOy8vT6+99tpV2z///HPl5eXJ5/Np3rx5Wrdu\nndra2mZUJAAAOM92cBcXF2vu3LlXbR8cHJTf74+9XrhwoQYGBuz+GgAAcBnbp8qvx+fzaXBwMPZ6\naGhI2dnZcf1sTo5/+kkZ7Eb7//vfP9Fbb32ub76Zq0WLxrVt2wqtX397kqpLPid//k7uXaJ/+nd2\n/zdqxsFtWdak17feeqt6e3sVDofl8XjU1tamJ598Mq736utz7pF5To4/7v6Hh4dVVRVSS8sGRaOP\nxrbX13crEPiDamtL5PV6k1VqUtxI/5nGyb1L9E//zu3f7g7LjIPb5XJJkkKhkCKRiEpLS7Vz5049\n8cQTsixLpaWluvnmm2f6a3CZqqqQQqHHJU1eqohGVykUWimpQfX1ZekoDQCQZC7rykPmNHLqXpcU\n/17nqVNdCgaXKBq97bpzPJ5uNTd/o8LC1YksMamcvtft1N4l+qd/5/Zv94ibG7AYprn57JShLZ0/\n8m5q6k1RRQCAVCK4DdPfH9/qRjg8L8mVAADSgeA2zKJF43HNy84eS3IlAIB0ILgNs2lTrjye7inn\neDzdCgbzUlQRACCVCG7D3HXXGgUCrZLOXWfGOQUCrUb9YRoAIH4JvwELkq+2tkRSw4XruFfFtns8\n3QoEWi+MAwAyEcFtIK/Xq/r6MrW3n1FT02GFw/OUnT2qYHCZCgu5fhsAMhnBbbDCwtWcEgcAh2GN\nGwAAgxDcAAAYhOAGAMAgBDcAAAYhuAEAMAjBDQCAQQhuAAAMQnADAGAQghsAAIMQ3AAAGITgBgDA\nIAQ3AAAGIbgBADAIwQ0AgEEIbgAADEJwAwBgEIIbAACDENwAABiE4AYAwCAENwAABiG4AQAwCMEN\nAIBBCG4AAAxCcAMAYBCCGwAAgxDcAAAYhOAGAMAgBDcAAAaxFdyWZWnXrl0qLy9XZWWlzp49O2n8\nnXfe0aZNm1RaWqpDhw4lpFAAACBl2fmhlpYWjY6OqrGxUadPn1ZNTY3q6upi43v37tVf/vIXeTwe\nPfzwwyopKZHf709Y0QAAOJWt4O7o6FBRUZEkqaCgQF1dXZPGV61apf7+frlcLkmK/S8AAJgZW8E9\nODg46Qg6KytLExMTmjPn/Jn3lStXavPmzfJ6vSouLpbP50tMtQAAOJyt4Pb5fBoaGoq9vjy0e3p6\n9MEHH+j48ePyer16/vnn9f777+uBBx6Y9n1zcpx9Op3+ndu/k3uX6J/+nd3/jbIV3GvXrtWJEyf0\n4IMPqrOzU/n5+bExv9+vBQsWyO12y+VyacmSJQqHw3G9b1/fgJ1yMkJOjp/+Hdq/k3uX6J/+ndu/\n3R0WW8FdXFys1tZWlZeXS5JqamoUCoUUiURUWlqqsrIybd26VW63W0uXLtXGjRttFQcAACZzWZZl\npbuIi5y61yU5e69Tcnb/Tu5don/6d27/do+4uQELAAAGIbgBADAIwQ0AgEEIbgAADEJwAwBgEIIb\nAACDENwAABiE4AYAwCAENwAABiG4AQAwCMENAIBBCG4AAAxCcAMAYBCCGwAAgxDcAAAYhOAGAMAg\nBDcAAAbJSncBAICZaWs7o6NHv1R/f5ays8cUDObpzjtXp7ssJAnBDQCGGh4eVlVVSC0tGxSN/jC2\n/dChbgUCb6u2tkRerzeNFSIZCG4AMFRVVUih0OOS5k7aHo2uUii0UlKD6uvL0lEakog1bgAw0KlT\nXWppuVdXhvYlc9XSskHt7WdSWRZSgOAGAAM1N59VNHrblHOi0VVqaupNUUVIFYIbAAzU3x/fSmc4\nPC/JlSDVCG4AMNCiReNxzcvOHktyJUg1ghsADLRpU648nu4p53g83QoG81JUEVKF4AYAA9111xoF\nAq2Szl1nxjkFAq0qLOR67kzD5WAAYKja2hJJDReu414V2+7xdCsQaL0wjkxDcAOAobxer+rry9Te\nfkZNTYcVDs9TdvaogsFlKizk+u1MRXADgOEKC1dzStxBWOMGAMAgBDcAAAYhuAEAMAjBDQCAQQhu\nAAAMQnADAGAQghsAAIPYuo7bsixVV1erp6dHbrdbu3fvVm5ubmz8448/1iuvvCJJuummm/TrX/9a\nbrc7MRUDAOBgto64W1paNDo6qsbGRu3YsUM1NTWTxl966SXt2bNHBw8eVFFRkf79738npFgAAJzO\n1hF3R0eHioqKJEkFBQXq6uqKjX3xxRdavHix3njjDf3jH//Qj370Iy1btiwhxQIA4HS2gntwcFB+\nv//Sm2RlaWJiQnPmzNHXX3+tzs5O7dq1S7m5uXrmmWe0Zs0a3X333dO+b06Of9o5mYz+ndu/k3uX\n6J/+nd3/jbIV3D6fT0NDQ7HXF0NbkhYvXqylS5dq+fLlkqSioiJ1dXXFFdx9fQN2yskIOTl++ndo\n/07uXaJ/+ndu/3Z3WGytca9du1YnT56UJHV2dio/Pz82lpubq+HhYZ09e1bS+dPqK1assFUcAACY\nzNYRd3FxsVpbW1VeXi5JqqmpUSgUUiQSUWlpqXbv3q3t27dLku644w7df//9iasYAJAWbW1ndPTo\nl+rvz1J29piCwTzdeSdPJUs1l2VZVrqLuMipp0skZ58ukpzdv5N7l+jfhP6Hh4dVVRVSS8sGRaOr\nYts9nm4FAq2qrS2R1+u19d4m9J8sdk+V8zxuAMCUqqpCCoUelzR30vZodJVCoZWSGlRfX5aO0hyJ\nO6cBAK7r1KkutbTcqytD+5K5amnZoPb2M6ksy9EIbgDAdTU3n1U0etuUc6LRVWpq6k1RRSC4AQDX\n1d8f34pqODwvyZXgIoIbAHBdixaNxzUvO3ssyZXgIoIbAHBdmzblyuPpnnKOx9OtYDAvRRWB4AYA\nXNddd61RINAq6dx1ZpxTINCqwkKu504VLgcDAEyptrZEUsOU13EjdQhuAMCUvF6v6uvL1N5+Rk1N\nhxUOz1N29qiCwWUqLOT67VQjuAEAcSksXM0p8VmANW4AAAxCcAMAYBCCGwAAgxDcAAAYhOAGAMAg\nBDcAAAYhuAEAMAjBDQCAQQhuAAAMQnADAGAQbnkKAEiatrYzOnr0S/X3Zyk7e0zBYJ7uvJPbps4E\nwQ0ASLjh4WFVVYUuPFHsh7Hthw51KxB4W7W1JfJ6vWms0FwENwAg4aqqQgqFHpc0d9L2aHSVQqGV\nkhpUX8+TxexgjRsAkFCnTnWppeVeXRnal8xVS8sGtbefSWVZGYPgBgAkVHPzWUWjt005Jxpdpaam\n3hRVlFkIbgBAQvX3x7cKGw7PS3IlmYngBgAk1KJF43HNy84eS3IlmYngBgAk1KZNufJ4uqec4/F0\nKxjMS1FFmYXgBgAk1F13rVEg0Crp3HVmnFMg0KrCQq7ntoPLwQAACVdbWyKp4cJ13Kti2z2ebgUC\nrRfGYQfBDQBIOK/Xq/r6MrW3n1FT02GFw/OUnT2qYHCZCgu5fnsmCG4AQNIUFq7mlHiCscYNAIBB\nCG4AAAzCqXIA18RTnYDZieAGMAlPdQJmN1vBbVmWqqur1dPTI7fbrd27dys3N/eqeS+99JIWL16s\n7du3z7hQAKnBU52A2c3WGndLS4tGR0fV2NioHTt2qKam5qo5jY2N+uyzz2ZcIIDU4alOwOxn64i7\no6NDRUVFkqSCggJ1dXVNGv/oo4/0ySefqLy8XP/85z9nXiWAlDj/VKd7ppxz/qlOh5N2iQ9r68DU\nbAX34OCg/H7/pTfJytLExITmzJmjvr4+1dbWqq6uTseOHbuh983J8U8/KYPRv3P7ny29j4wsiGve\n6Kg3oTXn5Pg1PDysysomHTt2tyKRS2vrjY09euih/9b+/cGMXVufLZ9/uji9/xtlK7h9Pp+GhoZi\nry+GtiS99957+uabb/TUU0+pr69PIyMjuuWWW/Too49O+759fQN2yskIOTl++ndo/7Op9/nzI3HN\nc7uHE1bzxf6feOLta66tRyK36ejRFRoZycy19dn0+aeDk/u3u8Nia4177dq1OnnypCSps7NT+fn5\nsbGKigodPXpU+/fv19NPP62SkpK4QhtA+qXrqU6srQPxsxXcxcXFcrvdKi8v1549e7Rz506FQiEd\nOXIk0fUBSKF0PdXp/Nr6bVPOOb+23pvQ3wuYyNapcpfLpZdffnnStuXLl181b+PGjfaqApA26Xiq\nU39/fF9F4fC8hP9uwDTcgAXAJOl4qtOiReNxzcvOHkvK7wdMQnADuKZUPtVp06ZcvfVW96Qj/Csl\nY20dMBEPGQGQdulaWwdMxBE3gFkhHWvrgIkIbgCzQjrW1gETEdwAZpVUrq0DJmKNGwAAgxDcAAAY\nhOAGAMAgBDcAAAYhuAEAMAjBDQCAQQhuAAAMQnADAGAQghsAAIMQ3AAAGITgBgDAIAQ3AAAGIbgB\nADAIwQ0AgEEIbgAADEJwAwBgEIIbAACDENwAABiE4AYAwCAENwAABiG4AQAwCMENAIBBCG4AAAxC\ncAMAYBCCGwAAgxDcAAAYhOAGAMAgBDcAAAYhuAEAMEiWnR+yLEvV1dXq6emR2+3W7t27lZubGxsP\nhULav3+/srKylJ+fr+rq6kTVCwCAo9k64m5padHo6KgaGxu1Y8cO1dTUxMZGRkb06quv6s0339Rb\nb72lgYEBnThxImEFAwDgZLaCu6OjQ0VFRZKkgoICdXV1xcbcbrcaGxvldrslSePj45o/f34CSgUA\nALaCe3BwUH6/P/Y6KytLExMTkiSXy6UlS5ZIkg4cOKBIJKL169cnoFQAAGBrjdvn82loaCj2emJi\nQnPmXNoHsCxLe/fuVW9vr2pra+N+35wc//STMhj9O7d/J/cu0T/9O7v/G2UruNeuXasTJ07owQcf\nVGdnp/Lz8yeNv/jii/J4PKqrq7uh9+3rG7BTTkbIyfHTv0P7d3LvEv3Tv3P7t7vDYiu4i4uL1dra\nqvLycklSTU2NQqGQIpGIVq9erebmZq1bt04VFRVyuVyqrKxUIBCwVSAAALjEVnC7XC69/PLLk7Yt\nX7489v8//fTTmVUFAACuiRuwAABgEIIbAACDENwAABiE4AYAwCAENwAABiG4AQAwCMENAIBBCG4A\nAAxCcAMAYBCCGwAAgxDcAAAYhOAGAMAgBDcAAAYhuAEAMAjBDQCAQWw9jxtItba2Mzp69Ev192cp\nO3tMwWCe7rxzdbrLAoCUI7gxqw0PD6uqKqSWlg2KRn8Y237oULcCgbdVW1sir9ebxgoBILUIbsxq\nVVUhhUKPS5o7aXs0ukqh0EpJDaqvL0tHaQCQFqxxY9Y6dapLLS336srQvmSuWlo2qL39TCrLAoC0\nIrgxazU3n1U0etuUc6LRVWpq6k1RRQCQfgQ3Zq3+/vhWcsLheUmuBABmD4Ibs9aiReNxzcvOHkty\nJQAwexDcmLU2bcqVx9M95RyPp1vBYF6KKgKA9CO4MWvdddcaBQKtks5dZ8Y5BQKtKizkem4AzsHl\nYJjVamtLJDVcuI57VWy7x9OtQKD1wjgAOAfBjVnN6/Wqvr5M7e1n1NR0WOHwPGVnjyoYXKbCQq7f\nBuA8BDeMUFi4mlPiACDWuAEAMArBDQCAQQhuAAAMwhr3LPH3v3+iP/zh//HYSgDAlAjuNLv42Mr/\n/d97FYlc+itpHluZeXimOIBEILjTjMdWZr7pnil++PAWW+/LjgDgTAR3Gt3IYyu5FMpc0+2cVVYe\n1O9+tzHu95tuR4CzNEBm44/T0ojHVma+eHbOjh27+4aeKX5xR+DyO8lJF3cEHldVVch+wQBmPYI7\njXhsZeaLZ+csErkt7p2zGzlLAyAz2Qpuy7K0a9culZeXq7KyUmfPnp00fvz4cQWDQZWXl+vIkSMJ\nKTQT8djKzJfonTPO0gCwFdwtLS0aHR1VY2OjduzYoZqamtjY+Pi49uzZo4aGBh04cECHDx/Wf/7z\nn4QVnEl4bGXmS/TOGWdpANgK7o6ODhUVFUmSCgoK1NXVFRv7/PPPlZeXJ5/Pp3nz5mndunVqa2tL\nTLUZhsdWZr54ds4WLOiJe+eMszQAbAX34OCg/H5/7HVWVpYmJiauObZw4UINDAzMsMzMVVtbopKS\nBi1Y0DNpu8fTrZKSBh5babh4ds4eeuj/4t454ywNAFuXg/l8Pg0NDcVeT0xMaM6cObGxwcHB2NjQ\n0JCys7Pjet+cHP/0kzKOX++++6Q+/PATHTz4P+rvn6tFi8a1bdsK3XPPk+kuLqUy9fM/fHiLKisP\n6tixuxWJXFqfXrCgRw899H/avz8Y9+VbDz98jx5+eL+OHl2pa/+B2jk9/PAp/dd/VSam+BTJ1M8+\nXvTv7P5vlK3gXrt2rU6cOKEHH3xQnZ2dys/Pj43deuut6u3tVTgclsfjUVtbm558Mr4A6utz7pH5\nPffcrhUrlk3a5qR/Hjk5/ozu93e/23idZ4pvlNfrvaHe9+17QCMjDReu4750SZjH061AoFX79pUY\n9c8y0z/76dC/c/u3u8PisizLutEfsixL1dXV6uk5f3q3pqZGZ86cUSQSUWlpqT744APV1tbKsiwF\ng0Ft2RLfnaGc+uFJzv6XV3J2/3Z7P78j0HvFjoB5fw/h5M9eon8n95/S4E4Wp354krP/5ZWc3b+T\ne5fon/6d27/d4OYGLAAAGITgBgDAIAQ3AAAGIbgBADAIwQ0AgEEIbgAADEJwAwBgEIIbAACDENwA\nABiE4AYAwCAENwAABiG4AQAwCMENAIBBCG4AAAxCcAMAYBCCGwAAgxDcAAAYhOAGAMAgBDcAAAYh\nuAEAMAjBDQCAQQhuAAAMQnADAGAQghsAAIMQ3AAAGITgBgDAIAQ3AAAGIbgBADAIwQ0AgEEIbgAA\nDEJwAwBgEIIbAACDENwAABiE4AYAwCAENwAABiG4AQAwSJadHxoZGdHPf/5zffXVV/L5fNqzZ4++\n9a1vTZrT0NCgY8eOyeVy6b777tNPfvKThBQMAICT2TriPnTokPLz83Xw4EE98sgjqqurmzR+9uxZ\nhUIhvf322zp8+LD+9re/6bPPPktIwQAAOJmt4O7o6NB9990nSbrvvvv04YcfThr/zne+o9dffz32\nenx8XPPnz59BmQAAQIrjVHlTU5P++Mc/Ttp20003yefzSZIWLlyowcHBSeNz587V4sWLJUmvvPKK\nvv/97ysvLy9RNQMA4Fguy7KsG/2h5557Tk8//bRuv/12DQ4OasuWLXr33XcnzRkdHdXOnTvl9/u1\na9cuuVyuhBUNAIBT2TpVvnbtWp08eVKSdPLkSRUWFl4159lnn9X3vvc9VVdXE9oAACSIrSPuaDSq\nF154QX19fXK73dq3b5++/e1vq6GhQXl5eTp37px27NihgoICWZYll8sVew0AAOyzFdwAACA9uAEL\nAAAGIbgBADAIwQ0AgEEIbgAADJK24B4ZGdFPf/pTbdu2Tc8884y+/vrrq+Y0NDSorKxMjz32mF57\n7bU0VJlYlmVp165dKi8vV2Vlpc6ePTtp/Pjx4woGgyovL9eRI0fSVGXyTNd/KBRSWVmZtm7dqurq\n6vQUmUTT9X/RSy+9pN/85jcpri75puv/448/1rZt27Rt2zb97Gc/0+joaJoqTbzpen/nnXe0adMm\nlZaW6tChQ2mqMvlOnz6tioqKq7Zn+nffRdfr/4a/+6w0eeONN6zf/va3lmVZ1p///GfrV7/61aTx\nL7/80tq8eXPsdXl5udXT05PSGhPtr3/9q/WLX/zCsizL6uzstJ599tnY2NjYmFVcXGwNDAxYo6Oj\n1ubNm62vvvoqXaUmxVT9R6NRq7i42BoZGbEsy7K2b99uHT9+PC11JstU/V906NAh67HHHrP27duX\n6vKSbrr+H3nkEevLL7+0LMuyjhw5Yn3xxRepLjFpput9w4YNVjgctkZHR63i4mIrHA6no8yk+v3v\nf2+VlJRYjz322KTtTvjus6zr92/nuy9tR9xOvN95R0eHioqKJEkFBQXq6uqKjX3++efKy8uTz+fT\nvHnztG7dOrW1taWr1KSYqn+3263Gxka53W5JmfF5X2mq/iXpo48+0ieffKLy8vJ0lJd0U/X/xRdf\naPHixXrjjTdUUVGh/v5+LVu2LE2VJt50n/2qVavU39+vkZERScrIm1bl5eVd88ypE777pOv3b+e7\nz9ZjPW8U9zs/b3BwUH6/P/Y6KytLExMTmjNnzlVjCxcu1MDAQDrKTJqp+ne5XFqyZIkk6cCBA4pE\nIlq/fn26Sk2Kqfrv6+tTbW2t6urqdOzYsTRWmTxT9f/111+rs7NTu3btUm5urp555hmtWbNGd999\ndxorTpypepeklStXavPmzfJ6vSouLo59N2aS4uJi/etf/7pquxO++6Tr92/nuy8lwR0MBhUMBidt\ne+655zQ0NCRJGhoamvTBXXT5/c4zYc3T5/PFepY06T9cn883aedlaGhI2dnZKa8xmabqXzq/Drh3\n71719vaqtrY2HSUm1VT9v/fee/rmm2/01FNPqa+vTyMjI7rlllv06KOPpqvchJuq/8WLF2vp0qVa\nvny5JKmoqEhdXV0ZE9xT9d7T06MPPvhAx48fl9fr1fPPP6/3339fDzzwQLrKTSknfPdN50a/+9J2\nqtyJ9zu/vOfOzk7l5+fHxm699Vb19vYqHA5rdHRUbW1t+sEPfpCuUpNiqv4l6cUXX9TY2Jjq6upi\np40yyVT9V1RU6OjRo9q/f7+efvpplZSUZFRoS1P3n5ubq+Hh4dgfbXV0dGjFihVpqTMZpurd7/dr\nwYIFcrvdsaOvcDicrlKTzrriZp1O+O673JX9Szf+3ZeSI+5r2bJli1544QVt3bo1dr9zSZPud97e\n3q6xsTGdPHkyI+53XlxcrNbW1tgaZk1NjUKhkCKRiEpLS7Vz50498cQTsixLpaWluvnmm9NccWJN\n1f/q1avV3NysdevWqaKiQi6XS5WVlQoEAmmuOnGm+/wz3XT97969W9u3b5ck3XHHHbr//vvTWW5C\nTdf7xb8odrvdWrp0qTZu3JjmipPn4kGYk777Lndl/3a++7hXOQAABuEGLAAAGITgBgDAIAQ3AAAG\nIbgBADAIwQ0AgEEIbgAADEJwAwBgkP8PJjFcqzTtbqoAAAAASUVORK5CYII=\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x10be92fd0>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "import seaborn; seaborn.set() # Plot styling\n",
    "plt.scatter(X[:, 0], X[:, 1], s=100);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we'll compute the distance between each pair of points.\n",
    "Recall that the squared-distance between two points is the sum of the squared differences in each dimension;\n",
    "using the efficient broadcasting ([Computation on Arrays: Broadcasting](02.05-Computation-on-arrays-broadcasting.ipynb)) and aggregation ([Aggregations: Min, Max, and Everything In Between](02.04-Computation-on-arrays-aggregates.ipynb))  routines provided by NumPy we can compute the matrix of square distances in a single line of code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "dist_sq = np.sum((X[:, np.newaxis, :] - X[np.newaxis, :, :]) ** 2, axis=-1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This operation has a lot packed into it, and it might be a bit confusing if you're unfamiliar with NumPy's broadcasting rules. When you come across code like this, it can be useful to break it down into its component steps:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(10, 10, 2)"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# for each pair of points, compute differences in their coordinates\n",
    "differences = X[:, np.newaxis, :] - X[np.newaxis, :, :]\n",
    "differences.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(10, 10, 2)"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# square the coordinate differences\n",
    "sq_differences = differences ** 2\n",
    "sq_differences.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(10, 10)"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# sum the coordinate differences to get the squared distance\n",
    "dist_sq = sq_differences.sum(-1)\n",
    "dist_sq.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just to double-check what we are doing, we should see that the diagonal of this matrix (i.e., the set of distances between each point and itself) is all zero:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.])"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dist_sq.diagonal()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It checks out!\n",
    "With the pairwise square-distances converted, we can now use ``np.argsort`` to sort along each row. The leftmost columns will then give the indices of the nearest neighbors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0 3 9 7 1 4 2 5 6 8]\n",
      " [1 4 7 9 3 6 8 5 0 2]\n",
      " [2 1 4 6 3 0 8 9 7 5]\n",
      " [3 9 7 0 1 4 5 8 6 2]\n",
      " [4 1 8 5 6 7 9 3 0 2]\n",
      " [5 8 6 4 1 7 9 3 2 0]\n",
      " [6 8 5 4 1 7 9 3 2 0]\n",
      " [7 9 3 1 4 0 5 8 6 2]\n",
      " [8 5 6 4 1 7 9 3 2 0]\n",
      " [9 7 3 0 1 4 5 8 6 2]]\n"
     ]
    }
   ],
   "source": [
    "nearest = np.argsort(dist_sq, axis=1)\n",
    "print(nearest)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the first column gives the numbers 0 through 9 in order: this is due to the fact that each point's closest neighbor is itself, as we would expect.\n",
    "\n",
    "By using a full sort here, we've actually done more work than we need to in this case. If we're simply interested in the nearest $k$ neighbors, all we need is to partition each row so that the smallest $k + 1$ squared distances come first, with larger distances filling the remaining positions of the array. We can do this with the ``np.argpartition`` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "K = 2\n",
    "nearest_partition = np.argpartition(dist_sq, K + 1, axis=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to visualize this network of neighbors, let's quickly plot the points along with lines representing the connections from each point to its two nearest neighbors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x115ae2898>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.scatter(X[:, 0], X[:, 1], s=100)\n",
    "\n",
    "# draw lines from each point to its two nearest neighbors\n",
    "K = 2\n",
    "\n",
    "for i in range(X.shape[0]):\n",
    "    for j in nearest_partition[i, :K+1]:\n",
    "        # plot a line from X[i] to X[j]\n",
    "        # use some zip magic to make it happen:\n",
    "        plt.plot(*zip(X[j], X[i]), color='black')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each point in the plot has lines drawn to its two nearest neighbors.\n",
    "At first glance, it might seem strange that some of the points have more than two lines coming out of them: this is due to the fact that if point A is one of the two nearest neighbors of point B, this does not necessarily imply that point B is one of the two nearest neighbors of point A.\n",
    "\n",
    "Although the broadcasting and row-wise sorting of this approach might seem less straightforward than writing a loop, it turns out to be a very efficient way of operating on this data in Python.\n",
    "You might be tempted to do the same type of operation by manually looping through the data and sorting each set of neighbors individually, but this would almost certainly lead to a slower algorithm than the vectorized version we used. The beauty of this approach is that it's written in a way that's agnostic to the size of the input data: we could just as easily compute the neighbors among 100 or 1,000,000 points in any number of dimensions, and the code would look the same.\n",
    "\n",
    "Finally, I'll note that when doing very large nearest neighbor searches, there are tree-based and/or approximate algorithms that can scale as $\\mathcal{O}[N\\log N]$ or better rather than the $\\mathcal{O}[N^2]$ of the brute-force algorithm. One example of this is the KD-Tree, [implemented in Scikit-learn](http://scikit-learn.org/stable/modules/generated/sklearn.neighbors.KDTree.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Aside: Big-O Notation\n",
    "\n",
    "Big-O notation is a means of describing how the number of operations required for an algorithm scales as the input grows in size.\n",
    "To use it correctly is to dive deeply into the realm of computer science theory, and to carefully distinguish it from the related small-o notation, big-$\\theta$ notation, big-$\\Omega$ notation, and probably many mutant hybrids thereof.\n",
    "While these distinctions add precision to statements about algorithmic scaling, outside computer science theory exams and the remarks of pedantic blog commenters, you'll rarely see such distinctions made in practice.\n",
    "Far more common in the data science world is a less rigid use of big-O notation: as a general (if imprecise) description of the scaling of an algorithm.\n",
    "With apologies to theorists and pedants, this is the interpretation we'll use throughout this book.\n",
    "\n",
    "Big-O notation, in this loose sense, tells you how much time your algorithm will take as you increase the amount of data.\n",
    "If you have an $\\mathcal{O}[N]$ (read \"order $N$\") algorithm that takes 1 second to operate on a list of length *N*=1,000, then you should expect it to take roughly 5 seconds for a list of length *N*=5,000.\n",
    "If you have an $\\mathcal{O}[N^2]$ (read \"order *N* squared\") algorithm that takes 1 second for *N*=1000, then you should expect it to take about 25 seconds for *N*=5000.\n",
    "\n",
    "For our purposes, the *N* will usually indicate some aspect of the size of the dataset (the number of points, the number of dimensions, etc.). When trying to analyze billions or trillions of samples, the difference between $\\mathcal{O}[N]$ and $\\mathcal{O}[N^2]$ can be far from trivial!\n",
    "\n",
    "Notice that the big-O notation by itself tells you nothing about the actual wall-clock time of a computation, but only about its scaling as you change *N*.\n",
    "Generally, for example, an $\\mathcal{O}[N]$ algorithm is considered to have better scaling than an $\\mathcal{O}[N^2]$ algorithm, and for good reason. But for small datasets in particular, the algorithm with better scaling might not be faster.\n",
    "For example, in a given problem an $\\mathcal{O}[N^2]$ algorithm might take 0.01 seconds, while a \"better\" $\\mathcal{O}[N]$ algorithm might take 1 second.\n",
    "Scale up *N* by a factor of 1,000, though, and the $\\mathcal{O}[N]$ algorithm will win out.\n",
    "\n",
    "Even this loose version of Big-O notation can be very useful when comparing the performance of algorithms, and we'll use this notation throughout the book when talking about how algorithms scale."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "< [Fancy Indexing](02.07-Fancy-Indexing.ipynb) | [Contents](Index.ipynb) | [Structured Data: NumPy's Structured Arrays](02.09-Structured-Data-NumPy.ipynb) >"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}