Updating for 2022: Pine Valley absorbed by Pine Hill.

 1) No changes to GEOIDs or names
 2) Max year is now 2022.
 3) Pine Valley disappears in 2022.
 4) Documentation and tests updated.
 5) Added NEWS.md
 6) Bump version to 1.1.0

DESCRIPTION

@@ -1,12 +1,12 @@
 Package: njmunicipalities
 Type: Package
 Title: NJ Municipalities data package
-Version: 1.0.0
+Version: 1.1.0
 Authors@R: 
     person("Tor", "Gunston", , "tor.gunston@protonmail.com", role = c("aut", "cre"))
-Description: NJ Municipalities, 2000-2021.
+Description: NJ Municipalities, 2000-2022.
     Name and GEOID for every NJ municipality and county, for the
-    years 2000-2021.
+    years 2000-2022.
 License: CC0
 Encoding: UTF-8
 LazyData: true

NEWS.md

@@ -0,0 +1,9 @@
+# njmunicipalities 1.1.0
+
+* Added a `NEWS.md` file to track changes to the package.
+
+* Updating for 2022: Pine Valley absorbed by Pine Hill.  
+    * No changes to GEOIDs or names.
+    * Max year is now 2022.
+    * Pine Valley disappears in 2022.
+

R/get_municipalities.R

@@ -1,5 +1,5 @@
 MIN_YEAR <- 2000
-MAX_YEAR <- 2021
+MAX_YEAR <- 2022
 YEARS <- MIN_YEAR:MAX_YEAR
 
 #' Internal function get_municipalities_
