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.point_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

>>> point_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

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'}, optional) –
The distance metric to be used for calculating the matrix. By default ‘haversine.

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, optional) – Number of cores to use: ‘dtw’, ‘frechet’ and all distance metrics from pairwise_distance (only available if only X is given) are parallelized. By default 1.
**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 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 import calculate_haversine_length
>>> triplegs['length'] = calculate_haversine_length(triplegs)

trackintel.geogr.distances.get_speed_positionfixes(positionfixes)[source]

Compute speed per positionfix (in m/s)

Parameters:: positionfixes (GeoDataFrame (as trackintel positionfixes)) –
Returns:: pfs – Copy of the original positionfixes with a new column [`speed`]. The speed is given in m/s
Return type:: GeoDataFrame (as trackintel positionfixes)

Notes

The speed at one positionfix is computed from the distance and time since the previous positionfix. For the first positionfix, the speed is set to the same value as for the second one.

trackintel.geogr.distances.get_speed_triplegs(triplegs, positionfixes=None, method='tpls_speed')[source]

Compute the average speed per positionfix for each tripleg (in m/s)

Parameters:

triplegs (GeoDataFrame (as trackintel triplegs)) – The generated triplegs as returned by ti.preprocessing.positionfixes.generate_triplegs
(Optional) (positionfixes) – The positionfixes as returned by ti.preprocessing.positionfixes.generate_triplegs. Only required if the method is ‘pfs_mean_speed’. In addition the standard columns it must include the column [`tripleg_id`].
method (str) – Method how the speed is computed, one of {tpls_speed, pfs_mean_speed}. The ‘tpls_speed’ method simply divides the overall tripleg distance by its duration, while the ‘pfs_mean_speed’ method is the mean pfs speed.

Returns:

tpls – The original triplegs with a new column [`speed`]. The speed is given in m/s.

Return type:

GeoDataFrame (as trackintel triplegs)