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

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

## Plotting

Plots of US maps in R usually lack Alaska, Hawaii, and Puerto Rico. The reason is plotting takes the literal longitude and latitude coordinates and maps it to a cartesian x-y coordinate graph. Alaska, Hawaii, and Puerto Rico are very far from the mainland US when using this so it can be unwieldy to include them. The `usmap` package solves this issue by providing data frames which have Alaska, Hawaii, and Puerto Rico moved to a convenient spot just to the bottom left of the contiguous United States.

#### Blank US state map

```{r, fig.align='center', fig.width=7}
usmap::plot_usmap()
```

#### Blank US county map

```{r, fig.align='center', fig.width=7}
usmap::plot_usmap(regions = "counties")
```

## Raw map data

The raw US map data for counties or states can be obtained for further manipulation (and joining with data). The default `regions` is `"states"`.
 
```{r, eval = FALSE}
states_df <- usmap::us_map()
counties_df <- usmap::us_map(regions = "counties")
```


## FIPS codes

FIPS codes are defined in the Federal Information Processing Standards by the US government. One usage is uniquely identifying US states and counties. Downloaded data sets from the [US Census](https://www.census.gov/data.html) will often include FIPS codes as identifiers so it can be helpful to know what a FIPS code represents. The functions in `usmap` are built around the FIPS code identification system and so convenience methods for accessing them and performing reverse-lookups have been included.

#### State/County FIPS lookup

```{r}
# Get FIPS code for a state
usmap::fips(state = "MA")
usmap::fips(state = "Massachusetts")

# Get FIPS code for a county
usmap::fips(state = "NJ", county = "Bergen")
usmap::fips(state = "CA", county = "Orange County")

# The parameters are NOT case sensitive!
usmap::fips(state = "ca", county = "oRanGe cOUNty")
```

#### FIPS reverse lookup

If the FIPS code is known and want to see what state/county it corresponds to, use the reverse lookup function `fips_info`.

```{r}
usmap::fips_info(c("30", "33", "34"))
```

```{r}
usmap::fips_info(c("01001", "01003", "01005", "01007"))
```

#### Further reading

More information about FIPS can be read [here](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standards).
  
---

> “A map is the greatest of all epic poems. Its lines and colors show the realization of great dreams.”
> - _Gilbert H. Grosvenor, Editor of National Geographic (1903 - 1954)_