diff --git a/CRAN-RELEASE b/CRAN-RELEASE new file mode 100644 index 0000000..a90d28a --- /dev/null +++ b/CRAN-RELEASE @@ -0,0 +1,2 @@ +This package was submitted to CRAN on 2019-07-22. +Once it is accepted, delete this file and tag the release (commit 2af548182c). diff --git a/DESCRIPTION b/DESCRIPTION index 4ab5510..81339e2 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: censusxy Title: Access the U.S. Census Bureau Geocoder -Version: 0.1.0 +Version: 0.1.1 Authors@R: c( person("Christopher", "Prener", ,"chris.prener@slu.edu", c("aut", "cre"), comment = c(ORCID = "0000-0002-4310-9888")), @@ -9,11 +9,12 @@ Authors@R: c( ) Description: Provides access to the U.S. Census Bureau's API for batch geocoding American street addresses (). - The package offers a vectorized solution for address geocoding. It was also - developed specifically with large data sets in mind - only unique addresses - are passed to the API for geocoding. If a data set exceeds 1,000 unique addresses, - it will be automatically subset into appropriately sized API calls, geocoded, and - then put back together so that a single object is returned. + The package offers a batch solution for address geocoding, as opposed to geocoding + a single address at a time. It has also been developed specifically with large + data sets in mind - only unique addresses are passed to the API for geocoding. + If a data set exceeds 1,000 unique addresses, it will be automatically subset + into appropriately sized API calls, geocoded, and then put back together so that + a single object is returned. Depends: R (>= 3.3) License: GPL-3 URL: https://github.com/slu-openGIS/censusxy diff --git a/NEWS.md b/NEWS.md index bc12683..2beb4e0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,9 @@ +# censusxy 0.1.1 + +* CRAN release version of the software. +* Corrected tense shifts in description paragraph in `DESCRIPTION`, `README.Rmd`, and `index.Rmd` +* Other minor updates to `pkgdown` site and `README.Rmd` + # censusxy 0.1.0 * Added a `NEWS.md` file to track changes to the package. diff --git a/R/cxy_geocode.R b/R/cxy_geocode.R index 91bd152..d63da9a 100644 --- a/R/cxy_geocode.R +++ b/R/cxy_geocode.R @@ -24,10 +24,21 @@ #' @importFrom rlang enquo quo_name #' @importFrom sf st_as_sf #' +#' @examples +#' # load sample data +#' data <- stl_homicides_small +#' +#' # geocode data +#' data <- cxy_geocode(data, address = "street_address", city = "city", +#' state = "state", zip = "postal_code") +#' +#' # preview data +#' data +#' #' @export cxy_geocode <- function(.data, address, city, state, zip, style = "minimal", output = "tibble", timeout = 30){ - # global bindings + # global bindings lon = lat = NULL # check for missing parameters diff --git a/README.Rmd b/README.Rmd index 63c8385..46260ed 100644 --- a/README.Rmd +++ b/README.Rmd @@ -22,14 +22,20 @@ knitr::opts_chunk$set( [![DOI](https://zenodo.org/badge/165924122.svg)](https://zenodo.org/badge/latestdoi/165924122) [![CRAN_status_badge](http://www.r-pkg.org/badges/version/censusxy)](https://cran.r-project.org/package=censusxy) -The `censusxy` package is designed to provide easy and efficient access to the [US Census Bureau Batch Geocoder](https://geocoding.geo.census.gov/geocoder/) in `R`. The package offers a vectorized solution for address geocoding (as opposed to packages like [`censusr`](https://CRAN.R-project.org/package=censusr), which provide functionality for a single address at a time). `censusxy` was also developed specifically with large data sets in mind - only unique addresses are passed to the API for geocoding. If a data set exceeds 1,000 unique addresses, it will be automatically subset into appropriately sized API calls, geocoded, and then put back together so that a single object is returned. +The `censusxy` package is designed to provide easy and efficient access to the [U.S. Census Bureau Batch Geocoder](https://geocoding.geo.census.gov/geocoder/) in `R`. The package offers a batch solution for address geocoding (as opposed to packages like [`censusr`](https://CRAN.R-project.org/package=censusr), which provide functionality for a single address at a time). `censusxy` has also been developed specifically with large data sets in mind - only unique addresses are passed to the API for geocoding. If a data set exceeds 1,000 unique addresses, it will be automatically subset into appropriately sized API calls, geocoded, and then put back together so that a single object is returned. ## Installation ### Installing Dependencies You should check the [`sf` package website](https://r-spatial.github.io/sf/) and the [`censusxy` package website](https://slu-openGIS.github.io/censusxy/) for the latest details on installing dependencies for that package. Instructions vary significantly by operating system. For best results, have `sf` installed before you install `censusxy`. Other dependencies, like `dplyr`, will be installed automatically with `censusxy` if they are not already present. ### Installing censusxy -The package is soon to be on CRAN, but meanwhile, the development version of `censusxy` can be accessed from GitHub with `remotes`: +Once `sf` is installed, the easiest way to get `censusxy` is to install it from CRAN: + +```r +install.packages("censusxy") +``` + +Alternatively, the development version of `censusxy` can be accessed from GitHub with `remotes`: ```r # install.packages("remotes") @@ -59,7 +65,7 @@ If you request an `sf` object, you easily preview the results with the [`mapview ```r > mapview::mapview(homicide_sf) ``` -```{r exampleMap1, echo=FALSE, out.width = '60%'} +```{r exampleMap1, echo=FALSE, out.width = '100%'} knitr::include_graphics("man/figures/homicide_example.png") ``` diff --git a/README.md b/README.md index 1f3681d..37fcd72 100644 --- a/README.md +++ b/README.md @@ -14,15 +14,14 @@ status](https://codecov.io/gh/slu-openGIS/censusxy/branch/master/graph/badge.svg [![CRAN\_status\_badge](http://www.r-pkg.org/badges/version/censusxy)](https://cran.r-project.org/package=censusxy) The `censusxy` package is designed to provide easy and efficient access -to the [US Census Bureau Batch +to the [U.S. Census Bureau Batch Geocoder](https://geocoding.geo.census.gov/geocoder/) in `R`. The -package offers a vectorized solution for address geocoding (as opposed -to packages like -[`censusr`](https://CRAN.R-project.org/package=censusr), which provide -functionality for a single address at a time). `censusxy` was also -developed specifically with large data sets in mind - only unique -addresses are passed to the API for geocoding. If a data set exceeds -1,000 unique addresses, it will be automatically subset into +package offers a batch solution for address geocoding (as opposed to +packages like [`censusr`](https://CRAN.R-project.org/package=censusr), +which provide functionality for a single address at a time). `censusxy` +has also been developed specifically with large data sets in mind - only +unique addresses are passed to the API for geocoding. If a data set +exceeds 1,000 unique addresses, it will be automatically subset into appropriately sized API calls, geocoded, and then put back together so that a single object is returned. @@ -40,8 +39,15 @@ installed automatically with `censusxy` if they are not already present. ### Installing censusxy -The package is soon to be on CRAN, but meanwhile, the development -version of `censusxy` can be accessed from GitHub with `remotes`: +Once `sf` is installed, the easiest way to get `censusxy` is to install +it from CRAN: + +``` r +install.packages("censusxy") +``` + +Alternatively, the development version of `censusxy` can be accessed +from GitHub with `remotes`: ``` r # install.packages("remotes") @@ -81,7 +87,7 @@ If you request an `sf` object, you easily preview the results with the > mapview::mapview(homicide_sf) ``` - + ## Contributor Code of Conduct diff --git a/cran-comments.md b/cran-comments.md index 18d2728..4f38b5d 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,5 +1,11 @@ ## Release summary -This is the initial version of the `censusxy` package. +This is the initial version of the `censusxy` package. It was previously submitted (on July 5) and then rejected (on July 9): + +> Please ensure that your functions do not write by default or in your examples/vignettes/tests in the user's home filespace (including the package directory and getwd()). + +We have reviewed the package to be sure - `censusxy` only interacts with the file system in `cxy_geocoder.R`, where a `.csv` is written to the temp directory (lines 14-16), which is subsequently cleaned up (line 57). We thought that this would be permissable according to CRAN policy since we're only working with the temp directory here. + +We are not at all opposed to making changes to ensure we comply with CRAN policy - but are unsure what to change in this instance. Uwe kindly suggested that we could resubmit the package as is and that he would be willing to take a look at the function. Thanks, Uwe, for your offer and help! ## Test environments * local OS X install: R 3.6.0 diff --git a/docs/CODE_OF_CONDUCT.html b/docs/CODE_OF_CONDUCT.html index ffe0504..ffb2761 100644 --- a/docs/CODE_OF_CONDUCT.html +++ b/docs/CODE_OF_CONDUCT.html @@ -63,7 +63,7 @@ censusxy - 0.1.0 + 0.1.1 diff --git a/docs/CONTRIBUTING.html b/docs/CONTRIBUTING.html index 655c9f3..98d433f 100644 --- a/docs/CONTRIBUTING.html +++ b/docs/CONTRIBUTING.html @@ -63,7 +63,7 @@ censusxy - 0.1.0 + 0.1.1 diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html index 7f1a45c..52ce505 100644 --- a/docs/LICENSE-text.html +++ b/docs/LICENSE-text.html @@ -63,7 +63,7 @@ censusxy - 0.1.0 + 0.1.1 diff --git a/docs/PULL_REQUEST_TEMPLATE.html b/docs/PULL_REQUEST_TEMPLATE.html index 3a5f281..88a9dc6 100644 --- a/docs/PULL_REQUEST_TEMPLATE.html +++ b/docs/PULL_REQUEST_TEMPLATE.html @@ -63,7 +63,7 @@ censusxy - 0.1.0 + 0.1.1 diff --git a/docs/articles/censusxy.html b/docs/articles/censusxy.html index 7d896f3..a470471 100644 --- a/docs/articles/censusxy.html +++ b/docs/articles/censusxy.html @@ -31,7 +31,7 @@ censusxy - 0.1.0 + 0.1.1 @@ -87,16 +87,16 @@

2019-07-05

Overview

-

The censusxy package is designed to provide easy and efficient access to the US Census Bureau Batch Geocoder in R.

+

The censusxy package is designed to provide easy and efficient access to the U.S. Census Bureau Batch Geocoder in R.

Motivation

-

The censusxy package was developed specifically with large data sets in mind. There are other implementations for accessing the Census Bureau’s API for geocoding in R (e.g. the censusr package) that require iteration to geocode multiple addresses at once. censusxy, on the other hand, is designed to operate on on a column of addresses in a data frame or tibble object. Additionally, the Census Bureau caps the number of addresses that can be sent to the API in a single call at 1,000. If a data set exceeds 1,000 unique addresses, it will be automatically subset into appropriately sized API calls, geocoded, and then put back together so that a single object is returned. The package therefore provides an efficient solution to batch geocoding via the Census Bureau’s services.

+

The censusxy package has been developed specifically with large data sets in mind. There are other implementations for accessing the Census Bureau’s API for geocoding in R (e.g. the censusr package) that require iteration to geocode multiple addresses at once. censusxy, on the other hand, is designed to operate on on a column of addresses in a data frame or tibble object. Additionally, the Census Bureau caps the number of addresses that can be sent to the API in a single call at 1,000. If a data set exceeds 1,000 unique addresses, it will be automatically subset into appropriately sized API calls, geocoded, and then put back together so that a single object is returned. The package therefore provides an efficient solution to batch geocoding via the Census Bureau’s services.

Responsible Use

-

The US Census Bureau makes their geocoding API available without any API key, and this package allows for virtually unlimited batch geocoding. Please use this package responsibly, as others will need use of this API for their research.

+

The U.S. Census Bureau makes their geocoding API available without any API key, and this package allows for virtually unlimited batch geocoding. Please use this package responsibly, as others will need use of this API for their research.

@@ -104,10 +104,10 @@

We recommend that users install sf before proceeding with the installation of censusxy. Windows users should be able to install sf without significant issues, but macOS and Linux users will need to install several open source spatial libraries to get sf itself up and running. The easiest approach for macOS users is to install the GDAL 2.0 Complete framework from Kyng Chaos.

For Linux users, steps will vary based on the flavor being used. Our configuration file for Travis CI and its associated bash script should be useful in determining the necessary components to install.

Once sf is installed, the easiest way to get censusxy is to install it from CRAN:

-
install.packages("compstatr")
-

The development version of compstatr can be accessed from GitHub with remotes:

- +
install.packages("censusxy")
+

The development version of censusxy can be accessed from GitHub with remotes:

+
# install.packages("remotes")
+remotes::install_github("slu-openGIS/censusxy")

@@ -126,16 +126,16 @@

Usage

-

This package contains a single exported function, cxy_geocode(). The only required arguments are .data for the data.frame or tibble containing address data, and address specifying the column name containing street addresses. The function supports non-standard evaluation, meaning you do not need to quote arguments for column names.

-
results <- cxy_geocode(stl_homicides, address = street_address)
+

This package contains a single exported function, cxy_geocode(). The only required arguments are .data for the data.frame or tibble containing address data, and address specifying the column name containing street addresses. The function supports non-standard evaluation, meaning you do not need to quote arguments for column names.

+
results <- cxy_geocode(stl_homicides, address = street_address)

However, it is highly recommended that you include city, state and zip code as well. Doing so will increase speed and accuracy significantly. The homicide data contain city and state data as well, so the preferred call for these data would be:

-
results <- cxy_geocode(stl_homicides, address = street_address, city = city, state = state)
+
results <- cxy_geocode(stl_homicides, address = street_address, city = city, state = state)

Finally, two output types are supported. By default, a tibble is returned (output = "tibble") with a minimal set of variables that describe the accuracy of a given observation’s geocoding (style = "minimal"). A complete set of values returned by the API for each observation can be obtained by using style = "full". Alternatively, an sf object can be returned with the geocoded data projected using the WGS 1984 geographic coordinate system:

-
homicide_sf <- cxy_geocode(stl_homicides, id, street_address, city, state, postal_code, output = "sf")
+
homicide_sf <- cxy_geocode(stl_homicides, id, street_address, city, state, postal_code, output = "sf")

Note, however, that it returns only matched addresses, including those approximated by street length. If there are unmatched addresses, they will be dropped from the output. Use output = "tibble" to return all addresses, including those that are unmatched.

Output returned as an sf object can be previewed with a package like mapview:

-
> mapview::mapview(homicide_sf)
-

+
> mapview::mapview(homicide_sf)
+

diff --git a/docs/articles/index.html b/docs/articles/index.html index e17c12d..dc5499e 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -63,7 +63,7 @@ censusxy - 0.1.0 + 0.1.1

diff --git a/docs/authors.html b/docs/authors.html index c4d9051..c2c0caf 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -63,7 +63,7 @@ censusxy - 0.1.0 + 0.1.1

diff --git a/docs/index.html b/docs/index.html index f77384f..d81161f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -12,11 +12,12 @@ + The package offers a batch solution for address geocoding, as opposed to geocoding + a single address at a time. It has also been developed specifically with large + data sets in mind - only unique addresses are passed to the API for geocoding. + If a data set exceeds 1,000 unique addresses, it will be automatically subset + into appropriately sized API calls, geocoded, and then put back together so that + a single object is returned.">