[Epic F] CRAN Release v0.2.0 — documentation and submission prep

DESCRIPTION

@@ -1,9 +1,9 @@
 Package: deprivateR
 Title: Calculating and Analyzing Measures of Deprivation in the United States
-Version: 0.2.0.9000
+Version: 0.2.0
 Authors@R: c(
     person(
-      given = "Christopher", family = "Prener", email = "Christopher.Prener@pfizer.com", 
+      given = "Christopher", family = "Prener", email = "christopher.prener@pfizer.com", 
       role = c("aut", "cre"), comment = c(ORCID = "0000-0002-4310-9888")
     ),
     person(

NEWS.md

@@ -1,11 +1,34 @@
-# deprivateR 0.2.0.9000
+# deprivateR 0.2.0
 
-Completed:
-* Minor updates to documentation
-* Added `dep_set_api_key()` — a wrapper around `tidycensus::census_api_key()` that checks for the `key` argument, then `CENSUS_API_KEY` env var, and prompts interactively if neither is found
+## New features
 
-Planned:
-* Addition of Theil's H index
+* Added `dep_set_api_key()` for easier Census API key management — checks
+  for an explicit key, then the `CENSUS_API_KEY` env var, and prompts
+  interactively if neither is found
+* Added a "Getting Started" vignette covering all supported indices,
+  sample data workflows, and spatial output
+
+## Dependency changes
+
+* Removed `stringr`, `english`, `tibble`, and `tidyselect` from Imports,
+  reducing hard dependencies from 14 to 10
+* Bumped minimum R version to 4.4
+
+## Improvements
+
+* Error messages now use `cli` formatting (tidyverse-style) instead of
+  base `stop()`/`warning()`/`message()`
+* Internal code quality improvements: extracted shared helpers, reduced
+  nesting, and removed code duplication across SVI/NDI processing
+* Expanded test suite with 350+ new assertions covering all exported
+  functions and core internals
+
+## Bug fixes
+
+* Fixed territory (e.g., Puerto Rico) FIPS code validation in
+  `dep_get_index()` — was incorrectly comparing abbreviations instead
+  of FIPS codes
+* Fixed pkgdown site build failure caused by `docs/` directory conflict
 
 # deprivateR 0.1.0
 

README.Rmd

@@ -19,102 +19,128 @@ knitr::opts_chunk$set(
 [![CRAN_status_badge](https://www.r-pkg.org/badges/version/deprivateR)](https://cran.r-project.org/package=deprivateR)
 [![cranchecks](https://badges.cranchecks.info/worst/deprivateR.svg)](https://cran.r-project.org/web/checks/check_results_deprivateR.html)
 [![Downloads](https://cranlogs.r-pkg.org/badges/deprivateR?color=brightgreen)](https://www.r-pkg.org/pkg/deprivateR)
-[![DOI](https://img.shields.io/badge/DOI-10.32614%2FCRAN.package.deprivateR-blue)](https://doi.org/10.32614/deprivateR)
 
-`deprivateR` is meant to provide a unified API for accessing and calculating a number of different measures of socioeconomic deprivation in the United States, including the Area Deprivation Index (ADI), Neighborhood Deprivation Index (NDI), and the Social Vulnerability Index. The Gini Coefficient can also be returned, though it is not re-calculated on the fly. 
+`deprivateR` provides a unified API for accessing and calculating measures of socioeconomic deprivation in the United States, including the Area Deprivation Index (ADI), Neighborhood Deprivation Index (NDI), and the Social Vulnerability Index (SVI). The Gini Coefficient can also be returned, though it is not re-calculated on the fly.
+
+## What's New in v0.2.0
+
+* New `dep_set_api_key()` function for easier Census API key setup
+* Reduced dependencies from 14 to 10
+* Tidyverse-style error messages via `cli`
+* Getting Started vignette
 
 ## Motivation
+
 The [`sociome`](https://CRAN.R-project.org/package=sociome) and [`ndi`](https://CRAN.R-project.org/package=ndi) packages are excellent contributions, but offer different APIs for returning their respective indices. `deprivateR` provides a unified interface for accessing these measures of deprivation, as well as the ability to calculate the various forms of the Social Vulnerability Index (SVI) that the Centers for Disease Control and Prevention (CDC) has published. Importantly, SVI can be calculated for a variety of years and geographic levels. This functionality expands the possibilities for implementing these measures in research and public health practice. However, users should also be aware that ADI, NDI, and SVI have not been extensively validated for some Census geographies.
 
 ## Installation
+
 The easiest way to install `deprivateR` is from CRAN:
 
 ```r
 install.packages("deprivateR")
 ```
 
-Alternatively, you can install development version of `deprivateR` from GitHub with `remotes`:
+Alternatively, you can install the development version of `deprivateR` from GitHub with `remotes`:
 
 ```r
 # install.packages("remotes")
 remotes::install_github("pfizer-opensource/deprivateR")
 ```
 
 ## Usage
+
+### API Key Setup
+
+`deprivateR` retrieves data from the U.S. Census Bureau via `tidycensus`, which requires a free API key. If you've already configured `tidycensus`, no additional setup is needed. Otherwise, use `dep_set_api_key()` to store your key:
+
+```r
+dep_set_api_key("your_key_here")
+```
+
+You can obtain a key at <https://api.census.gov/data/key_signup.html>.
+
 ### Calculate Deprivation Indices
+
 The core function in `deprivateR` is `dep_get_index()`. This function returns the specified index for the given geography and year:
 
 ```r
-> dep_get_index(geography = "county", state = "MO", index = "adi", year = 2022)
-Using FIPS code '29' for state 'MO'
-# A tibble: 115 × 3
-   GEOID NAME                         ADI
-   <chr> <chr>                      <dbl>
- 1 29001 Adair County, Missouri     101. 
- 2 29003 Andrew County, Missouri     69.4
- 3 29005 Atchison County, Missouri  104. 
- 4 29007 Audrain County, Missouri   115. 
- 5 29009 Barry County, Missouri     106. 
- 6 29011 Barton County, Missouri    118. 
- 7 29013 Bates County, Missouri     107. 
- 8 29015 Benton County, Missouri    103. 
- 9 29017 Bollinger County, Missouri 104. 
-10 29019 Boone County, Missouri      68.9
-# ℹ 105 more rows
-# ℹ Use `print(n = ...)` to see more rows
+dep_get_index(geography = "county", state = "MO", index = "adi", year = 2022)
+```
+
+```
+#> Using FIPS code '29' for state 'MO'
+#> # A tibble: 115 × 3
+#>    GEOID NAME                         ADI
+#>    <chr> <chr>                      <dbl>
+#>  1 29001 Adair County, Missouri     101. 
+#>  2 29003 Andrew County, Missouri     69.4
+#>  3 29005 Atchison County, Missouri  104. 
+#>  4 29007 Audrain County, Missouri   115. 
+#>  5 29009 Barry County, Missouri     106. 
+#>  6 29011 Barton County, Missouri    118. 
+#>  7 29013 Bates County, Missouri     107. 
+#>  8 29015 Benton County, Missouri    103. 
+#>  9 29017 Bollinger County, Missouri 104. 
+#> 10 29019 Boone County, Missouri      68.9
+#> # ℹ 105 more rows
 ```
 
 The `index` argument can take multiple indices at once, as can the `year` argument. This gives users the ability to compare multiple indices across multiple years:
 
 ```r
-> dep_get_index(geography = "county", state = "MO", index = c("svi20", "svi20s"), year = c(2021, 2022))
-Using FIPS code '29' for state 'MO'
-# A tibble: 230 × 5
-   GEOID NAME                       YEAR SVI_20 SVI_20S
-   <chr> <chr>                     <dbl>  <dbl>   <dbl>
- 1 29001 Adair County, Missouri     2021  0.377   0.386
- 2 29001 Adair County, Missouri     2022  0.456   0.439
- 3 29003 Andrew County, Missouri    2021  0       0    
- 4 29003 Andrew County, Missouri    2022  0       0    
- 5 29005 Atchison County, Missouri  2021  0.149   0.167
- 6 29005 Atchison County, Missouri  2022  0.149   0.167
- 7 29007 Audrain County, Missouri   2021  0.746   0.781
- 8 29007 Audrain County, Missouri   2022  0.886   0.904
- 9 29009 Barry County, Missouri     2021  0.702   0.693
-10 29009 Barry County, Missouri     2022  0.702   0.667
-# ℹ 220 more rows
-# ℹ Use `print(n = ...)` to see more rows
+dep_get_index(geography = "county", state = "MO", index = c("svi20", "svi20s"), year = c(2021, 2022))
+```
+
+```
+#> Using FIPS code '29' for state 'MO'
+#> # A tibble: 230 × 5
+#>    GEOID NAME                       YEAR SVI_20 SVI_20S
+#>    <chr> <chr>                     <dbl>  <dbl>   <dbl>
+#>  1 29001 Adair County, Missouri     2021  0.377   0.386
+#>  2 29001 Adair County, Missouri     2022  0.456   0.439
+#>  3 29003 Andrew County, Missouri    2021  0       0    
+#>  4 29003 Andrew County, Missouri    2022  0       0    
+#>  5 29005 Atchison County, Missouri  2021  0.149   0.167
+#>  6 29005 Atchison County, Missouri  2022  0.149   0.167
+#>  7 29007 Audrain County, Missouri   2021  0.746   0.781
+#>  8 29007 Audrain County, Missouri   2022  0.886   0.904
+#>  9 29009 Barry County, Missouri     2021  0.702   0.693
+#> 10 29009 Barry County, Missouri     2022  0.702   0.667
+#> # ℹ 220 more rows
 ```
 
 An alternative to `dep_get_index()` is `dep_calc_index()`, which provides users with the ability to calculate indices using pre-downloaded data. The `dep_sample_data()` function can be used to explore how this function works using sample data from the 2018-2022 5-year American Community Survey for Missouri Counties:
 
 ```r
-> ndi_m <- dep_sample_data(index = "ndi_m")
-> dep_calc_index(ndi_m, geography = "county", index = "ndi_m", year = 2022)
-Warning: The proportion of variance explained by PC1 is less than 0.50.
-# A tibble: 115 × 4
-   GEOID NAME                        YEAR   NDI_M
-   <chr> <chr>                      <dbl>   <dbl>
- 1 29001 Adair County, Missouri      2022  0.0193
- 2 29003 Andrew County, Missouri     2022 -0.108 
- 3 29005 Atchison County, Missouri   2022 -0.0505
- 4 29007 Audrain County, Missouri    2022  0.0107
- 5 29009 Barry County, Missouri      2022  0.0129
- 6 29011 Barton County, Missouri     2022  0.105 
- 7 29013 Bates County, Missouri      2022  0.0679
- 8 29015 Benton County, Missouri     2022  0.0283
- 9 29017 Bollinger County, Missouri  2022  0.0565
-10 29019 Boone County, Missouri      2022 -0.0646
-# ℹ 105 more rows
-# ℹ Use `print(n = ...)` to see more rows
+ndi_m <- dep_sample_data(index = "ndi_m")
+dep_calc_index(ndi_m, geography = "county", index = "ndi_m", year = 2022)
+```
+
+```
+#> Warning: The proportion of variance explained by PC1 is less than 0.50.
+#> # A tibble: 115 × 4
+#>    GEOID NAME                        YEAR   NDI_M
+#>    <chr> <chr>                      <dbl>   <dbl>
+#>  1 29001 Adair County, Missouri      2022  0.0193
+#>  2 29003 Andrew County, Missouri     2022 -0.108 
+#>  3 29005 Atchison County, Missouri   2022 -0.0505
+#>  4 29007 Audrain County, Missouri    2022  0.0107
+#>  5 29009 Barry County, Missouri      2022  0.0129
+#>  6 29011 Barton County, Missouri     2022  0.105 
+#>  7 29013 Bates County, Missouri      2022  0.0679
+#>  8 29015 Benton County, Missouri     2022  0.0283
+#>  9 29017 Bollinger County, Missouri  2022  0.0565
+#> 10 29019 Boone County, Missouri      2022 -0.0646
+#> # ℹ 105 more rows
 ```
 
 ### Additional Functionality
 The `deprivateR` package also contains a number of helper functions that we use in our disparities work. These include:
 
   * `dep_percentiles()`: Calculate percentiles for a given variable in a data frame. This is the method used to reproduce SVI estimates, which include percentiles for each variable. It is also the method used for `dep_get_index()` and `dep_calc_index()` when `return_percentiles = TRUE`.
   * `dep_quantiles()`: Calculate quantiles for a given variable in a data frame. We use this to create tertiles and quartiles for descriptive statistics and regression analyses.
-  * `dep_map_breaks()`: Calculate map breaks for a given variable in a data frame. This is useful for creating choropleth maps with package like `ggplot2` or `leaflet`. It can be used to create "bins" automatically, using any of the algorithms supported by \code{classInt::classIntervals()}, or accept pre-specified breaks. 
+  * `dep_map_breaks()`: Calculate map breaks for a given variable in a data frame. This is useful for creating choropleth maps with packages like `ggplot2` or `leaflet`. It can be used to create "bins" automatically, using any of the algorithms supported by `classInt::classIntervals()`, or accept pre-specified breaks.
 
 ## Gratitude
 `deprivateR` would not be possible without the work of the [`sociome`](https://CRAN.R-project.org/package=sociome) and [`ndi`](https://CRAN.R-project.org/package=ndi) packages. The `sociome` package's development was led by Nik Krieger, and the `ndi` package's author is Ian D. Buller - we're immensely grateful for their contributions to the field. Likewise, `deprivateR` would not be possible without [Kyle Walker's](https://walker-data.com) packages [`tigris`](https://CRAN.R-project.org/package=tigris) and [`tidycensus`](https://walker-data.com/tidycensus/), which provide access to the underlying U.S. Census Bureau data for calculating these indices.