updated vignette with new data

Author: jacciz

.Rbuildignore

@@ -16,3 +16,5 @@
 ^CRAN-RELEASE$
 ^[.]?air[.]toml$
 ^codemeta.json$
+^doc$
+^Meta$

.gitignore

@@ -2,3 +2,6 @@
 .Rhistory
 .RData
 .Ruserdata
+inst/doc
+/doc/
+/Meta/

R/state_codes.R

@@ -12,8 +12,8 @@
 #' }
 #'
 #' @references U.S. Census Bureau,
-#'   \href{https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.2014.html}{U.S. Gazeteer Files} (2014).
+#'   \href{https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.2024.html}{U.S. Gazeteer Files} (2024).
 #'
-#'   \href{https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code}{Federal Information Processing Standard state code}, Wikipedia (accessed July 23,
-#'   2015).
+#'   \href{https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code}{Federal Information Processing Standard state code}, Wikipedia (accessed October 12,
+#'   2025).
 "state_codes"

R/us_cities.R

@@ -29,6 +29,7 @@
 #'
 #' @export
 us_cities <- function(map_date = NULL, states = NULL) {
+  # TODO maybe return all the cities to see trend over time?
   if (is.null(map_date)) {
     message("City populations for contemporary data come from the 2010 census.")
     map_date <- 2010

R/us_counties.R

@@ -72,6 +72,7 @@ us_counties <- function(
     shp <- filter_by_states(shp, states)
   } else {
     map_date <- as.Date(map_date)
+    # TODO better error message?
     stopifnot(
       as.Date("1636-12-30") <= map_date,
       map_date <= as.Date("2000-12-31")

R/us_states.R

@@ -1,6 +1,6 @@
 #' State boundaries (contemporary and historical)
 #'
-#' Get the current (2024) boundaries for U.S states from the U.S. Census Bureau,
+#' Get the current (2019) boundaries for U.S states from the U.S. Census Bureau,
 #' or get historical state boundaries for dates between 3 September 1783 and 31
 #' December 2000.
 #'

R/usaboundaries-package.R

@@ -0,0 +1,26 @@
+#' USAboundaries: Historical and Contemporary Boundaries of the United States of
+#' America
+#'
+#' This package provides contemporary (2014) boundaries for states, counties,
+#' zip code tabulation areas, and congressional districts in the United States
+#' of America. This data is provided by the U.S. Census Bureau.
+#'
+#' This package also provides spatial objects with historical boundaries of
+#' states or counties in the United States of America from 1629 to 2000. It
+#' provides data from the \href{https://publications.newberry.org/ahcbp/}{Atlas
+#' of Historical County Boundaries}. The copyright to the historical data used
+#' in this package is owned by the Newberry Library, and it is included in the
+#' \code{USAboundariesData} package under the terms of the
+#' \href{https://creativecommons.org/licenses/by-nc-sa/2.5/}{Creative Commons
+#' Attribution-NonCommercial-ShareAlike 2.5 Generic} (CC BY-NC-SA 2.5) license.
+#'
+#' The code in this package is copyrighted by
+#' \href{https://lincolnmullen.com}{Lincoln Mullen}, and is released under the
+#' terms of the \href{https://opensource.org/licenses/MIT}{MIT License}.
+#'
+#' @name USAboundaries
+NULL
+
+if (getRversion() >= "2.15.1") {
+  utils::globalVariables(c("state_codes", "state_proj"))
+}

R/usboundaries-package.r

@@ -1,7 +1,7 @@
 #' USAboundaries: Historical and Contemporary Boundaries of the United States of
 #' America
 #'
-#' This package provides contemporary (2014) boundaries for states, counties,
+#' This package provides contemporary (2024) boundaries for states, counties,
 #' zip code tabulation areas, and congressional districts in the United States
 #' of America. This data is provided by the U.S. Census Bureau.
 #'

README.Rmd

@@ -1,6 +1,9 @@
 ---
 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 -->
@@ -17,38 +20,47 @@ set.seed(87737)
 # USAboundaries
 
 <!-- [![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/USAboundaries)](https://cran.r-project.org/package=USAboundaries) -->
-[![JOSS Status](https://joss.theoj.org/papers/3458a33133aa6c069ab4dd8df0b5f3b5/status.svg)](https://doi.org/10.21105/joss.00314)
+
+[![JOSS
+Status](https://joss.theoj.org/papers/3458a33133aa6c069ab4dd8df0b5f3b5/status.svg)](https://doi.org/10.21105/joss.00314)
 [![R-CMD-check](https://github.com/ropensci/USAboundaries/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/USAboundaries/actions/workflows/R-CMD-check.yaml)
-[![Codecov test coverage](https://codecov.io/gh/ropensci/USAboundaries/graph/badge.svg)](https://app.codecov.io/gh/ropensci/USAboundaries)
+[![Codecov test
+coverage](https://codecov.io/gh/ropensci/USAboundaries/graph/badge.svg)](https://app.codecov.io/gh/ropensci/USAboundaries)
 ![r-universe](https://ropensci.r-universe.dev/USAboundaries/badges/version)
 
-
 ## Overview
 
-This R package includes contemporary state, county, and Congressional district
-boundaries, as well as 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/), as well as historical
+Note: Due to U.S. Government Shutdown, state boundaries are unable to be
+updated.
+
+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 some 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)
 
+The package has some 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
+
+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.
+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.
+If you use this package in your research, we would appreciate a
+citation.
 
 ```{r}
 citation("USAboundaries")
@@ -58,41 +70,45 @@ citation("USAboundaries")
 
 You can install this package from CRAN.
 
-```
+```         
 install.packages("USAboundaries", repos = c("https://ropensci.r-universe.dev"))
 ```
 
-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.
+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 the development versions 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.
+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.
+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.
+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.
+See the examples below to see how the interface works, and see the
+documentation for each function for more details.
 
 ```{r}
 library(USAboundaries) 
@@ -125,9 +141,9 @@ 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.
+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")
@@ -141,33 +157,49 @@ 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
+[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 which are not provided by this
-package, consider using the [tigris](https://cran.r-project.org/package=tigris)
-package, which downloads those shapefiles.
+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.
 
-## License
+USAboundaries differs from tigris in a few ways:
+
+-   Boundary files are contained within the data package while tigris
+    downloads the files from US Census.
 
-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.
+-   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.
 
-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
+-   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.
+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](http://lincolnmullen.com)
-and is released under the MIT license.
+All code in this package is copyright [Lincoln
+Mullen](http://lincolnmullen.com) and is released under the MIT license.
 
----
-[![rOpenSci footer](https://ropensci.org//public_images/github_footer.png)](https://ropensci.org/)
+------------------------------------------------------------------------
+
+[![rOpenSci
+footer](https://ropensci.org//public_images/github_footer.png)](https://ropensci.org/)

README.md

@@ -14,24 +14,29 @@ coverage](https://codecov.io/gh/ropensci/USAboundaries/graph/badge.svg)](https:/
 
 ## Overview
 
+Note: Due to U.S. Government Shutdown, state boundaries are unable to be
+updated.
+
 This R package includes contemporary state, county, and Congressional
-district boundaries, as well as 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/), as well as
-historical city population data from Erik Steiner’s “[United States
-Historical City Populations,
+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 some 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.
 
-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
+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.
@@ -193,11 +198,23 @@ Each function returns an `sf` object from the
 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 which are not provided by
-this package, consider using the
+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