R/US_countyConversion.R

In MazamaSpatialUtils: Spatial Data Download and Utility Functions

#'
#' @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 
#' 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 
#' # 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
#' @export
US_countyNameToFIPS <- function(
  state = NULL,
  countyName = NULL
) {

  # ----- Validate parameters --------------------------------------------------

  state <- as.character(state)
  
  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) ) {
    stateFIPS <- US_stateNameToFIPS(state)
  } else if ( state[1] %in% US_stateCodes$stateFIPS ) {
    stateFIPS <- state
  } else {
    stop(sprintf("state = \"%s\" is not recognized.", state))
  }
  
  # ----- Find countyFIPS ------------------------------------------------------
  
  state_county_name <- 
    paste0(stateFIPS, "_", countyName) %>%
    tolower()
  
  US_state_county_name <-
    paste0(
      MazamaSpatialUtils::US_countyCodes$stateFIPS, 
      "_", 
      MazamaSpatialUtils::US_countyCodes$countyName
    ) %>%
    tolower()
  
  indices <- match(state_county_name, US_state_county_name)
  
  countyFIPS <- 
    MazamaSpatialUtils::US_countyCodes$countyFIPS[indices]
  
  # ----- Return ---------------------------------------------------------------
  
  return(countyFIPS)
  
}

#' @rdname US_countyConversion
#' @export
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) ) 
    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) ) {
    stateFIPS <- US_stateNameToFIPS(state)
  } else if ( state[1] %in% US_stateCodes$stateFIPS ) {
    stateFIPS <- state
  } else {
    stop(sprintf("state = \"%s\" is not recognized.", state))
  }
  
  # ----- Find countyFIPS ------------------------------------------------------
  
  state_county_FIPS <- 
    paste0(stateFIPS, "_", countyFIPS) %>%
    tolower()
  
  US_state_county_FIPS <-
    paste0(
      MazamaSpatialUtils::US_countyCodes$stateFIPS, 
      "_", 
      MazamaSpatialUtils::US_countyCodes$countyFIPS
    ) %>%
    tolower()
  
  indices <- match(state_county_FIPS, US_state_county_FIPS)
  
  countyName <- 
    MazamaSpatialUtils::US_countyCodes$countyName[indices]
  
  # ----- Return ---------------------------------------------------------------
  
  return(countyName)
  
}