---
title: "usmap: Mapping the US"
author: "Paolo Di Lorenzo"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mapping the US}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Extending `plot_usmap` with `ggplot2`

The nice thing about `usmap::plot_usmap` is it returns a [ggplot object](http://docs.ggplot2.org/current/) object, which means we can add `ggplot` layers to the plot right out of the box.

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
library(usmap)
library(ggplot2)

plot_usmap(regions = "counties") + 
  labs(title = "US Counties",
       subtitle = "This is a blank map of the counties of the United States.") + 
  theme(panel.background = element_rect(color = "black", fill = "lightblue"))
```

#### Plot only certain states

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
library(usmap)
library(ggplot2)

plot_usmap(include = c("CA", "ID", "NV", "OR", "WA")) +
  labs(title = "Western US States",
       subtitle = "These are the states in the Pacific Timezone.")
```

#### Add some data to the map

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
library(usmap)
library(ggplot2)

plot_usmap(data = statepop, values = "pop_2015", color = "red") + 
  scale_fill_continuous(name = "Population (2015)", label = scales::comma) + 
  theme(legend.position = "right")
```

Notice the comprehensive expandability that can be applied to the map using `ggplot2` layers. For example, we might want to use a different color scheme.

#### Change fill color scale

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
library(usmap)
library(ggplot2)

plot_usmap(data = statepop, values = "pop_2015", color = "red") + 
  scale_fill_continuous(
    low = "white", high = "red", name = "Population (2015)", label = scales::comma
  ) + theme(legend.position = "right")
```

The data-filled map can also be filtered to show certain regions only, like the western states shown above.

#### Show data in certain states

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
library(usmap)
library(ggplot2)

plot_usmap(
    data = statepop, values = "pop_2015", include = c("CA", "ID", "NV", "OR", "WA"), color = "red"
  ) + 
  scale_fill_continuous(
    low = "white", high = "red", name = "Population (2015)", label = scales::comma
  ) + 
  labs(title = "Western US States", subtitle = "These are the states in the Pacific Timezone.") +
  theme(legend.position = "right")
```

## Built-in Regions

`usmap` provides some built-in regions based on the [US Census Bureau Regions and Divisions](https://www2.census.gov/geo/pdfs/maps-data/maps/reference/us_regdiv.pdf). These can be used in place of the `include`/`exclude` parameters when using `us_map` or `plot_usmap` and start with a `.` (dot):

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
usmap::plot_usmap(include = .south_region)
```

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
usmap::plot_usmap(include = .east_south_central)
```

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
usmap::plot_usmap(include = .south_region, exclude = .east_south_central)
```

This also works with county maps. The regions can also be combined with actual state or FIPS values within the `include`/`exclude` parameters:

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
usmap::plot_usmap("counties", 
                  include = c(.south_region, "IA"), 
                  exclude = c(.east_south_central, "12"))  # 12 = FL
```

You can even include or exclude individual counties (county-level inclusions/exclusions can only be done via their FIPS codes due to duplicate county names across states; for example eight different states have an "Orange County"):

```{r, fig.align='center', fig.width=7, message=FALSE, warning=FALSE}
usmap::plot_usmap("counties", fill = "yellow", alpha = 0.25,
                  # 06065 = Riverside County, CA
                  include = c(.south_region, "IA", "06065"),
                  # 12 = FL, 48141 = El Paso County, TX
                  exclude = c(.east_south_central, "12", "48141"))
```

These parameters therefore allow for the possibility of some complex compositions of states and counties, to create the exact map that is desired.

#### Supported US Census Regions and Divisions

The following divisions are supported:
```{r}
.new_england
.mid_atlantic
.east_north_central
.west_north_central
.south_atlantic
.east_south_central
.west_south_central
.mountain
.pacific
```

Regions are composed of multiple divisions, and the following are supported:
```{r}
.northeast_region      # c(.new_england, .mid_atlantic)
.north_central_region  # c(.east_north_central, .west_north_central)
.midwest_region        # .north_central_region (renamed in June 1984)
.south_region          # c(.south_atlantic, .east_south_central, .west_south_central)
.west_region           # c(.mountain, .pacific)
```

## Raw map data

The raw US map data for counties or states can be obtained for further manipulation (and joining with data).

```{r}
str(usmap::us_map())
```
```{r}
str(usmap::us_map(regions = "counties"))
```

You can also include only certain states and counties just like in `plot_usmap`. In fact, the `regions` and `include` parameters of `plot_usmap` are derived directly from their usage in `us_map`.
