% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/distance_by_haversine.R
\name{distance_by_haversine}
\alias{distance_by_haversine}
\title{Function to calculate distances between two points in metres or kilometres.}
\usage{
distance_by_haversine(
  latitude,
  longitude,
  latitude_lag = NA,
  longitude_lag = NA,
  unit = "metres",
  radius = 6371
)
}
\arguments{
\item{latitude}{A vector of latitude values in decimal degrees.}

\item{longitude}{A vector of longitude values in decimal degrees.}

\item{latitude_lag}{A vector of latitude values in decimal degrees.}

\item{longitude_lag}{A vector of longitude values in decimal degrees.}

\item{unit}{The unit of the returned distance values. Can be metres or 
kilometres. Metres is the default.}

\item{radius}{The radius of the Earth in kilometres. The default value is
6371, but I have seen versions of similar functions which use slightly
different values (plus or minus two or three kilometres) so this value can
be altered.}
}
\description{
\code{distance_by_haversine} is used when distances between latitude and 
longitude-pairs need to be represented in metre or kilometre units. The 
distances between two points is based on the Haversine Formula which is 
approximate and is most appropriate when used for short-distance calculations.
}
\details{
The Haversine Formula does not compensate for Earth's non-spherical shape, 
will overestimate distances in the polar regions but will underestimate 
distances near the equator. For more information see 
\url{https://en.wikipedia.org/wiki/Haversine_formula}

\code{distance_by_haversine} is not a spatial function and does not have any
geographic library dependencies. If a spatial funcion is desired or distances
to/betwwen lines or polygons need to be calculated see 
\code{\link{sp_distance}}.
}
\examples{
\dontrun{
# What is the distance between Oxford's Radcliffe Camera and Cliveden House 
in Buckinghamshire? 
# In metres
distance_by_haversine(51.753447, -1.254024, 51.558170, -0.688250)
44662.57

# In kilometres
distance_by_haversine(51.753447, -1.254024, 51.558170, -0.688250, "km")
44.66257

# or because we are in a locale with a different distance unit, in miles
distance_by_haversine(51.753447, -1.254024, 51.558170, -0.688250, "km") * 0.62
27.69079


# Data frame usage
# Distances of many air quality monitoring sites from the City of London
data_air$distance <- distance_by_haversine(
  data_air$latitude, data_air$longitude, 51.513468, -0.089133, "km")
  
# Arrange by distance, closest at the top
data_air <- plyr::arrange(data_air, distance)

}

}
\seealso{
See \code{\link{gDistance}}
}
\author{
Stuart K. Grange
}
