<!--
%\VignetteEngine{knitr}
%\VignetteIndexEntry{a) Introduction}
-->

Introduction
========================================================

### What is a Choropleth?

A choropleth is a map which 

  1. Shows geographic boundaries.
  2. Colors those regions based on some metric.

Choropleths are useful for visualizing data where geographic boundaries are a natural unit of aggregation.  For example, here is a choropleth that shows 2012 US State Population Estimates:

```{r}
    library(choroplethr)
    ?df_pop_state
    data(df_pop_state)

    state_choropleth(df_pop_state, title="2012 US State Population Estimates", legend="Population")
```

### What is choroplethr? 

`choroplethr` is an R package that facilitates the creation of choropleth maps in R. It does this in 3 ways.

1. It provides ready-made functions for creating choropleths with four different maps. 
2. It provides API connections to interesting data sources for making choropleths.
3. It provides a framework for creating choropleths from arbitrary shapefiles.

The remaining vignettes explain these features in more detail.
