Vectorize zip_distance() function

Author: gavinrozzi

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: zipcodeR
 Title: Data & Functions for Working with US ZIP Codes
-Version: 0.3.2
+Version: 0.3.3
 Authors@R: 
     person(given = "Gavin",
            family = "Rozzi",
@@ -16,7 +16,7 @@ BugReports: https://github.com/gavinrozzi/zipcodeR/issues/
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.1.1
+RoxygenNote: 7.1.2
 Imports: 
     rlang,
     stringr,

NEWS.md

@@ -1,5 +1,9 @@
 # *News*
 
+# zipcodeR 0.3.3
+- This update vectorizes the `zip_distance()` function to allow distance calculations between two vectors or columns of ZIP codes. The function now returns a data.frame of the resulting distance calculation.
+- `zip_distance()` now includes an additional argument, units, which allows selection between miles and meters for distance calculations.
+
 # zipcodeR 0.3.2
 - `zip_code_db` has been updated.
 - `download_zip_data()` has been refactored to make data updates more easily accessible and compare against existing data. Data is now directly downloaded from the upstream source and the existing data GitHub repository will no longer be updated.

R/download_data.r

@@ -24,10 +24,10 @@ download_zip_data <- function(force = FALSE) {
   if (file.exists(system.file("data", "zcta_crosswalk.rda", package = "zipcodeR")) == TRUE && force == FALSE) {
     cat("Crosswalk file found, skipping")
   } else if (file.exists(system.file("data", "zcta_crosswalk.rda", package = "zipcodeR")) == FALSE) {
-    cat(paste("zipcodeR: Downloading ZCTA crosswalk file","\n"))
+    cat(paste("zipcodeR: Downloading ZCTA crosswalk file", "\n"))
     utils::download.file(url_crosswalk, paste0(system.file("data", package = "zipcodeR"), "/zcta_crosswalk.rda"))
   } else if (force == TRUE) {
-    cat(paste("zipcodeR: forcing Download of ZCTA crosswalk file","\n"))
+    cat(paste("zipcodeR: forcing Download of ZCTA crosswalk file", "\n"))
     utils::download.file(url_crosswalk, paste0(system.file("data", package = "zipcodeR"), "/zcta_crosswalk.rda"))
   }
 

R/zip_helper_functions.R

@@ -65,31 +65,72 @@ normalize_zip <- function(zipcode) {
 #' Calculate the distance between two ZIP codes in miles
 #'
 #'
-#' @param zipcode_a First ZIP code
-#' @param zipcode_b Second ZIP code
+#' @param zipcode_a First vector of ZIP codes
+#' @param zipcode_b Second vector of ZIP codes
 #' @param lonlat lonlat argument to pass to raster::pointDistance() to select method of distance calculation. Default is TRUE to calculate distance over a spherical projection. FALSE will calculate the distance in Euclidean (planar) space.
-#' @return distance calculated from centroids of each ZIP code in miles
+#' @param units Specify which units to return distance calculations in. Choices include meters or miles.
+#' @return a data.frame containing a column for each ZIP code and a new column containing the distance between the two columns of ZIP code
 #'
 #' @examples
+#' Example with a single pair of ZIP codes
 #' zip_distance("08731", "08901")
+#'
+#' zip_codes <- tribble(~zip_a,  ~zip_b,
+#' "08731",  "08901",
+#' "08734",  "08005")
+#'
+#' Example with two vectors of ZIP codes
+#' zip_distance(zip_codes$zip_a,zip_codes$zip_b)
+#'
 #' @importFrom raster pointDistance
 #' @export
-zip_distance <- function(zipcode_a, zipcode_b, lonlat = TRUE) {
+zip_distance <- function(zipcode_a, zipcode_b, lonlat = TRUE, units = "miles") {
+  zipcode_a <- as.character(zipcode_a)
+  zipcode_b <- as.character(zipcode_b)
 
   # Create an instance of the ZIP code database for calculating distance,
   # filter to those with lat / lon pairs
   zip_data <- zip_code_db %>%
     dplyr::filter(.data$lat != "NA" & .data$lng != "NA") %>%
-    dplyr::filter(.data$zipcode == zipcode_a | .data$zipcode == zipcode_b) %>%
+    dplyr::filter(.data$zipcode %in% zipcode_a | .data$zipcode %in% zipcode_b) %>%
     dplyr::select(.data$zipcode, .data$lat, .data$lng)
 
-  distance <- raster::pointDistance(c(zip_data$lng[1], zip_data$lat[1]), c(zip_data$lng[2], zip_data$lat[2]), lonlat = lonlat)
+  # Filter the data points for each set of ZIP codes
+  zip_a_data <- zip_data %>%
+    dplyr::filter(.data$zipcode %in% zipcode_a)
+
+  zip_b_data <- zip_data %>%
+    dplyr::filter(.data$zipcode %in% zipcode_b)
+
+  # Create a matrix of points to feed to raster
+  points_a <- cbind(cbind(zip_a_data$lng, zip_a_data$lat))
+  points_b <- cbind(cbind(zip_b_data$lng, zip_b_data$lat))
+
+  # Calculate the distance matrix between both sets of points
+  distance <- raster::pointDistance(points_a, points_b, lonlat = lonlat)
 
-  # Convert meters to miles for distance measurement
-  distance <- distance * 0.000621371
+  # Convert the distance matrix from meters to miles
+  if (units == "miles") {
+    distance <- distance * 0.000621371
+  }
 
   # Round to 2 decimal places to match search_radius()
   distance <- round(distance, digits = 2)
 
-  return(distance)
+  # Put together the results in a data.frame
+  result <- data.frame(zipcode_a, zipcode_b, distance)
+
+  # Insert NA values in rows that could not be found in zip_code_db
+  for (i in 1:nrow(result)) {
+    if (result$zipcode_a[i] %in% zip_data$zipcode == FALSE) {
+      result$distance[i] <- NA
+    }
+
+    if (result$zipcode_b[i] %in% zip_data$zipcode == FALSE) {
+      result$distance[i] <- NA
+    }
+  }
+
+
+  return(result)
 }

codemeta.json

@@ -14,7 +14,7 @@
   ],
   "issueTracker": "https://github.com/gavinrozzi/zipcodeR/issues/",
   "license": "https://spdx.org/licenses/GPL-3.0",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",
@@ -220,6 +220,18 @@
       },
       "sameAs": "https://CRAN.R-project.org/package=httr"
     },
+    {
+      "@type": "SoftwareApplication",
+      "identifier": "curl",
+      "name": "curl",
+      "provider": {
+        "@id": "https://cran.r-project.org",
+        "@type": "Organization",
+        "name": "Comprehensive R Archive Network (CRAN)",
+        "url": "https://cran.r-project.org"
+      },
+      "sameAs": "https://CRAN.R-project.org/package=curl"
+    },
     {
       "@type": "SoftwareApplication",
       "identifier": "RSQLite",
@@ -253,7 +265,7 @@
   ],
   "releaseNotes": "https://github.com/gavinrozzi/zipcodeR/blob/master/NEWS.md",
   "readme": "https://github.com/gavinrozzi/zipcodeR/blob/master/README.md",
-  "fileSize": "3064.175KB",
+  "fileSize": "3771.828KB",
   "contIntegration": ["https://github.com/gavinrozzi/zipcodeR/actions", "https://codecov.io/gh/gavinrozzi/zipcodeR"],
   "citation": [
     {