<!--
  %\VignetteEngine{knitr}
%\VignetteIndexEntry{d) Country Choropleths}
-->

Country Choropleths 
===

You can create a choropleth of Countries with the function `country_choropleth`:

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

?df_pop_country
data(df_pop_country)

?country_choropleth
country_choropleth(df_pop_country)
```

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

This map demonstrates another feature of choroplethr: regions for which no value is provided (what is the population of Antarctica?) appear, by default, as black.  

# Data Requirements

The data.frame that you provide to `country_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 `country.regions`:

```{r}
library(choroplethrMaps)

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

In order to use choroplethr, you must use the naming convention in the "region" column of country.regions. That is, you must use full names in all lowercase letters.

# Exploring Data

The `country_choropleth` function provides two parameters to facilitate exploring data: `num_colors` and `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. `zoom` defaults to NULL, which means that all states are shown. You can set it to be a vector of valid regions.  

As an example, here is how you can use choroplethr to show the population of the US, Canada and Mexico.

```{r}
country_choropleth(df_pop_country,
                 title      = "2012 Population Estimates",
                 legend     = "Population",
                 num_colors = 1,
                 zoom       = c("united states of america", "mexico", "canada"))
```

# Advanced Options

Any customization outside the optional parameters presented above will require you to create a `StateChoropleth` 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` on the base Choropleth object to customize the palette used.


```{r}
library(ggplot2)

choro = CountryChoropleth$new(df_pop_country)
choro$title = "2012 Population Estimates"
choro$ggplot_scale = scale_fill_brewer(name="Population", palette=2)
choro$render()
```
