Simplify the Creation of Choropleth Maps in R

Choropleths are thematic maps where geographic regions, such as states, are colored according to some metric, such as the number of people who live in that state. This package simplifies this process by 1. Providing ready-made functions for creating choropleths of common maps. 2. Providing data and API connections to interesting data sources for making choropleths. 3. Providing a framework for creating choropleths from arbitrary shapefiles. 4. Overlaying those maps over reference maps from Google Maps.


choroplethr simplifies the creation of choropleth maps in R. Choropleths are thematic maps where geographic regions, such as states, are colored according to some metric, such as the number of people who live in that state. choroplethr simplifies this process by
  1. Providing ready-made functions for creating choropleths using 220 different maps.
  2. Providing API connections to interesting data sources for making choropleths.
  3. Providing a framework for creating choropleths from arbitrary shapefiles.

My free course Learn to Map Census Data in R can teach you how to use this package. There is also a paid course that goes into much more detail. I blog about this package's development here.

Please see the following pages for more details.

  1. Introduction
  2. US State Choropleths
  3. US County Choropleths
  4. Country Choropleths
  5. Mapping US Census Data
  6. Mapping World Bank WDI Data
  7. Animated Choropleths
  8. Creating Your Own Maps
  9. Creating Administrative Level 1 Maps

To install the latest stable release type the following from an R console:

install.packages("choroplethr")

To install the development version use the devtools package:

# install.packages("devtools")
library(devtools)
install_github("choroplethr", "arilamstein")
library(choroplethr)

News

-New function admin1_region_choropleth lets you create admin 1 choropleths based on a list of admin 1 regions. This can span multiple countries and include subset of countries. -Function get_acs_data now has a parameter include_moe which, if true will return the 90% margins of error in the data frame.

-Set reference_map=TRUE in admin1_choropleth to overlay the choropleth over a reference map taken from google maps. -Add startup messages designed to help users.

-Compatability changes to support building with roxygen2 version 5.0.1. -Compatability changes to work with ggplot2 version 2.0.0.

-Set reference_map=TRUE in state_choropleth and county_choropleth functions to overlay the choropleth over a reference map taken from google maps. The reference map is in black and white and the alpha of the choropleth is set to .5 by default. -The reference map code is in the base choropleth object, so you should be able to easily use it for other maps as well.

-Default projection for all maps is now coord_quickmap, including insets of US maps. -Add ggplot_polygon member variable to base choropleth object, which makes it easy to remove borders from choropleth objects. -Add variable continental_us_states, which is a vector of continental us state names.

-Bug fix: in get_acs_data, do not prompt user for column_idx if they already supply it. -function ?get_state_demographics returns 8 cached demographic variables from a given ACS -data.frame ?df_state_demographics caches the results of get_state_demograhpics for the 2013 5 year ACS -function ?get_county_demographics returns 8 cached demographic variables from a given ACS -data.frame ?df_county_demographics caches the results of get_county_demographics for the 2013 5 year ACS

-All zip related functionality has been deprecated and moved to the choroplethrZip package, which is available here: https://github.com/arilamstein/choroplethrZip. -Merge the county_choropleth and county_choropleth_zoom functions. The resulting function now has two zoom parameters: state_zoom and county_zoom. -Break the choroplethr_acs function into three separate functions: state_choropleth_acs, county_choropleth_acs and zip_choropleth_acs (located in choroplethrZip). This is because each function now has different zoom parameters, so it didn't make sense to have one function with a large number of parameters, many of which cannot be set for any given function call. -Rename "buckets" parameter to "num_colors" to clarity the meaning for the user. During development it made sense to think of assigning values to buckets. But I think that it's easier for users to just think about how many colors they want on the map, and then see in the comments that each color has an equal number of regions assigned to it. Also, "num_colors=1" has a more natural relationship to a continuous scale than "buckets=1". -Bug fix: documentation of choroplethr_animate() was not working -Deprecate get_acs_df in favor of get_acs_data -Export choropleth object.

-Bug fix: text for vignettes was for some reason not rebuilt into HTML.

-Add function county_zoom_choropleth, which allows you to zoom in on counties, not states. If an individual county is specified, render it with no fill color. -Updated and corrected the values of df_president. Thank you to Richard Careaga. -Update vignettes about US maps. Specifically, provide information about custom scales to include warning about interactions with insets of AK and HI. -Add admin1_choropleth function which allows you to create an Administrative Level 1 choropleth of any country in the world. (Administrative Level 1 is the generic term for states, provinces, etc.). Create a vignette demonstrating usage of this function.

