Geography Utils

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

Filtering

trackintel.geogr.spatial_filter(source, areas, method='within', re_project=False)

Filter a GeoDataFrame on a geo extent. Using spatial indexing for improved performance.

Parameters:

• source (GeoDataFrame) – The source feature to perform the spatial filtering

• areas (GeoDataFrame) – The areas used to perform the spatial filtering. Note, you can have multiple Polygons and it will return all the features intersect with ANY of those geometries.

• method ({'within', 'intersects', 'crosses'}, optional) –

  The method to filter the ‘source’ GeoDataFrame, by default ‘within’

  • within: return instances in ‘source’ where no points of these instances lies in the exterior of the ‘areas’ and at least one point of the interior of these instances lies in the interior of ‘areas’.

  • intersects: return instances in ‘source’ where the boundary or interior of these instances intersect in any way with those of the ‘areas’

  • crosses: return instances in ‘source’ where the interior of these instances intersects the interior of the ‘areas’ but does not contain it, and the dimension of the intersection is less than the dimension of the one of the ‘areas’.

• re_project (bool, default False) – If this is set to True, the ‘source’ will be projected to the coordinate reference system of ‘areas’

Returns:

A new GeoDataFrame containing the features after the spatial filtering.

Return type:

GeoDataFrame

Examples

>>> sp.spatial_filter(areas, method="within", re_project=False)

Distance related

trackintel.geogr.point_haversine_dist(lon_1, lat_1, lon_2, lat_2, r=6371000, float_flag=False)

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.calculate_distance_matrix(X, Y=None, dist_metric='haversine', n_jobs=None, **kwds)

Compute the distance matrix from a vector array X and optional Y.

X and Y can either be Point geometries or LineString geometries. 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.

Parameters:

• X (GeoDataFrame) –

• Y (GeoDataFrame, optional) – Should have same geometry type as X

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

  The distance metric to be used for calculating the matrix. By default ‘haversine.

  For Point geometries we provide the ‘haversine’ metric. This function then wraps sklearn.metrics.pairwise_distances. 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 LineStrings, we provide the metrics {‘dtw’, ‘frechet’} via the implementation from similaritymeasures.

• n_jobs (int, optional) – The number of jobs to use for the computation. Ignored for LineStrings. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See sklearn.metrics.pairwise_distances for more informations.

• **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")
>>> pfs.calculate_distance_matrix(dist_metric="haversine")

trackintel.geogr.meters_to_decimal_degrees(meters, latitude)

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.check_gdf_planar(gdf, transform=False)

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.calculate_haversine_length(gdf)

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.get_speed_positionfixes(positionfixes)

Compute speed per positionfix (in m/s)

Parameters:

positionfixes (Positionfixes) –

Returns:

pfs – Copy of the original positionfixes with a new column [`speed`]. The speed is given in m/s

Return type:

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.get_speed_triplegs(triplegs, positionfixes=None, method='tpls_speed')

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

Parameters:

• triplegs (Triplegs) –

• positionfixes (Positionfixes, optional) – Only required if the method is ‘pfs_mean_speed’. In addition to the standard columns positionfixes must include the column [`tripleg_id`].

• method ({'tpls_speed', 'pfs_mean_speed'}, optional) – Method how of speed calculation, default is “tpls_speed” The ‘tpls_speed’ method divides the tripleg distance by its duration, the ‘pfs_mean_speed’ method calculates the speed via the mean speed of the positionfixes of a tripleg.

Returns:

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

Return type:

Triplegs