help lhaversine

Title

lhaversine -- Mata library for distance functions

Syntax

real matrix
hav_dist(lat_a, lng_a, lat_b, lng_b [, rd])

real matrix
hav_distm(lat_a, lng_a, lat_b, lng_b [, rd])

real matrix
hav_inrange(lat_a, lng_a, lat_b, lng_b, rn [, rd])

real matrix
hav_inrangem(lat_a, lng_a, lat_b, lng_b, rn [, rd])

real matrix
hav_ninrange(lat_a, lng_a, lat_b, lng_b, rn [, rd])

real matrix
hav_ninrangem(lat_a, lng_a, lat_b, lng_b, rn [, rd])

where

lat_a is a real colvector

lng_a is a real colvector

lat_b is real colvector

lng_b is a real colvector

rd is a real scalar

rn is a real scalar

Description

All functions in lhaversine use the haversine formula for great-circle distances, https://en.wikipedia.org/wiki/Haversine_formula. The geographical coordinates must be in signed decimal degress.
Latitudes range from -90 to 90. Longitudes range from -180 to 180. To convert radians into degress, multiply by pi/180.

hav_dist()
returns a matrix of distances between A locations and B locations. The results are in kilometres. hav_dist() takes the latitudes (column vector lat_a) and
longitudes (column vector lng_a) of the A locations and the latitudes (column vector lat_b) and longitudes (column vector lng_b) of the B locations as inputs. The optional argument (rd) allows the
user to specifiy the earth radius. The default is 6,371 kilometres.

hav_distm()
returns a distance matrix in miles. The default radius is 3,958.76 miles.

hav_inrange()
returns a matrix of ones and zeros, indicating if a B location is within a given range of an A location. The range (rn) needs to be specified by the user and is in kilometers. The hav_dist() takes the latitudes lat_a and longitudes lng_b of the A locations and the latitudes
lat_b and longitudes lng_b as inputs. The optional argument (rd) allows the user to specifiy the earth radius. The default is 6,371 kilometres.

hav_inrangem()
returns a matrix of ones and zeros, indicating if a B location is within a range of (rn) miles of an a location. The optional argument (rd) allows the user to specifiy the earth radius. The default is 3,958.76 miles.

hav_inrange()
returns a column vector containing the number of B locations that are within a given range of an A location. The range (rn) needs to be specified by the user and is in kilometers. The optional argument (rd) allows the user to specifiy the earth radius. The default is 6,371 kilometres.

hav_ninrangem()
returns a column vector with the number of B locations that are within a range of (rn) miles of an A location. The optional argument (rd) allows the user to specifiy the earth radius. The default is 3,958.76 miles.

Examples

Define the latitudes and longitudes of two A und three B locations:

: lat_a = 53.1205306\53.2056589
: lng_a = 8.101857\8.2530387
: lat_b = 53.1479943\53.2450662\51.2082624
: lng_b = 7.8664467\6.8423613\8.2001266

Obtain distances between A und B locations in kilometres using hav_dist():

: hav_dist(lat_a, lng_a, lat_b, lng_b)
1 2 3
+
+
1 | 15.99849446 229.3229587 15.31791198 |
2 | 26.55005308 241.9975468 5.622063328 |
+
+

Obtain distances in miles with user-specified radius of 3960 miles using hav_distm():

: rd = 3960

: hav_distm(lat_a, lng_a, lat_b, lng_b, rd)
1 2 3
+
+
1 | 9.944127774 142.5394627 9.521100523 |
2 | 16.50262285 150.4175617 3.494486074 |
+
+

Generate a matrix indicating which B locations are within a 25km range of the A locations using hav_inrange():

: rn = 25

: hav_inrange(lat_a, lng_a, lat_b, lng_b, rn)
1 2 3
+
+
1 | 1 0 1 |
2 | 0 0 1 |
+
+

Generate a column vector containing the number of B locations that are within a 25km range of the A locations using hav_ninrange():

: hav_mindist(lat_a, lng_a, lat_b, lng_b, rn)
1
+-------+
1 | 2 |
2 | 1 |
+-------+

Conformability

hav_dist(lat_a, lng_a, lat_b, lng_b [, rd]):
lat_a: n x 1
lng_a: n x 1
lat_b: k x 1
lng_b: k x 1
rd: 1 x 1
result: n x k.

hav_distm() is analogue

hav_inrange(lat_a, lng_a, lat_b, lng_b, rn [, rd]):
lat_a: n x 1
lng_a: n x 1
lat_b: k x 1
lng_b: k x 1
rn: 1 x 1
rd: 1 x 1
result: n x k.

hav_inrangem() is analogue

hav_ninrange(lat_a, lng_a, lat_b, lng_b, rn [, rd]):
lat_a: n x 1
lng_a: n x 1
lat_a: k x 1
lng_a: k x 1
rn: 1 x 1
rd: 1 x 1
result: n x 1.

hav_ninrangem() is analogue

Author

Lars Zeigermann, lars.zeigermann@posteo.de

Acknowledgment

lhaversine is based on geodist written bei Robert Picard und reuses some of its code.