R/deltalon.per.km.R

In ejanalysis/proxistat: Create a Proximity Score in Each Census Unit, Based on Distances to Specified Points (as in EPA's EJScreen tool, for example)

#' @title Convert kilometers (East-West) to degrees longitude.
#'
#' @description
#' \code{deltalon.per.km} returns change in decimal degrees longitude per kilometer (East-West), given latitude (Northern Hemisphere).
#' 
#' @details
#' This function returns the change in decimal degrees longitude per kilometer moving East-West, at a given latitude (N. Hemisphere).
#' This is an approximation and is less accurate further from the given latitude.
#' The degrees of longitude per km traveled East-West is larger closer to the poles, and smallest at the equator.
#' See \url{http://en.wikipedia.org/wiki/Longitude} and \url{http://en.wikipedia.org/wiki/Decimal_degrees}
#' Not using \code{meters.per.degree.lon} the results would be roughly ( 1 / ((pi/180) * 6378.137 * cos(lat * 0.01745329)) )
#' where 0.01745329 is pi/180 to convert to radians. see \url{http://en.wikipedia.org/wiki/Decimal_degrees}
#' The equator is divided into 360 degrees of longitude, so 
#' each degree at the equator represents 111,319.9 metres or approximately 111.32 km.
#' As one gets further from the equator, one degree of longitude 
#' must be multiplied by the cosine of the latitude, decreasing distance per degree lon, approaching zero at the pole.
#' For most northern point of USA \code{http://en.wikipedia.org/wiki/Extreme_points_of_the_United_States}, where 
#' one finds maximum degrees lon per mile, latitude is just under 72, and cos of 72 degrees= cos(72 * pi/180) = 0.309 , 
#' so miles/degrees is about 111.32 km * 0.309 = 34.4 km = 21.4 miles roughly.
#'
#' @param lat The decimal degrees of latitude of the Northern Hemisphere location(s) of interest, as number or vector of numbers.
#' @return Returns decimal degrees longitude per km traveled E-W, as a number or vector of numbers the same length as the input lat.
#' @seealso \code{\link{meters.per.degree.lon}} for the inverse of this function (other than a factor of 1000),
#'   and \code{\link{get.distances}} which allows you to specify a search radius and 
#'   get distances only within that radius, and related functions.
#' @concept proximity
#' @examples
#' deltalon.per.km(0) 
#'   # Roughly 111 km/degree moved East-West at the equator roughly, or around 21 miles.
#' deltalon.per.km(c(0,45,72))
#' @export
deltalon.per.km <- function(lat) {
  return( 1000 / meters.per.degree.lon(lat))
}