---
title: "A sample analysis using USAboundaries"
author: "Lincoln Mullen"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{A sample analysis using USAboundaries}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

The USAboundaries package provides both historical and contemporary boundaries of the United States. This vignette gives an example of using the package to create maps of Maryland Congressional elections (to the 115th Congress) and in 1792 (to the 3rd Congress). We will use the USAboundaries package data for the spatial data. See the documentation for the functions used for citations to the underlying datasets. For the 2016 Congressional votes, we will use [data available on the website](http://history.house.gov/Institution/Election-Statistics/Election-Statistics/) of the U.S. House of Representatives. For the 1792 elections we will use data from the [*Mapping Early American Elections*](https://earlyamericanelections.org/data/) project.

We begin by loading the packages that we need.

```{r message=FALSE}
library(USAboundaries)
library(dplyr)
library(sf)
library(leaflet)

# Check that USAboundariesData is available, since it is not on CRAN
avail <- requireNamespace("USAboundariesData", quietly = TRUE)
```

We can load the voting data for the 115th Congress into `md_votes`. We use this package to get the contemporary (2016) boundaries for Congressional districts in Maryland. They are returned as an `sf` object from the [sf](https://github.com/r-spatial/sf/) package.

```{r}
if (avail) {
  md_votes <- read.csv(system.file("extdata", "md-115.csv",
                                   package = "USAboundaries"),
                       colClasses = c("character", "integer", "character", "integer",
                                      "character", "integer", "integer", "integer",
                                      "integer", "integer", "integer",  "numeric",
                                      "numeric", "numeric", "numeric", "numeric"))
  md_districts <- us_congressional(states = "MD")
}
```

In order to map the data, we have to join the voting data to the spatial data.

```{r}
if (avail) {
  md_115 <- md_districts %>% 
   left_join(md_votes, by = c("cd116fp" = "district")) 
}
```

The data has the percentage of votes for Democrats and Republicans. We are going to map the margin that Republicans had over an even vote, so that we can see both the Democrat and Republican results. For a more careful analysis we would have to take account of third parties and write-in votes, but this will serve our purpose.

```{r}
if (avail) {
  md_115$margin_percent <- md_115$percentage_republican - 0.5
}
```

We create a color palette to turn the margin of victory into red and blue colors.

```{r}
if (avail) {
  palette <- colorBin("RdBu", domain = c(-0.3, 0.3), bins = 7, reverse = TRUE)
}
```

We can use the [leaflet](https://rstudio.github.io/leaflet/) package to make the map.

```{r}
if (avail) {
  leaflet(md_115) %>% 
    addTiles() %>% 
    addPolygons(color = "black",
                opacity = 1,
                weight = 1,
                fillColor = ~palette(margin_percent),
                fillOpacity = 1,
                label = ~paste0("District: ", cd116fp))
}
```

We can do the same analysis for the 3rd Congress, thanks to the historical data included in the package. In this case, we will have to map counties rather than Congressional districts. The parties of interest are the Federalists and the Democratic-Republicans.

We start by loading and joining the data. 

```{r}
if (avail) {
  md_03_votes <- read.csv(system.file("extdata", "md-003.csv",
                                      package = "USAboundaries"),
                          stringsAsFactors = FALSE)
  md_03_districts <- us_counties(map_date = "1792-10-01",
                                 resolution = "high", states = "MD")
  md_003 <- md_03_districts %>% 
    left_join(md_03_votes, by = c("id" = "county_ahcb"))
  md_003$margin_percent <- md_003$federalist_percentage - 0.5
}
```

Then we create a new palette function and make the map.

```{r}
if (avail) {
  palette_03 <- colorBin("PRGn", domain = c(-0.5, 0.5), bins = 9)
  leaflet(md_003) %>% 
    addTiles() %>% 
    addPolygons(color = "black",
                opacity = 1,
                weight = 1,
                fillColor = ~palette_03(margin_percent),
                fillOpacity = 1,
                label = ~paste0("County: ", name))
}  
```
