-
Notifications
You must be signed in to change notification settings - Fork 10
Expand file tree
/
Copy pathREADME.Rmd
More file actions
202 lines (153 loc) · 7.17 KB
/
README.Rmd
File metadata and controls
202 lines (153 loc) · 7.17 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
---
output: github_document
pagetitle: Historical and Contemporary Boundaries of the United States of America
editor_options:
markdown:
wrap: 72
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-"
)
set.seed(87737)
```
# USAboundaries
<!-- [](https://cran.r-project.org/package=USAboundaries) -->
[](https://doi.org/10.21105/joss.00314)
[](https://github.com/ropensci/USAboundaries/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/ropensci/USAboundaries)
## 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. See the ["A sample analysis
using
USAboundaries"](https://docs.ropensci.org/USAboundaries/articles/usaboundaries-sample-analysis.html)
vignette for an example of how the package can be used for both
historical and contemporary maps.
## Citation
If you use this package in your research, we would appreciate a
citation.
```{r}
citation("USAboundaries")
```
## Installation
You can install this package by:
```
pak::pkg_install("ropensci/USAboundaries")
```
Almost all of the data for this package is provided by the
[USAboundariesData
package](https://github.com/ropensci/USAboundariesData). That package
will be automatically installed (with your permission) from the
[rOpenSci package repository](https://ropensci.r-universe.dev) the first
time that you need it.
Or you can install from GitHub:
```
install.packages("USAboundaries", repos = c("https://ropensci.r-universe.dev"))
install.packages("USAboundariesData", repos = c("https://ropensci.r-universe.dev"))
```
## 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)
library(sf) # for plotting and projection methods
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}
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)
```
## Related packages
Each function returns an `sf` object from the
[sf](https://cran.r-project.org/package=sf) package, which can be mapped
using the [leaflet](https://cran.r-project.org/package=leaflet) or
[ggplot2](https://cran.r-project.org/package=ggplot2) packages.
If you need U.S. Census Bureau boundary files not provided by this
package, consider using the
[tigris](https://cran.r-project.org/package=tigris) package, which
downloads those shapefiles.
USAboundaries differs from tigris in a few ways:
- Boundary files are contained within the data package while tigris
downloads the files from US Census.
- USAboundaries uses Cartographic Boundary Files (CBFs) that are
simplified representations of TIGER/Line shapefiles. They are much
smaller in file size, making rendering much faster on the screen.
- Data files contain historical boundary and population data dating as
far back as 1629.
## License
The historical boundary data provided in this package is available under
the CC BY-NC-SA 2.5 license from John H. Long, et al., [Atlas of
Historical County Boundaries](https://publications.newberry.org/ahcbp/),
Dr. William M. Scholl Center for American History and Culture, The
Newberry Library, Chicago (2010). Please cite that project if you use
this package in your research and abide by the terms of their license if
you use the historical information.
The historical population data for cities is provided by U.S. Census
Bureau and Erik Steiner, Spatial History Project, Center for Spatial and
Textual Analysis, Stanford University. See the data in [this
repository](https://github.com/cestastanford/historical-us-city-populations).
The contemporary data is provided by the U.S. Census Bureau and is in
the public domain.
All code in this package is copyright [Lincoln
Mullen](https://lincolnmullen.com) and is released under the MIT license.
------------------------------------------------------------------------
[](https://ropensci.org/)