---
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, echo = 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(colour = "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", lines = "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", lines = "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"), lines = "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")
```

## 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`.
