<!--
  %\VignetteEngine{knitr}
%\VignetteIndexEntry{c) US County Choropleths}
-->

US County Chropleths
===

You can create a choropleth of US Counties with the function `county_choropleth`:

```{r hold=TRUE}
library(choroplethr)

?df_pop_county
data(df_pop_county)

?county_choropleth
county_choropleth(df_pop_county)
```

As demonstrated above, the only required parameter to `county_choropleth` is a data.frame.  You can see the optional parameters by typing `?county_choropleth`.  

# Data Requirements

The data.frame that you provide to `county_choropleth` must have one column named "region" and one column named "value". Your entries for "region" must **exactly** match how regions are named in the map which choroplethr uses.  These names are defined in the object `county.regions`:

```{r}
library(choroplethrMaps)

?county.regions
data(county.regions)
head(county.regions)
```

In order to use choroplethr, you must use the naming convention in the "region" column of county.regions. That is, you must use the numeric version of the county FIPS code - i.e. you must drop any leading zeroes.

# Exploring Data

The `county_choropleth` function provides three parameters to facilitate exploring data: `num_colors`, `state_zoom` and `county_zoom`.  `num_colors` defaults to 7, which means that there are 7 colors on the map. An equal number of regions is assigned to each color; a value of 1 uses a continuous scale. Both `state_zoom` and `county_zoom` default to NULL, which means that all counties are shown. 

As an example of zooming by state with a continuous scale, here is code to create a map of the population of all US Counties on the West Coast. The outlier is Los Angeles County.

```{r}
county_choropleth(df_pop_county,
                 title      = "2012 Population Estimates",
                 legend     = "Population",
                 num_colors = 1,
                 state_zoom = c("california", "washington", "oregon"))
```

As an example of zooming by county, this code maps the population of the 9 Counties in the San Francisco Bay Area:

```{r}
# FIPS codes for Alameda, Contra Costa, Marin, Napa, San Francisco, San Mateo, Santa Clara, 
# Solano, and Sonoma counties
bay_area_counties = c(6001, 6013, 6041, 6055, 6075, 6081, 6085, 6095, 6097)
county_choropleth(df_pop_county,
                 title       = "2012 Population Estimates",
                 legend      = "Population",
                 num_colors  = 1,
                 county_zoom = bay_area_counties)
```

# Advanced Options

Any customization outside the optional parameters presented above will require you to create a `CountyChoropleth` object.  choroplethr uses [R6](https://github.com/wch/R6) to take advantage of object-oriented programming.  Here is an example of using the `ggplot2_scale` variable on the base Choropleth object to customize the palette used.

```{r}
library(ggplot2)

choro = CountyChoropleth$new(df_pop_county)
choro$title = "2012 Population Estimates"
choro$ggplot_scale = scale_fill_brewer(name="Population", palette=2, drop=FALSE)
choro$render()
```

**Note:** Care must be taken when manually setting the scale on `CountyChoropleth` objects. In particular, choroplethr uses ggplot2 custom annotations to render Alaska and Hawaii as insets. This means that the scales of the insets and the main map will only be the same if you do the following

1. for discrete scales, pass `drop=FALSE` to the scale (as above).
2. for continuous scales, pass `limits` which encompass the minimum and maximum values for the entire dataset.