added US_countryConvsion functions

DESCRIPTION

@@ -1,6 +1,6 @@
 Type: Package
 Package: MazamaSpatialUtils
-Version: 0.8.6
+Version: 0.8.7
 Title: Spatial Data Download and Utility Functions
 Authors@R: c(
     person("Jonathan", "Callahan", email="[email protected]", role=c("aut","cre")), 
@@ -57,4 +57,4 @@ Suggests:
 Encoding: UTF-8
 VignetteBuilder: knitr
 LazyData: true
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1

NAMESPACE

@@ -29,6 +29,12 @@ export(convertUSCensusStates)
 export(convertWBDHUC)
 export(convertWeatherZones)
 export(convertWikipediaTimezoneTable)
+export(countryCodeToFIPS)
+export(countryCodeToName)
+export(countryFIPSToCode)
+export(countryFIPSToName)
+export(countryNameToCode)
+export(countryNameToFIPS)
 export(countryToCode)
 export(dissolve)
 export(getCountry)

NEWS.md

@@ -1,3 +1,18 @@
+# MazamaSpatialUtils 0.8.7
+
+Added a new set of country code conversion functions whose names match those
+for state and county conversions:
+
+- `countryCodeToName()`
+- `countryCodeToFIPS()`
+- `countryFIPSToName()`
+- `countryCodeToCode()`
+- `countryNameToCode()`
+- `countryNameToFIPS()`
+
+These are now preferred over the older `codeToCountry()` and `countryToCode()`
+functions which, while deprecated, are still supported for backwards compatibility.
+
 # MazamaSpatialUtils 0.8.6
 
 * Addressed CRAN package documentation issue.

R/MazamaSpatialUtils.R → R/MazamaSpatialUtils-package.R

@@ -1,6 +1,6 @@
-#' @docType package
+#' @keywords internal
+#' "_PACKAGE"
 #' @name MazamaSpatialUtils
-#' @aliases MazamaSpatialUtils-package
 #' @title Mazama Science spatial data and utility functions.
 #' @description This package contains code to convert various spatial datasets
 #' into .rda files with uniformly named identifiers including:
@@ -150,27 +150,27 @@ iso3ToIso2 <- function(countryCodes) {
 #' @param countryCodes Vector of ISO 3166-1 alpha-2 country codes.
 #' @description Converts a vector of ISO 3166-1 alpha-2 codes to the
 #' corresponding English names.
+#'
+#' @note This function is deprecated as of \strong{MazamaSpatialUtils 0.8.7}.
+#' Please use \link{countryCodeToName} instead.
+#'
 #' @return A vector of English country names or NA.
 codeToCountry <- function(countryCodes) {
-  countryNames <- countrycode::countrycode(
-    countryCodes, "iso2c", "country.name",
-    custom_match = c("AN" = "Netherlands Antilles") # custom match for Netherlands Antilles
-  )
-  return(countryNames)
+  return(countryCodeToName(countryCodes));
 }
 
 #' @export
 #' @title Convert country names to country codes
 #' @param countryNames Vector of English language country names.
 #' @description Converts a vector of English country names to the corresponding
 #' ISO 3166-1 alpha-2 codes.
+#'
+#' @note This function is deprecated as of \strong{MazamaSpatialUtils 0.8.7}.
+#' Please use \link{countryNameToCode} instead.
+#'
 #' @return A vector of ISO 3166-1 alpha-2 codes or NA.
 countryToCode <- function(countryNames) {
-  countryCodes <- countrycode::countrycode(
-    countryNames, "country.name", "iso2c",
-    custom_match = c("Netherlands Antilles" = "AN") # custom match for Netherlands Antilles
-  )
-  return(countryCodes)
+  return(countryNameToCode(countryNames));
 }
 
 #' @export

R/US_countryConversion.R

@@ -0,0 +1,100 @@
+#'
+#' @name countryConversion
+#' @aliases countryCodeToName countryCodeToFIPS
+#' @aliases countryFIPSToName countryCodeToCode
+#' @aliases countryNameToCode countryNameToFIPS
+#'
+#' @title Conversion functions for country names, codes and FIPS codes.
+#'
+#' @param countryName Vector of English language country names.
+#' @param countryCode Vector of ISO 3166-1 alpha-2 codes.
+#' @param countryFIPS Vector of two-character FIPS codes.
+#'
+#' @return A vector of country names or codes.
+#'
+#' @description Converts a vector of country names or codes from one system to
+#' another returning \code{NA} where no match is found.
+#'
+#' @examples
+#' library(MazamaSpatialUtils)
+#'
+#' # FIPS codes are different!
+#'
+#' countryNameToCode("Germany")
+#' countryNameToFIPS("Germany")
+#'
+#' countryCodeToName("CH")
+#' countryFIPSToName("CH")
+#'
+#' countryCodes <- sample(SimpleCountries$countryCode, 30)
+#'
+#' data.frame(
+#'   name = countryCodeToName(countryCodes),
+#'   code = countryCodes,
+#'   FIPS = countryCodeToFIPS(countryCodes)
+#' )
+#'
+NULL
+
+#' @rdname countryConversion
+#' @export
+countryCodeToName <- function(
+  countryCode = NULL
+) {
+  countryName <- countrycode::countrycode(
+    countryCode, "iso2c", "country.name",
+    custom_match = c("AN" = "Netherlands Antilles") # custom match for Netherlands Antilles
+  )
+  return(countryName)
+}
+
+#' @rdname countryConversion
+#' @export
+countryCodeToFIPS <- function(
+  countryCode = NULL
+) {
+  values <- MazamaSpatialUtils::SimpleCountries$FIPS
+  names(values) <- toupper(MazamaSpatialUtils::SimpleCountries$countryCode)
+  return( as.character(values[toupper(countryCode)]) )
+}
+
+#' @rdname countryConversion
+#' @export
+countryFIPSToName <- function(
+  countryFIPS = NULL
+) {
+  countryName <- countryFIPS %>% countryFIPSToCode() %>% countryCodeToName()
+  return(countryName)
+}
+
+#' @rdname countryConversion
+#' @export
+countryFIPSToCode <- function(
+  countryFIPS = NULL
+) {
+  values <- MazamaSpatialUtils::SimpleCountries$countryCode
+  names(values) <- toupper(MazamaSpatialUtils::SimpleCountries$FIPS)
+  return( as.character(values[toupper(countryFIPS)]) )
+}
+
+#' @rdname countryConversion
+#' @export
+countryNameToCode <- function(
+  countryName = NULL
+) {
+  countryCode <- countrycode::countrycode(
+    countryName, "country.name", "iso2c",
+    custom_match = c("Netherlands Antilles" = "AN") # custom match for Netherlands Antilles
+  )
+  return(countryCode)
+}
+
+#' @rdname countryConversion
+#' @export
+countryNameToFIPS <- function(
+  countryName = NULL
+) {
+  countryFIPS <- countryName %>% countryNameToCode() %>% countryCodeToFIPS()
+  return(countryFIPS)
+}
+

R/US_countyConversion.R

@@ -1,46 +1,46 @@
 #'
 #' @name US_countyConversion
 #' @aliases US_countyFIPSToName US_countyNameToFIPS
-#' 
+#'
 #' @title Conversion functions for US county names and FIPS codes.
-#' 
+#'
 #' @param state Vector of state codes, names or FIPS codes. Values will be
 #' evaluated to determine the type of input.
 #' @param countyName Vector of English language county names.
 #' @param countyFIPS Vector of two-digit FIPS codes.
-#' 
+#'
 #' @return A vector of US county names or FIPS codes.
-#' 
-#' @description Converts a vector of US county names or FIPS codes from one 
-#' system to another reuturning \code{NA} where no match is found.
-#' 
-#' @examples 
+#'
+#' @description Converts a vector of US county names or FIPS codes from one
+#' system to another returning \code{NA} where no match is found.
+#'
+#' @examples
 #' library(MazamaSpatialUtils)
-#' 
+#'
 #' US_countyNameToFIPS("Washington", "King")
-#' 
+#'
 #' # If a single state is provided, it will be recycled
 #' US_countyNameToFIPS("Washington", c("King", "Okanogan"))
-#' 
+#'
 #' # Normally, equal length vectors are provided
 #' US_countyNameToFIPS(c("WA", "WA"), c("King", "Okanogan"))
-#' 
+#'
 #' # You cannot mix codes!
 #' US_countyNameToFIPS(c("WA", "Washington"), c("King", "Okanogan"))
-#' 
+#'
 #' # No 'Okanogan' county in Texas
 #' US_countyNameToFIPS(c("WA", "TX"), c("King", "Okanogan"))
-#' 
+#'
 #' # But there is a 'King' county in Texas
 #' US_countyNameToFIPS(c("TX", "WA"), c("King", "Okanogan"))
 #' US_countyNameToFIPS(c("TX", "WA"), c("King", "King"))
-#' 
-#' # The US_countyFIPSToName() function is included for symmetry but a 
+#'
+#' # The US_countyFIPSToName() function is included for symmetry but a
 #' # more typical usage of a 5-digit county FIPS would be to extract it from
 #' # the US_countyCodes package dataset:
-#' 
+#'
 #' US_countyCodes %>% dplyr::filter(countyFIPS == 53033)
-#' 
+#'
 NULL
 
 #' @rdname US_countyConversion
@@ -53,15 +53,15 @@ US_countyNameToFIPS <- function(
   # ----- Validate parameters --------------------------------------------------
 
   state <- as.character(state)
-  
-  if ( length(state) == 1 ) 
-    state <- rep(state, length.out = length(countyName) ) 
-  
-  if ( length(state) != length(countyName) ) 
+
+  if ( length(state) == 1 )
+    state <- rep(state, length.out = length(countyName) )
+
+  if ( length(state) != length(countyName) )
     stop("Parameter 'state' must have the same length as 'countyName' or be of length 1")
-  
+
   # ----- Get stateFIPS --------------------------------------------------------
-  
+
   if ( state[1] %in% US_stateCodes$stateCode ) {
     stateFIPS <- US_stateCodeToFIPS(state)
   } else if ( tolower(state[1]) %in%  tolower(US_stateCodes$stateName) ) {
@@ -71,30 +71,30 @@ US_countyNameToFIPS <- function(
   } else {
     stop(sprintf("state = \"%s\" is not recognized.", state))
   }
-  
+
   # ----- Find countyFIPS ------------------------------------------------------
-  
-  state_county_name <- 
+
+  state_county_name <-
     paste0(stateFIPS, "_", countyName) %>%
     tolower()
-  
+
   US_state_county_name <-
     paste0(
-      MazamaSpatialUtils::US_countyCodes$stateFIPS, 
-      "_", 
+      MazamaSpatialUtils::US_countyCodes$stateFIPS,
+      "_",
       MazamaSpatialUtils::US_countyCodes$countyName
     ) %>%
     tolower()
-  
+
   indices <- match(state_county_name, US_state_county_name)
-  
-  countyFIPS <- 
+
+  countyFIPS <-
     MazamaSpatialUtils::US_countyCodes$countyFIPS[indices]
-  
+
   # ----- Return ---------------------------------------------------------------
-  
+
   return(countyFIPS)
-  
+
 }
 
 #' @rdname US_countyConversion
@@ -103,19 +103,19 @@ US_countyFIPSToName <- function(
   state = NULL,
   countyFIPS = NULL
 ) {
-  
+
   # ----- Validate parameters --------------------------------------------------
-  
+
   state <- as.character(state)
-  
-  if ( length(state) == 1 ) 
-    state <- rep(state, length.out = length(countyFIPS) ) 
-  
-  if ( length(state) != length(countyFIPS) ) 
+
+  if ( length(state) == 1 )
+    state <- rep(state, length.out = length(countyFIPS) )
+
+  if ( length(state) != length(countyFIPS) )
     stop("Parameter 'state' must have the same length as 'countyFIPS' or be of length 1")
-  
+
   # ----- Get stateFIPS --------------------------------------------------------
-  
+
   if ( state[1] %in% US_stateCodes$stateCode ) {
     stateFIPS <- US_stateCodeToFIPS(state)
   } else if ( tolower(state[1]) %in%  tolower(US_stateCodes$stateName) ) {
@@ -125,29 +125,29 @@ US_countyFIPSToName <- function(
   } else {
     stop(sprintf("state = \"%s\" is not recognized.", state))
   }
-  
+
   # ----- Find countyFIPS ------------------------------------------------------
-  
-  state_county_FIPS <- 
+
+  state_county_FIPS <-
     paste0(stateFIPS, "_", countyFIPS) %>%
     tolower()
-  
+
   US_state_county_FIPS <-
     paste0(
-      MazamaSpatialUtils::US_countyCodes$stateFIPS, 
-      "_", 
+      MazamaSpatialUtils::US_countyCodes$stateFIPS,
+      "_",
       MazamaSpatialUtils::US_countyCodes$countyFIPS
     ) %>%
     tolower()
-  
+
   indices <- match(state_county_FIPS, US_state_county_FIPS)
-  
-  countyName <- 
+
+  countyName <-
     MazamaSpatialUtils::US_countyCodes$countyName[indices]
-  
+
   # ----- Return ---------------------------------------------------------------
-  
+
   return(countyName)
-  
+
 }