Merge pull request #929 from plotly/zipcode-choro

Choropleth Counties

Author: Kully

CHANGELOG.md

@@ -2,6 +2,11 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.4.0] - 2018-02-16
+### Added
+- County Choropleth figure factory. Call `help(plotly.figure_factory.create_choropleth)` for examples and how to get started making choropleths of US counties with the Python API.
+
+
 ## [2.3.0] - 2018-01-25
 ### Fixed
 - Merged [pull request](https://github.com/plotly/plotly.py/commit/a226e07393c158e01c34c050aaf492da9d77679a) that fixes `GraphWidget` for IPython > v6

optional-requirements.txt

@@ -28,3 +28,8 @@ scipy
 ## jupyter ##
 jupyter
 ipykernel
+
+## deps for _county_choropleth.py figure factory
+pyshp
+geopandas
+shapely

plotly/colors.py

@@ -18,18 +18,60 @@
 floats between 0 and 1 inclusive.
 
 -----
-Types of colormap:
+Colormaps and Colorscales:
+A colormap or a colorscale is a correspondence between values - Pythonic
+objects such as strings and floats - to colors.
+
 There are typically two main types of colormaps that exist: numerical and
 categorical colormaps.
 
-Numerical colormaps are used when a the coloring column being used takes a
-spectrum of values or numbers. Alternatively, a categorical colormap is used
-to assign a specific value in a color column to a specific color everytime it
-appears in the plot at hand. For instance, a column of strings in a dataframe
-would naturally use a categorical colormap. You can choose however to use a
-categorical colormap with a column of numbers. Be careful though, as if you
-have a large set of unique numbers in your column you'll get a lot of colors.
-
+Numerical:
+----------
+Numerical colormaps are used when the coloring column being used takes a
+spectrum of values or numbers.
+
+A classic example from the Plotly library:
+```
+rainbow_colorscale =  [
+    [0, 'rgb(150,0,90)'], [0.125, 'rgb(0,0,200)'],
+    [0.25, 'rgb(0,25,255)'], [0.375, 'rgb(0,152,255)'],
+    [0.5, 'rgb(44,255,150)'], [0.625, 'rgb(151,255,0)'],
+    [0.75, 'rgb(255,234,0)'], [0.875, 'rgb(255,111,0)'],
+    [1, 'rgb(255,0,0)']
+]
+```
+
+Notice that this colorscale is a list of lists with each inner list containing
+a number and a color. These left hand numbers in the nested lists go from 0 to
+1, and they are like pointers tell you when a number is mapped to a specific
+color.
+
+If you have a column of numbers `col_num` that you want to plot, and you know
+
+```
+min(col_num) = 0
+max(col_num) = 100
+```
+
+then if you pull out the number `12.5` in the list and want to figure out what
+color the corresponding chart element (bar, scatter plot, etc) is going to be,
+you'll figure out that proportionally 12.5 to 100 is the same as 0.125 to 1.
+So, the point will be mapped to 'rgb(0,0,200)'.
+
+All other colors between the pinned values in a colorscale are linearly
+interpolated.
+
+Categorical:
+------------
+Alternatively, a categorical colormap is used to assign a specific value in a
+color column to a specific color everytime it appears in the dataset.
+
+A column of strings in a panadas.dataframe that is chosen to serve as the
+color index would naturally use a categorical colormap. However, you can
+choose to use a categorical colormap with a column of numbers.
+
+Be careful! If you have a lot of unique numbers in your color column you will
+end up with a colormap that is massive and may slow down graphing performance.
 """
 from __future__ import absolute_import
 

plotly/figure_factory/__init__.py

@@ -18,3 +18,4 @@
 from plotly.figure_factory._table import create_table
 from plotly.figure_factory._trisurf import create_trisurf
 from plotly.figure_factory._violin import create_violin
+from plotly.figure_factory._county_choropleth import create_choropleth