us_polygon_mapper
us_polygon_mapper allows users to create polygon maps of the United States from csvâs, python dictionaries and pandas DataFrames. The script utilizes Google Maps API (gmplot wrapper). You can create html files and pngâs (when a png is created, an html is also created). PhantomJS must be installed to create pngâs (see below).
Basics
To install:
pip install us_polygon_mapper
To use:
#!/usr/bin/env python import us_polygon_mapper.us_polygon_mapper as uspm
You can use any of the following as data inputs:
- A csv with a column containing states (full or abbreviated) and another column containing values
- A dictionary of the form {state1: value1, state2: value2}
- A pandas DataFrame with a column containing states (full or abbreviated) and another column containing values
The map works by splitting your data into two groups. The âlowâ group will contain all data points <= the âmiddleâ (by default, the mean). The âhighâ group will contain all the data points > the âmiddleâ.
A color is specified for the âlowâ group and the âhighâ group (by default: green and red respectively).
Colors: âredâ, âorangeâ, âyellowâ, âgreenâ, âblueâ, âpurpleâ, âbrownâ
Middle: âmeanâ, âmedianâ, float, âpercentile=xâ (x: 0-100)
By default, for csvâs and pandas DataFrames, the states column is assumed to be column 0, and the values column is assumed to be column 1.
You can change this by passing the argument columns=[state_column_num, value_column_num] (e.g. [2, 3]) or columns=[state_column_name, value_column_name] (e.g. [âstateâ, âdebtâ]).
Use case:
For example, you could use this package to create a map of election results. You could make your values GOP% - DEM% for each state. You would then set your âmiddleâ to be 0, âlow colorâ to be blue and âhigh colorâ to be red. See example.py.
Main Functions
The main functions are:
- uspm.dict_to_html(values_dict, low_color=âgreenâ, high_color=âredâ, middle=âmeanâ, html_fn=âmymap.htmlâ)
- uspm.csv_to_html(csv_path, low_color=âgreenâ, high_color=âredâ, middle=âmeanâ, columns=None, html_fn=âmymap.htmlâ)
- uspm.df_to_html(df, low_color=âgreenâ, high_color=âredâ, middle=âmeanâ, columns=None, html_fn=âmymap.htmlâ)
- uspm.dict_to_png(values_dict, low_color=âgreenâ, high_color=âredâ, middle=âmeanâ, png_fn=âmymap.pngâ, html_fn=âmymap.htmlâ)
- uspm.csv_to_png(csv_path, low_color=âgreenâ, high_color=âredâ, middle=âmeanâ, columns=None, png_fn=âmymap.pngâ, html_fn=âmymap.htmlâ)
- uspm.df_to_png(df, low_color=âgreenâ, high_color=âredâ, middle=âmeanâ, columns=None, png_fn=âmymap.pngâ, html_fn=âmymap.htmlâ)
colors: âredâ, âorangeâ, âyellowâ, âgreenâ, âblueâ, âpurpleâ, âbrownâ
middle: âmeanâ, âmedianâ, float, âpercentile=xâ (x: 0-100)
columns: None (defaults to [0, 1]), [state_column_num, value_column_num] (e.g. [2, 3]), or [state_column_name, value_column_name] (e.g. [âstateâ, âdebtâ])
Remark on pngâs
To create pngâs, you must have PhantomJS installed <http://phantomjs.org/download.html>.
Mac:
(With Homebrew) Enter âbrew install phantomjsâ in Terminal
Windows:
Download PhantomJS <http://phantomjs.org/download.html> and place phantomjs.exe in your Path (full steps below for Windows 10).
- Download PhantomJS <http://phantomjs.org/download.html>
- Go to Control Panel > System and Security > System
- Click "Advanced system settings" in the left panel
- Click Environment Variables...
- Either move phantomjs.exe to a folder in your Path, or add the folder phantomjs.exe is in to your Path.
Notes
- state coordinates: <https://github.com/kjhsoftware/us-state-polygons/blob/master/states.xml>
- state abbreviations: <https://gist.github.com/rogerallen/1583593>
- 2016 election results: <http://cookpolitical.com/story/10174>