Geography Utils

To make handling of mobility and geodata easier, trackintel features several geographic utility functions and distance functions for points and trajectories

trackintel.geogr.distances.calculate_distance_matrix(X, Y=None, dist_metric='haversine', n_jobs=0, **kwds)[source]

Calculate a distance matrix based on a specific distance metric.

If only X is given, the pair-wise distances between all elements in X are calculated. If X and Y are given, the distances between all combinations of X and Y are calculated. Distances between elements of X and X, and distances between elements of Y and Y are not calculated.

Parameters

  • X (GeoDataFrame (as trackintel staypoints or triplegs)) –

  • Y (GeoDataFrame (as trackintel staypoints or triplegs), optional) –

  • dist_metric ({'haversine', 'euclidean', 'dtw', 'frechet'}) –

    The distance metric to be used for calculating the matrix.

    For staypoints, common choice is ‘haversine’ or ‘euclidean’. This function wraps around the pairwise_distance function from scikit-learn if only X is given and wraps around the scipy.spatial.distance.cdist function if X and Y are given. Therefore the following metrics are also accepted:

    via scikit-learn: [‘cityblock’, ‘cosine’, ‘euclidean’, ‘l1’, ‘l2’, ‘manhattan’]

    via scipy.spatial.distance: [‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘correlation’, ‘dice’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘yule’]

    For triplegs, common choice is ‘dtw’ or ‘frechet’. This function uses the implementation from similaritymeasures.

  • n_jobs (int) – Number of cores to use: ‘dtw’, ‘frechet’ and all distance metrics from pairwise_distance (only available if only X is given) are parallelized.

  • **kwds – optional keywords passed to the distance functions.

Returns

D – matrix of shape (len(X), len(X)) or of shape (len(X), len(Y)) if Y is provided.

Return type

np.array

Examples

>>> calculate_distance_matrix(staypoints, dist_metric="haversine")
>>> calculate_distance_matrix(triplegs_1, triplegs_2, dist_metric="dtw")
trackintel.geogr.distances.meters_to_decimal_degrees(meters, latitude)[source]

Convert meters to decimal degrees (approximately).

Parameters

  • meters (float) – The meters to convert to degrees.

  • latitude (float) – As the conversion is dependent (approximatively) on the latitude where the conversion happens, this needs to be specified. Use 0 for the equator.

Returns

An approximation of a distance (given in meters) in degrees.

Return type

float

Examples

>>> meters_to_decimal_degrees(500.0, 47.410)
trackintel.geogr.distances.check_gdf_planar(gdf, transform=False)[source]

Check if a GeoDataFrame has a planar or projected coordinate system.

Optionally transform a GeoDataFrame into WGS84.

Parameters

  • gdf (GeoDataFrame) – input GeoDataFrame for checking or transform

  • transform (bool, default False) – whether to transform gdf into WGS84.

Returns

  • is_planer (bool) – True if the returned gdf has planar crs.

  • gdf (GeoDataFrame) – if transform is True, return the re-projected gdf.

Examples

>>> from trackintel.geogr.distances import check_gdf_planar
>>> check_gdf_planar(triplegs, transform=False)
trackintel.geogr.distances.calculate_haversine_length(gdf)[source]

Calculate the length of linestrings using the haversine distance.

Parameters

gdf (GeoDataFrame with linestring geometry) – The coordinates are expected to be in WGS84

Returns

length – The length of each linestring in meters

Return type

np.array

Examples

>>> from trackintel.geogr.distances import calculate_haversine_length
>>> triplegs['length'] = calculate_haversine_length(triplegs)

Point distances

trackintel.geogr.point_distances.haversine_dist(lon_1, lat_1, lon_2, lat_2, r=6371000)[source]

Compute the great circle or haversine distance between two coordinates in WGS84.

Serialized version of the haversine distance.

Parameters

  • lon_1 (float or numpy.array of shape (-1,)) – The longitude of the first point.

  • lat_1 (float or numpy.array of shape (-1,)) – The latitude of the first point.

  • lon_2 (float or numpy.array of shape (-1,)) – The longitude of the second point.

  • lat_2 (float or numpy.array of shape (-1,)) – The latitude of the second point.

  • r (float) – Radius of the reference sphere for the calculation. The average Earth radius is 6’371’000 m.

Returns

An approximation of the distance between two points in WGS84 given in meters.

Return type

float

Examples

>>> haversine_dist(8.5, 47.3, 8.7, 47.2)
18749.056277719905

References

https://en.wikipedia.org/wiki/Haversine_formula https://stackoverflow.com/questions/19413259/efficient-way-to-calculate-distance-matrix-given-latitude-and-longitude-data-in