---
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 119th 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 2024 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 119th Congress into `md_votes`. We use this
package to get the contemporary (2024) boundaries for Congressional districts in
Maryland. `us_congressional()` returns an `sf` object from the
[sf](https://github.com/r-spatial/sf/) package.

```{r}
if (avail) {
  md_votes <- read.csv(system.file("extdata", "md-119.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_119 <- md_districts %>% 
   left_join(md_votes, by = c("cd119fp" = "district")) 
}
```

The data contains 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_119$margin_percent <- md_119$percent_vote_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.4, 0.4), bins = 7, reverse = TRUE)
}
```

We can use the [leaflet](https://rstudio.github.io/leaflet/) package to make the
map.
```{r, out.width='100%'}
if (avail) {
  leaflet(md_119) %>%
    addTiles() %>%
    addPolygons(color = "black",
                opacity = 1,
                weight = 1,
                fillColor = ~palette(margin_percent),
                fillOpacity = 1,
                label = ~paste0("District: ", cd119fp))
}
```
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"))
  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, out.width='100%'}
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))
}  
```
