geo.Rmd

---
title: "Geographic filtering with nccsdata"
date: '`r format(Sys.Date(), "%B %d %Y")`'
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
    vignette: >
      %\VignetteIndexEntry{Geographic filtering with nccsdata}
      %\VignetteEngine{knitr::rmarkdown}
      %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.align = "center"
)
library(dplyr)
```

## Overview

This vignette walks through the process of retrieving geographic metadata used for filtering legacy NCCS files. The legacy data consists of several relevant
geographic variables:

 * `STATE`: 2 letter state abbreviation (all caps)
 * `CITY`: Name of the city associated with the address provided in `ADDRESS` (all caps)
 * `FIPS`: [County FIPS Codes](https://transition.fcc.gov/oet/info/maps/census/fips/fips.txt). Federal Information Processing System (FIPS) codes as used by the US Census (5 digit integer)
 
The last variable `FIPS` can be used to match observations based on Census units. This preserves the external validity of geographic units by operationalizing them according to U.S. Census delineations.

In US Census data,`FIPS` are also tied to Core Based Statistical Areas (CBSAs) that consist mutually exclusive Metropolitan, (metros with populations above 50,000) and Micropolitan Statistical Areas (populations above 10,000 and below 50,000). Further details and examples are provided on the Census Crosswalks [page](https://urbaninstitute.github.io/nccs/datasets/census/) of the Urban NCCS Site. Thus, geographic filtering with US Census units requires crosswalking units across multiple levels, such as county and CBSA.

In this vignette, we will first explore these CBSA FIPS codes with the `geo_preview()` function before demonstrating how these CBSA FIPS can be linked to county FIPS codes via `map_countyfips()`.

```{r dependencies}
library(nccsdata)
```

## Exploring CBSA FIPS codes

The `geo_preview()` function allows users to preview and retrieve CBSA FIPS codes and/or their associated metadata from a specific state. In the following code snippet, `geo_preview()` returns the names of all CBSAs and their associated FIPS codes. The `within` argument takes the desired state, in abbreviated form, as input while the `geo` argument returns the specified columns.

```{r}
geo_preview( geo=c("cbsa","cbsafips"), within="FL", type="metro" )
```

In the above code chunk, the function returns the names of all CBSAs and their
associated FIPS codes. `within` takes the desired state as input while `geo` returns
the specified columns. `geo` can also be used to return county metadata.

```{r}
geo_preview(geo = c("cbsa", "county", "cbsafips"), within = "FL", type = "metro")
```


## Metropolitan and Micropolitan Data

Since CBSAs include a combination of [metropolitan or micropolitan statistical areas](https://www.census.gov/programs-surveys/metro-micro/about.html), `geo_preview()` allows the user to select either unit using the `type` argument.

The below code snippet returns the CBSA names and FIPS codes for all metropolitan statistical areas in Wyoming.

```{r}
geo_preview(geo = c("cbsa","cbsafips"), within = "WY", type = "micro")
```

Setting `type` to `micro` returns data for micropolitan statistical areas.

```{r}
geo_preview(geo = c("cbsa","cbsafips"), within = "WY", type = "metro")
```

## Exploring CSA FIPS

In addition to CBSAs, `geo_preview()` can also retrieve metadata for [Combined Statistical Areas](https://en.wikipedia.org/wiki/Combined_statistical_area) (CSAs).

CSAs (populations that form a coherent commercial and commuting zone) are created by identifying adjacent micropolitant and metropolitan statistical areas that constitute a coherent economic region.

The code snippet below returns all CSA names and FIPS codes for metropolitan statistical areas in Virginia.

```{r}
geo_preview(geo = c("cbsa", "cbsafips", "csa","csafips"), 
            within = "VA", 
            type = "metro")
```

Since CSAs are combination of various Micropolitan and Metropolitan areas, not all CBSAs will fall under a CSA, and hence CSA FIPS are only available for existing CSAs.

## Filtering Legacy Data with County FIPS codes

After retrieving the desired CBSA/CSA FIPS codes, `map_countyfips()` can be used to match these with county FIPS codes present in the legacy data, retrieved with `get_data()`. Downloaded data can then be filtered using these county FIPS codes as shown below.

```{r}
# Retrive CBSA FIPS from NY
cbsa_ny <- geo_preview(geo = c("cbsa", "cbsafips"), 
                       within = "NY")

# Map these to county FIPS codes
ny_countyfips <- map_countyfips(geo.cbsafips = cbsa_ny$cbsafips)

# Pull core data for the year 2015
core_2015 <- get_data(dsname = "core",
                      time = "2015",
                      scope.orgtype = "NONPROFIT",
                      scope.formtype = "PZ")

# Filter with NY county FIPS
core_2015_nyfips <- core_2015 %>% 
  dplyr::filter(FIPS %in% ny_countyfips)
```