README.Rmd

---
output: github_document
editor_options: 
  chunk_output_type: console
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
library(knitr)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
options(tibble.print_min = 6)
```

# usa <a href='https:/k5cents.github.io/usa/'><img src='man/figures/logo.png' align="right" height="139" /></a>

<!-- badges: start -->
[![Lifecycle: experimental][life_badge]][life_link]
[![CRAN status][cran_badge]][cran_link]
![Downloads][dl_badge]
[![Codecov test coverage][cov_badge]][cov_link]
[![R build status][ga_badge]][ga_link]
<!-- badges: end -->

The goal of 'usa' is to provide updated versions of the 'datasets' objects
included with R. When attached, this package **overwrites** these original
vectors with information on all fifty states, the District of Columbia, and
Puerto Rico. As of now, information on the other territories are provided in
separate objects.

## Installation

You can install the release version of 'usa' from [CRAN][cran] with:

```{r cran, eval=FALSE}
install.packages("usa")
```

Or the development version from [GitHub][gh] with:

```{r remote, eval=FALSE}
# install.packages("remotes")
remotes::install_github("k5cents/usa")
```

## Base Data

R ships with eight outdated objects in the 'datasets' package: 7 vectors and a
matrix of statistics from the 1970's.

```{r enframe_vectors, echo=FALSE}
base.vectors <- data.frame(
  name = state.name,
  abb = state.abb,
  region = state.region,
  division = state.division,
  area = state.area,
  center.x = state.center$x,
  center.y = state.center$y
)
```

```{r vectors}
head(base.vectors)
```

```{r state.x77}
head(state.x77)
```

## New Data

This package contains new, expanded versions of these vectors.

```{r join_states, message=FALSE}
setdiff(usa::state.abb, datasets::state.abb)
unique(usa::state.region)
show(usa::territory.abb)
```

The package contains [tibbles][tib] identifying the states and providing updated
facts and figures.

```{r states}
usa::states
```

```{r facts}
usa::facts
```

```{r territory}
usa::territory
```

ZIP codes from the archived ['zipcode'][zip] package are also included

```{r zipcodes}
usa::zipcodes
```

These synthetic survey respondents from [Pew][pew] provide a statistically
accurate sample of the American people.

```{r people}
dplyr::select(usa::people, 1:8)
```

***

Please note that the 'usa' project is released with a 
[Contributor Code of Conduct][coc]. By
contributing to this project, you agree to abide by its terms.

<!-- refs: start -->
[life_badge]: https://img.shields.io/badge/lifecycle-maturing-blue.svg
[life_link]: https://lifecycle.r-lib.org/articles/stages.html#experimental
[cran_badge]: https://www.r-pkg.org/badges/version/usa
[cran_link]: https://CRAN.R-project.org/package=usa
[ga_badge]: https://github.com/k5cents/usa/workflows/R-CMD-check/badge.svg
[ga_link]: https://github.com/k5cents/usa/actions
[cov_badge]: https://codecov.io/gh/k5cents/usa/graph/badge.svg?token=ubolhKW81u
[cov_link]: https://app.codecov.io/gh/k5cents/usa?branch=master
[dl_badge]: https://cranlogs.r-pkg.org/badges/grand-total/usa
[tib]: https://tibble.tidyverse.org/
[cran]: https://cran.r-project.org/package=usa
[gh]: https://github.com/k5cents/usa
[zip]: https://cran.r-project.org/package=zipcode
[pew]: https://www.pewresearch.org/methods/2018/01/26/for-weighting-online-opt-in-samples-what-matters-most/
[coc]: https://k5cents.github.io/usa/CODE_OF_CONDUCT.html
<!-- refs: end -->