@@ -36,14 +36,14 @@ get_municipalities_ <- function(year = MAX_YEAR, geoid_reference_year = year) {
 #'
 #' To use the GEOIDs from a different year, specify `geoid_year`.
 #' If `year` < 2013 and `geoid_year` >= 2013, then the `GEOID` for
-#' for Princeton township will the GEOID in use until 2013, when
+#' Princeton township will the GEOID in use until 2013, when
 #' the township ceased to exist.
 #'
 #' The reference-year GEOID will replace the actual GEOID, unless
 #' `geoid_ref_as_ref_column` is `TRUE`, in which case the reference
 #' year GEOID will be put in a separate column called `GEOID_ref`.
 #'
-#' @param year The year, from 2000 to 2021. The default is 2021.
+#' @param year The year, from 2000 to 2022. The default is 2022.
 #' @param geoid_year The year to use for GEOIDs
 #' @param geoid_ref_as_ref_column If TRUE, add a separate column for the reference GEOID
 #' @return A table with `GEOID`, `county` and `municipality`

README.Rmd

@@ -20,7 +20,7 @@ knitr::opts_chunk$set(
 <!-- badges: end -->
 
 This is a data package for R that contains every county
-and municipality in New Jersey, from 2000 to 2021.
+and municipality in New Jersey, from 2000 to 2022.
 
 ## Installation
 
@@ -31,9 +31,9 @@ You can install the development version of njmunicipalities from [GitHub](https:
 devtools::install_github("tor-gu/njmunicipalities")
 ```
 
-## Changes in NJ municipalites, 2000-2021
+## Changes in NJ municipalites, 2000-2022
 
-Over the period 2000-2021, there have been several changes to
+Over the period 2000-2022, there have been several changes to
 the list of municipalities in New Jersey:
 
 * In 2005, South Belmar became Lake Como. The US Census assigned
@@ -43,21 +43,22 @@ a new GEOID to Lake Como.
 * In 2009, West Paterson became Woodland Park, and was assigned a new GEOID.
 * In 2010, Caldwell borough was assigned a new GEOID from the the US Census, though there was no name change at this time.
 * In 2013, Princeton borough and Princeton township merged. The merged municipality retained the Princeton borough GEOID, though the US Census started using the name 'Princeton' in place of 'Princeton borough' for the merged municipality.
+* In 2022, Pine Valley was absorbed by Pine Hill.
 
 This package will return municipality tables for any year from 2000 to
-2021, and provides tools for dealing the changes from year to year.
+2022, and provides tools for dealing the changes from year to year.
 
 ## Examples
 #### Get a table of municipalities
 Function `get_municipalities` returns a table of municipalities for a
-given year. The default is year 2021.
+given year. The default is year 2022.
 ```{r}
 library(njmunicipalities)
 
-# Municipality table for 2021
+# Municipality table for 2022
 get_municipalities() |> head(n=5)
 ```
-If the year is specified (from 2000 to 2021), the table will reflect the names and US Census GEOIDs in effect for that year. Here is the list for 2007.
+If the year is specified (from 2000 to 2022), the table will reflect the names and US Census GEOIDs in effect for that year. Here is the list for 2007.
 ```{r}
 # Municipality list for 2007
 get_municipalities(2007) |> head(n=5)
@@ -112,7 +113,7 @@ get_geoid_cross_references(2005, 2010:2020) |>
 ```
 
 #### Dealing with the Princetons
-Princeton township and Princeton borough merged in 2013. Because the merged municipality retained Princeton borough's GEOID, Princeton township disappears in 2013. This is the only example of a disappearing municipality in the package (but see [Pine Valley and the year 2022](#pine-valley-and-the-year-2022)).
+Princeton township and Princeton borough merged in 2013. Because the merged municipality retained Princeton borough's GEOID, Princeton township disappears in 2013. This is one of two examples of a disappearing municipality in the package (see [Dealing with Pine Valley and Pine Hill](#dealing-with-pine-valley-and-pine-hill)).
 
 The functions `get_municipality` and `get_geoid_cross_references` will return `NA` for a reference year GEOID after 2012 for Princeton township:
 ```{r}
@@ -141,16 +142,20 @@ election_by_municipality_combined |>
   head(5)
 ```
 
-#### Pine Valley and the year 2022
-In 2022, Pine Valley borough was merged into Pine Hill borough. The current version of this package does not cover the year 2022 because the [US Census Gazetteer](https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.html) for 2022 has not yet been published.
+#### Dealing with Pine Valley and Pine Hill
+In 2022, Pine Valley borough was merged into Pine Hill borough. 
 
-As a conveniene for dealing with 2022 datasets, this package includes constants `PINE_VALLEY_BORO_GEOID` and `PINE_HILL_BORO_GEOID`.  
+The functions `get_municipality` and `get_geoid_cross_references` will return `NA` for a reference year GEOID after 2021 for Pine Valley:
+```{r}
+# Pine Valley existed in 2021 but not 2022
+get_municipalities(2021, geoid_year = 2022) |>
+  dplyr::filter(is.na(GEOID))
+```
+For convenience in dealing with this issue, this package includes constants `PINE_VALLEY_BORO_GEOID` and `PINE_HILL_BORO_GEOID`.  
 ```{r}
 c(PINE_VALLEY_BORO_GEOID, PINE_HILL_BORO_GEOID)
 ```
 
-
-
 #### County list
 For convenience, this package also includes a table of counties and
 their GEOIDS. There have been no changes to New Jersey counties from 2000 to 2021.

README.md

@@ -9,7 +9,7 @@
 <!-- badges: end -->
 
 This is a data package for R that contains every county and municipality
-in New Jersey, from 2000 to 2021.
+in New Jersey, from 2000 to 2022.
 
 ## Installation
 
@@ -21,9 +21,9 @@ You can install the development version of njmunicipalities from
 devtools::install_github("tor-gu/njmunicipalities")
 ```
 
-## Changes in NJ municipalites, 2000-2021
+## Changes in NJ municipalites, 2000-2022
 
-Over the period 2000-2021, there have been several changes to the list
+Over the period 2000-2022, there have been several changes to the list
 of municipalities in New Jersey:
 
 -   In 2005, South Belmar became Lake Como. The US Census assigned a new
@@ -40,21 +40,22 @@ of municipalities in New Jersey:
     municipality retained the Princeton borough GEOID, though the US
     Census started using the name ‘Princeton’ in place of ‘Princeton
     borough’ for the merged municipality.
+-   In 2022, Pine Valley was absorbed by Pine Hill.
 
 This package will return municipality tables for any year from 2000 to
-2021, and provides tools for dealing the changes from year to year.
+2022, and provides tools for dealing the changes from year to year.
 
 ## Examples
 
 #### Get a table of municipalities
 
 Function `get_municipalities` returns a table of municipalities for a
-given year. The default is year 2021.
+given year. The default is year 2022.
 
 ``` r
 library(njmunicipalities)
 
-# Municipality table for 2021
+# Municipality table for 2022
 get_municipalities() |> head(n=5)
 #> # A tibble: 5 × 3
 #>   GEOID      county          municipality        
@@ -66,7 +67,7 @@ get_municipalities() |> head(n=5)
 #> 5 3400108710 Atlantic County Buena Vista township
 ```
 
-If the year is specified (from 2000 to 2021), the table will reflect the
+If the year is specified (from 2000 to 2022), the table will reflect the
 names and US Census GEOIDs in effect for that year. Here is the list for
 2007.
 
@@ -186,9 +187,9 @@ get_geoid_cross_references(2005, 2010:2020) |>
 
 Princeton township and Princeton borough merged in 2013. Because the
 merged municipality retained Princeton borough’s GEOID, Princeton
-township disappears in 2013. This is the only example of a disappearing
-municipality in the package (but see [Pine Valley and the year
-2022](#pine-valley-and-the-year-2022)).
+township disappears in 2013. This is one of two examples of a
+disappearing municipality in the package (see [Dealing with Pine Valley
+and Pine Hill](#dealing-with-pine-valley-and-pine-hill)).
 
 The functions `get_municipality` and `get_geoid_cross_references` will
 return `NA` for a reference year GEOID after 2012 for Princeton
@@ -240,15 +241,24 @@ election_by_municipality_combined |>
 #> 5  2004 President 3402160900 Libertarian Party     40
 ```
 
-#### Pine Valley and the year 2022
+#### Dealing with Pine Valley and Pine Hill
 
-In 2022, Pine Valley borough was merged into Pine Hill borough. The
-current version of this package does not cover the year 2022 because the
-[US Census
-Gazetteer](https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.html)
-for 2022 has not yet been published.
+In 2022, Pine Valley borough was merged into Pine Hill borough.
 
-As a conveniene for dealing with 2022 datasets, this package includes
+The functions `get_municipality` and `get_geoid_cross_references` will
+return `NA` for a reference year GEOID after 2021 for Pine Valley:
+
+``` r
+# Pine Valley existed in 2021 but not 2022
+get_municipalities(2021, geoid_year = 2022) |>
+  dplyr::filter(is.na(GEOID))
+#> # A tibble: 1 × 3
+#>   GEOID county        municipality       
+#>   <chr> <chr>         <chr>              
+#> 1 <NA>  Camden County Pine Valley borough
+```
+
+For convenience in dealing with this issue, this package includes
 constants `PINE_VALLEY_BORO_GEOID` and `PINE_HILL_BORO_GEOID`.
 
 ``` r

data-raw/municipalities.R

@@ -3,8 +3,11 @@ gz_2000_file <- fs::path("data-raw", "gazetteer_2000.txt")
 
 counties <- readr::read_tsv(counties_file, col_types = "cc")
 gz_2000 <- readr::read_fwf(gz_2000_file,
-                           readr::fwf_widths(c(2, 10, 60), c("state","GEOID","municipality"))
-) |> dplyr::mutate(municipality = stringr::str_trim(municipality),
+                           readr::fwf_widths(
+                             c(2, 10, 60),
+                             c("state","GEOID","municipality"))
+  ) |>
+  dplyr::mutate(municipality = stringr::str_trim(municipality),
                    GEOID = as.character(GEOID)) |>
   dplyr::filter(municipality != "County subdivisions not defined") |>
   dplyr::select(-state) |>
@@ -16,7 +19,7 @@ gz_2000 <- readr::read_fwf(gz_2000_file,
 municipalities <- gz_2000 |>
   dplyr::mutate(GEOID_Y2K = GEOID,
                 first_year = 2000,
-                final_year = 2021) |>
+                final_year = 2022) |>
   dplyr::relocate(GEOID_Y2K)
 
 municipality_updates <- tibble::tribble(
@@ -28,16 +31,17 @@ municipality_updates <- tibble::tribble(
   "3403179820", 2008, # West Paterson became Woodland Park in 2009
   "3402160900", 2012, # Princeton borough became just-plain Princeton in 2013
   "3402160915", 2012, # Princeton twp was absorbed by Princeton boro in 2013
+  "3400758920", 2021, # Pine Valley boro was absorbed by Pine Hill boro in 2022
 )
 
 municipality_inserts <- tibble::tribble(
   ~GEOID_Y2K,  ~GEOID,      ~county,          ~municipality,         ~first_year,~final_year,
-  "3401309220","3401309250","Essex County",   "Caldwell borough",     2010,      2021,
-  "3402177210","3402163850","Mercer County",  "Robbinsville township",2008,      2021,
-  "3402568670","3402537560","Monmouth County","Lake Como borough",    2005,      2021,
-  "3402918130","3402973125","Ocean County",   "Toms River township",  2007,      2021,
-  "3403179820","3403182423","Passaic County", "Woodland Park borough",2009,      2021,
-  "3402160900","3402160900","Mercer County",  "Princeton",            2013,      2021,
+  "3401309220","3401309250","Essex County",   "Caldwell borough",     2010,      2022,
+  "3402177210","3402163850","Mercer County",  "Robbinsville township",2008,      2022,
+  "3402568670","3402537560","Monmouth County","Lake Como borough",    2005,      2022,
+  "3402918130","3402973125","Ocean County",   "Toms River township",  2007,      2022,
+  "3403179820","3403182423","Passaic County", "Woodland Park borough",2009,      2022,
+  "3402160900","3402160900","Mercer County",  "Princeton",            2013,      2022,
 )
 
 municipalities <- municipalities |>

tests/testthat/test-get_municipalities.R

@@ -1,11 +1,11 @@
 test_that("get_municipalities handles bad year", {
   expect_error(get_municipalities(1999))
-  expect_error(get_municipalities(2022))
+  expect_error(get_municipalities(2023))
 })
 
 test_that("get_municipalities handles bad reference year", {
   expect_error(get_municipalities(2010, 1999))
-  expect_error(get_municipalities(2010, 2022))
+  expect_error(get_municipalities(2010, 2023))
 })
 
 
@@ -14,10 +14,12 @@ test_that("get_municipalities returns the correct table size", {
   muni_2012 <- get_municipalities(2012)
   muni_2013 <- get_municipalities(2013) # The year princeton township disappeared
   muni_2021 <- get_municipalities(2021)
+  muni_2022 <- get_municipalities(2022) # The year pine valley disappeared
   expect_equal(nrow(muni_2000), 566)
   expect_equal(nrow(muni_2012), 566)
   expect_equal(nrow(muni_2013), 565)
   expect_equal(nrow(muni_2021), 565)
+  expect_equal(nrow(muni_2022), 564)
 })
 
 test_that("get_municipalities handles Caldwell", {
@@ -42,6 +44,14 @@ test_that("get_municipalities handles Princeton", {
   expect_true( boro_geoid %in% muni_2013 )
 })
 
+test_that("get_municipalities handles Pine Valley", {
+  pv_geod <- "3400758920"
+  muni_2021 <- get_municipalities(2021) %>% dplyr::pull(GEOID)
+  muni_2022 <- get_municipalities(2022) %>% dplyr::pull(GEOID)
+  expect_true( pv_geod %in% muni_2021 )
+  expect_false( pv_geod %in% muni_2022 )
+})
+
 test_that("get_municipalities handles reference year in past", {
   muni_2021_2000 <- get_municipalities(2021, geoid_year = 2000)
   muni_2021_2021 <- get_municipalities(2021, geoid_year = 2021)
@@ -135,12 +145,12 @@ test_that("get_municipalities handles geoid_ref_as_ref_column", {
 
 test_that("get_geoid_cross_references handles bad years", {
   expect_error(get_geoid_cross_references(2000, 1999:2021))
-  expect_error(get_geoid_cross_references(2000, 2000:2022))
+  expect_error(get_geoid_cross_references(2000, 2000:2023))
 })
 
 test_that("get_geoid_cross_references handles bad reference year", {
   expect_error(get_geoid_cross_references(1999, 2010))
-  expect_error(get_geoid_cross_references(2022, 2010))
+  expect_error(get_geoid_cross_references(2023, 2010))
 })