dtoolkit.geoaccessor.geodataframe.geodistance#

dtoolkit.geoaccessor.geodataframe.geodistance(df: GeoDataFrame, /, other: BaseGeometry | GeoSeries | GeoDataFrame, align: bool = True, radius: float = 6371008.771415059) → Series[source]#

Returns a Series containing the great-circle distance to aligned other via haversine formula.

\[D(x, y) = 2 \arcsin [ \sqrt{ \sin^2 ((y_2 - y_1) / 2) + \cos(y_1) \cos(y_1) \sin^2 ((x_2 - y_1) / 2) } ]\]

Parameters:

otherBaseGeometry, GeoSeries, or GeoDataFrame
alignbool, default True: If True, automatically aligns GeoSeries based on their indices. If False, the order of elements is preserved.
radiusfloat, default 6371008.7714150598: Great-circle distance uses a spherical model of the earth, using the mean earth radius as defined by the International Union of Geodesy and Geophysics, (2a + b)/3 = 6371008.7714150598 meters for WGS-84.

Returns:

Series(float64): The values are the great-circle distances and its unit is meters.

Raises:

ValueError: If the CRS is not ESGP:4326.
TypeError: If the other is not a BaseGeometry, GeoSeries, or GeoDataFrame.

See also

geopandas.GeoSeries.distance
dtoolkit.geoaccessor.geoseries.geodistance
dtoolkit.geoaccessor.geoseries.geodistance_matrix
dtoolkit.geoaccessor.geodataframe.geodistance
dtoolkit.geoaccessor.geodataframe.geodistance_matrix

Notes

Currently, only supports Point geometry.
The great-circle distance is the angular distance between two points on the surface of a sphere. As the Earth is nearly spherical, the haversine formula provides a good approximation of the distance between two points of the Earth surface, with a less than 1% error on average.

Examples

>>> import dtoolkit.geoaccessor
>>> import pandas as pd
>>> import geopandas as gpd
>>> from shapely import Point
>>> df = (
...     pd.DataFrame({"x": [122, 100], "y":[55, 1]})
...     .from_xy("x", "y", crs=4326)
... )
>>> df
     x   y                    geometry
0  122  55  POINT (122.00000 55.00000)
1  100   1   POINT (100.00000 1.00000)
>>> df.geodistance(Point(120, 30)) / 1e6
0    2.784435
1    3.855604
dtype: float64

Calculate the great-circle distance of paired points.

>>> s = gpd.GeoSeries([Point(120, 30), Point(120, 50)], index=[1, 2], crs=4326)
>>> s
1    POINT (120.00000 30.00000)
2    POINT (120.00000 50.00000)
dtype: geometry
>>> df.geodistance(s) / 1e6
0         NaN
1    3.855604
2         NaN
dtype: float64
>>> df.geodistance(s, align=False) / 1e6
0    2.784435
1    5.768885
dtype: float64