---
title: "get-started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

This R package includes contemporary state, county, and Congressional
district boundaries, and zip code tabulation area centroids. It also
includes historical boundaries from 1629 to 2000 for states and counties
from the Newberry Library's [Atlas of Historical County
Boundaries](https://publications.newberry.org/ahcbp/) and historical
city population data from Erik Steiner's "[United States Historical City
Populations,
1790-2010](https://github.com/cestastanford/historical-us-city-populations)."

The package has helper data, including a table of state names,
abbreviations, and FIPS codes, and functions and data to get [State
Plane Coordinate
System](https://en.wikipedia.org/wiki/State_Plane_Coordinate_System)
projections as EPSG codes or PROJ.4 strings.

This package can serve a number of purposes. The spatial data can be
joined to any other kind of data in order to make thematic maps. Unlike
other R packages, this package also contains historical data for use in
analyses of the recent or more distant past.

## Use

This package provides a set of functions, one for each of the types of
boundaries that are available. These functions have a consistent
interface.

Passing a date to `us_states()`, `us_counties()`, and `us_cities()`
returns the historical boundaries for that date. If no date argument is
passed, then contemporary boundaries are returned. The functions
`us_congressional()` and `us_zipcodes()` only offer contemporary
boundaries.

For almost all functions, pass a character vector of state names or
abbreviations to the `states =` argument to return only those states or
territories.

For certain functions, more or less detailed boundary information is
available by passing an argument to the `resolution =` argument.

See the examples below to see how the interface works, and see the
documentation for each function for more details.

```{r}
library(USAboundaries) 

# Check that USAboundariesData is available, since it is not on CRAN.
# And sf as it's not a dependency.
if(all(requireNamespace("USAboundariesData", quietly = TRUE) & requireNamespace("sf", quietly = TRUE))){
  avail = TRUE
} else {
  avail = FALSE
}

# Lookup for state abbr and state codes
state_codes[state_codes$state_abbr == "WI",]

# Returns an sf object
us_states(resolution = "low", states = "WI")

# Returns a PROJ4
state_plane(state = "WI", type = "proj4")
```

```{r}
if (avail) {
  library(sf)
  states_1840 <- us_states("1840-03-12")
  plot(st_geometry(states_1840))
  title("U.S. state boundaries on March 3, 1840")
  
  states_contemporary <- us_states()
  plot(st_geometry(states_contemporary))
  title("Contemporary U.S. state boundaries")
  
  counties_va_1787 <- us_counties("1787-09-17", states = "Virginia")
  plot(st_geometry(counties_va_1787))
  title("County boundaries in Virginia in 1787")
  
  counties_va <- us_counties(states = "Virginia")
  plot(st_geometry(counties_va))
  title("Contemporary county boundaries in Virginia")
  
  counties_va_highres <- us_counties(states = "Virginia", resolution = "high")
  plot(st_geometry(counties_va_highres))
  title("Higher resolution contemporary county boundaries in Virginia")
  
  congress <- us_congressional(states = "California")
  plot(st_geometry(congress))
  title("Congressional district boundaries in California")
}
```

## State plane projections

The `state_plane()` function returns EPSG codes and PROJ.4 strings for
the State Plane Coordinate System. You can use these to use suitable
projections for specific states.

```{r}
if (avail) {
  va <- us_states(states = "VA", resolution = "high")
  plot(st_geometry(va), graticule = TRUE)
  
  va_projection <- state_plane("VA")
  va <- st_transform(va, va_projection)
  plot(st_geometry(va), graticule = TRUE)
}