-Move the maps and their helper data.frames to a separate package, choroplethrMaps -Change dependencies (remove dependencies on maps, grid, plyr->dplyr, add R6, add WDI) -Create R6 objects to simplify map creation -Base Choropleth object -CountryChoropleth inherits directly from Choropleth -Create USAChoropleth object to handle similar issues for all USA maps, such as insets and state boundaries -StateChoropleth, CountyChoropleth, ZipMap all inherit from those USAChoropleth -From a user's perspective, the only important functions on Choropleth are: new()/initialize() and render(). -From a developer's perspective, you care about three additional functions: clip(), discretize() and bind(). If you are using choroplethr as a framework to create your own choropleth, you might want to override those functions. Those functions are all called by prepare_map(). So in some sense, you just need to care about prepare_map() and render(). -Create helper functions for creating the 4 maps. See ?state_choropleth, ?county_choropleth, ?zip_map, ?country_choropleth for details. Importantly, all those functions have the five exact same parameters, four of which are optional. -Remove some functions that I think no one was using (see NAMESPACE diff for details) -Change some parameters on choroplethr_acs for consistency. -Break up the "data(choroplethr)" object. Now just say the object you actually want (e.g. "data(df_pop_state)"). This makes maintenance much easier. -Add choroplethr_wdi function, which generates choropleths from World Bank data. See the documentation of the WDI package for details. -Update function documentation and examples. -Update tests. -Change country.names from being a vector of English words to a data.frame with 2 columns: one named region (which contains English words), and one named "iso2c", which contains the iso2c equivalent names.

BUG FIX -with character input for values inset maps were not having consistent scales with main map. Fix this by converting character input to factors early on. -setting custom scales and having the values work across insets (e.g. AK and HI) now works if you create a Choropleth object and set the ggplot_scale field to the scale you want.

FEATURE -Add a world map: see ?map.world for more info -Add a vector of all countries in the world map: see ?country.names for more info -Add support for the world map to the choroplethr() function: see ?choroplethr for more info.

FEATURE -Add a flag to the choroplethr() function, renderAsInsets. If TRUE and user asked to view all states, then AK and HI will be rendered as insets, which is the standard way of rendering a map of all 50 US states. -Create a data.frame, map.states, which contains a map for all 50 states plus the District of Columbia. See ?map.states for details. -Create a data.frame, state.names, which contains naming information for each state in map.states. See ?state.names for more information. -Create a data.frame, map.counties, which contains a map for the counties of all 50 states plus the District of Columbia. See ?map.counties for details. -Create a data.frame, county.names, which contains naming information for each county in map.counties. See ?county.names for more information.

BUG FIXES

FEATURE -Make NA values appear black on the map. The default value for NA values in ggplot2, grey50, was difficult to distinguish from the light values in the brewer scale. -Create function clip_df(data.frame, lod) that clips a data.frame to a map. This is useful when you want to do statistics on a data.frame (such as above/below median values), and have your computations match the map. For example, maps in choroplethr do not contain Alaska or Hawaii. -Rename vignettes so that they appear in proper order on CRAN website. -Export format_levels function

BUG FIXES -handle counties with leading zeroes.

FEATURE -New choroplethr_animate function for animating choropleth maps. See ?choroplethr_animate -Handle string data as values -add example datasets and update help -Add commas to scales.

BUG FIXES -Choropleths of state, county and zip data with factor values were broken

BUG FIXES -Subsetting by state was broken for state and county choropleths -Fix a bug where ACS state choropleths were not displaying titles

FEATURES -Some features to support integration with shiny - requested by pssguy via github.
-New function get_acs_column_names -New parameter column_idx parameter to function get_acs_df -Improve formatting of discrete scales

FEATURES -Create 3 new functions which support a workflow of giving users more control of choropleths -get_acs_df, which gets an ACS table as a data.frame. You can then use, for example, cut2 to discretize the values as you see fit. -bind_df_to_map, which binds a data.frame of (region, value) pairs to a state, county or zip map. -render_choropleth, which renders a choropleth from (map, value) pairs.

-Improve documentation

FEATURES -Allow users to specify choropleths of a subset of states. See the "states" parameter in ?choroplethr and ?choroplethr_acs. -choroplethr_acs now supports year and span fields. See http://1.usa.gov/1geFSSj for a list of all ACS years with spans. However, see http://www.census.gov/developers/data/ for a list of which ACS are available via the Census API. Currently it is the 5-year surveys ending in 2010, 2011, 2012. Thanks to Ezra Haber Glenn for clarifying this.

-Add requirement of minimum R version of 3.0.0 in the DESCRIPTION file. See https://groups.google.com/forum/#!topic/choroplethr/Owv7NgAacGE for details.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("choroplethr")

3.6.1 by Ari Lamstein, 7 months ago


http://www.arilamstein.com/open-source


Browse source code at https://github.com/cran/choroplethr


Authors: Ari Lamstein <ari@lamsteinconsulting.com>[cre, aut], Brian P Johnson <brian@pjohnson.info> [ctb, frontend animation code]


Documentation:   PDF Manual  


BSD_3_clause + file LICENSE license


Imports scales, Hmisc, stringr, ggplot2, dplyr, R6, WDI, ggmap, RgoogleMaps, tigris, gridExtra

Depends on acs

Suggests testthat, choroplethrMaps, choroplethrAdmin1


Imported by noaastormevents, rUnemploymentData.

Suggested by countytimezones.


See at CRAN