tutorial_1_Colorbin.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#chorogrid tutorial, part 1:\n",
    "\n",
    "## Colorbin class\n",
    "\n",
    "This class can be used independently of the Chorogrid class shown in part 2, and vice-versa, but they work well together.\n",
    "\n",
    "This allows you to input a parallel list of ids (e.g. state abbreviations) and quantities (e.g. unemployment rate), and it will output a list of colors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on class Colorbin in module chorogrid.Colorbin:\n",
      "\n",
      "class Colorbin(builtins.object)\n",
      " |  Instantiate with a list of quantities and colors, then retrieve \n",
      " |  the following attributes:\n",
      " |  .colors_out : output list of colors, same length as quantities\n",
      " |  .fenceposts : divisions between bins\n",
      " |  .labels: one per color\n",
      " |  .fencepostlabels: one per fencepost\n",
      " |  .complements: list of colors, see set_complements, below\n",
      " |  \n",
      " |  attributes that can be changed:\n",
      " |  .proportional : if True, all bins have fenceposts same distance\n",
      " |                  apart (with default bin_min, bin_mid and bin_max)\n",
      " |                : if False, all bins have (insofar as possible) the same\n",
      " |                  number of members\n",
      " |                : note that this can break if not every quantity is \n",
      " |                  unique\n",
      " |  .bin_min, .bin_max, .bin_mid\n",
      " |  .decimals : if None, no rounding; otherwise round to this number\n",
      " |  \n",
      " |  methods:\n",
      " |  .set_decimals(n): just what it sounds like\n",
      " |  .recalc(fenceposts=True): recalculate colors (and fenceposts, if True)\n",
      " |   based on attributes\n",
      " |  .calc_complements(cutoff [between 0 and 1], color_below, color_above):\n",
      " |      if the greyscale color is below the cutoff (i.e. darker),\n",
      " |      complement is assigned color_below, otherwise color_above.\n",
      " |  \n",
      " |  Methods defined here:\n",
      " |  \n",
      " |  __init__(self, quantities, colors_in, proportional=True, decimals=None)\n",
      " |  \n",
      " |  calc_complements(self, cutoff, color_below, color_above)\n",
      " |  \n",
      " |  count_bins(self)\n",
      " |  \n",
      " |  recalc(self, fenceposts=True)\n",
      " |  \n",
      " |  set_decimals(self, decimals)\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Data descriptors defined here:\n",
      " |  \n",
      " |  __dict__\n",
      " |      dictionary for instance variables (if defined)\n",
      " |  \n",
      " |  __weakref__\n",
      " |      list of weak references to the object (if defined)\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# import the class\n",
    "from chorogrid import Colorbin\n",
    "\n",
    "# read the docs\n",
    "help(Colorbin)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You'll need to supply a list of colors in hex format; I recommend the library ``colorlover``. For now, I'll just enter a diverging list of six colors, ranging from dark brown to light brown/blue to dark blue.\n",
    "\n",
    "With ``colorlover`` installed, they were produced with the following code:\n",
    "\n",
    "    import colorlover as cl\n",
    "    colors = cl.scales['6']['div']['PuOr']\n",
    "    def rgb2hex(list_of_tuples):\n",
    "        output = []\n",
    "        for r, g, b in list_of_tuples:\n",
    "            output.append(\"#{0:02x}{1:02x}{2:02x}\".format(int(r), int(g), int(b)))\n",
    "        return output\n",
    "    colors = rgb2hex(cl.to_numeric(colors))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "mycolors = ['#b35806', '#f1a340', '#fee0b6', '#d8daeb', '#998ec3', '#542788']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We also need some data. I've prepared one column from the U.S. Census"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>state</th>\n",
       "      <th>Percent_living_in_same_home_as_one_year_ago</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>46</th>\n",
       "      <td>CA</td>\n",
       "      <td>84.2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>47</th>\n",
       "      <td>AZ</td>\n",
       "      <td>80.4</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>48</th>\n",
       "      <td>AR</td>\n",
       "      <td>83.6</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>49</th>\n",
       "      <td>AL</td>\n",
       "      <td>85.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>50</th>\n",
       "      <td>AK</td>\n",
       "      <td>80.3</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   state  Percent_living_in_same_home_as_one_year_ago\n",
       "46    CA                                         84.2\n",
       "47    AZ                                         80.4\n",
       "48    AR                                         83.6\n",
       "49    AL                                         85.0\n",
       "50    AK                                         80.3"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import pandas as pd\n",
    "df = pd.read_csv('chorogrid/sample_data/sample_state_data.csv')\n",
    "df.tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Now we can instantiate the ``Colorbin`` class with the quantity column in the dataframe, plus our list of six colors. Note that you don't have to use pandas, you could pass two lists instead."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "# I've stated the proportional and decimals args, but left them at their defaults for now.\n",
    "mybin = Colorbin(df['Percent_living_in_same_home_as_one_year_ago'], mycolors, proportional=True, decimals=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``Colorbin`` has automatically chosen six 'bins' representing the range of quantities. You can retrieve them with the ``.fenceposts`` attribute. Note that because there are six bins in this case, there are seven fenceposts: bin #1 is fencepost 0-1, bin #2 is 1-2 ... bin #6 is 6-7."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[77.700000000000003,\n",
       " 79.766666666666666,\n",
       " 81.833333333333343,\n",
       " 83.900000000000006,\n",
       " 85.966666666666669,\n",
       " 88.033333333333331,\n",
       " 90.099999999999994]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mybin.fenceposts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that these are floats. To see what the class will output as text that can be used in a map legend, use .fencepostlabels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['77.7',\n",
       " '79.7666666667',\n",
       " '81.8333333333',\n",
       " '83.9',\n",
       " '85.9666666667',\n",
       " '88.0333333333',\n",
       " '90.1']"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mybin.fencepostlabels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "We also have a list of colors the same length as the quantities we passed to the constructor, corresponding to the fenceposts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['#f1a340', '#542788', '#d8daeb', '#fee0b6', '#998ec3', '#d8daeb', '#fee0b6', '#fee0b6', '#d8daeb', '#fee0b6', '...']\n"
     ]
    }
   ],
   "source": [
    "print(mybin.colors_out[:10]+ ['...'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Back to the fenceposts. That's a lot of decimals, let's change it.\n",
    "\n",
    "After changing an attribute, the output fenceposts/labels and/or colors will not be changed until the ``.recalc()`` method is called. Calling ``.recalc(fenceposts=False)`` just recalculates the colors (which would have little or no effect in this case, since we are just changing the decimals, so only colors right near a fencepost might change); calling ``.recalc(True)`` recalculates the fenceposts, and then the colors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['77.7', '79.8', '81.8', '83.9', '86.0', '88.0', '90.1']"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mybin.set_decimals(1)\n",
    "mybin.recalc(fenceposts=True)\n",
    "mybin.fencepostlabels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see how many ids fall in each bin with the ``.count_bins()`` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "count  label\n",
      "=====  =====\n",
      "    1  77.7-79.8\n",
      "    4  79.8-81.8\n",
      "   16  81.8-83.9\n",
      "   17  83.9-86.0\n",
      "    8  86.0-88.0\n",
      "    5  88.0-90.1\n"
     ]
    }
   ],
   "source": [
    "mybin.count_bins()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "If you want the fenceposts to be easier-to-read whole numbers, or any specific numbers, just reassign the ``.fenceposts`` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "count  label\n",
      "=====  =====\n",
      "    1  77-80\n",
      "    5  80-82\n",
      "   15  82-84\n",
      "   17  84-86\n",
      "    8  86-88\n",
      "    5  88-91\n"
     ]
    }
   ],
   "source": [
    "mybin.fenceposts = [77,80,82,84,86,88,91]\n",
    "mybin.recalc(fenceposts=False) # if this were true, the fenceposts would be changed back to what they were originally\n",
    "mybin.count_bins()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "If you want each bin to contain(approximately) the same number of ids, you can pass ``proportional=False`` to the constructor. Note that having a choropleth with unequally-sized bins can be misleading to the viewer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "mybin = Colorbin(df['Percent_living_in_same_home_as_one_year_ago'], mycolors, proportional=False, decimals=None)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "count  label\n",
      "=====  =====\n",
      "    8  77.7-82.7\n",
      "    7  82.7-83.6\n",
      "    8  83.6-84.7\n",
      "   11  84.7-85.6\n",
      "    8  85.6-86.6\n",
      "    9  86.6-90.1\n"
     ]
    }
   ],
   "source": [
    "mybin.count_bins()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, there is the function ``calc_complements`` that can be used to ensure text that overlays a choropleth is visible. Choose a level of 'darkness' of the greyscale version of the colors (0 is black, 1 is white), a font color for dark backgrounds and a font color for light backgrounds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "#b35806 #ffffff\n",
      "#542788 #ffffff\n",
      "#998ec3 #000000\n",
      "#f1a340 #000000\n",
      "#542788 #ffffff\n",
      "#d8daeb #000000\n",
      "#f1a340 #000000\n",
      "#f1a340 #000000\n",
      "#fee0b6 #000000\n",
      "#fee0b6 #000000\n"
     ]
    }
   ],
   "source": [
    "mybin.calc_complements(0.5, '#ffffff', '#000000')\n",
    "for i, (color, complement) in enumerate(zip(mybin.colors_out, mybin.complements)):\n",
    "    if i<10:\n",
    "        print(color, complement)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "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.5.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}