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, float_flag=False)[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.

  • float_flag (bool, default False) – Optimization flag. Set to True if you are sure that you are only using floats as args.

Returns:

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

Return type:

float or numpy.array

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