MovingPandas.Trajectory¶

movingpandas: Implementation of Trajectory classes and functions built on top of GeoPandas

class movingpandas.Trajectory(df, traj_id, obj_id=None, t=None, x=None, y=None, crs='epsg:4326', parent=None)¶

__init__(df, traj_id, obj_id=None, t=None, x=None, y=None, crs='epsg:4326', parent=None)¶

Create Trajectory from GeoDataFrame or DataFrame.

Parameters:

df (GeoDataFrame or DataFrame) – GeoDataFrame with point geometry column and timestamp index
traj_id (any) – Trajectory ID
obj_id (any) – Moving object ID
t (string) – Name of the DataFrame column containing the timestamp
x (string) – Name of the DataFrame column containing the x coordinate
y (string) – Name of the DataFrame column containing the y coordinate
crs (string) – CRS of the x/y coordinates
parent (Trajectory) – Parent trajectory

Examples

Creating a trajectory from scratch:

>>> import pandas as pd
>>> import geopandas as gpd
>>> import movingpandas as mpd
>>> from fiona.crs import from_epsg
>>>
>>> df = pd.DataFrame([
...     {'geometry':Point(0,0), 't':datetime(2018,1,1,12,0,0)},
...     {'geometry':Point(6,0), 't':datetime(2018,1,1,12,6,0)},
...     {'geometry':Point(6,6), 't':datetime(2018,1,1,12,10,0)},
...     {'geometry':Point(9,9), 't':datetime(2018,1,1,12,15,0)}
... ]).set_index('t')
>>> gdf = gpd.GeoDataFrame(df, crs=from_epsg(31256))
>>> traj = mpd.Trajectory(gdf, 1)

For more examples, see the tutorial notebooks.

add_acceleration(overwrite=False, name='acceleration')¶

Add acceleration column and values to the trajectory’s DataFrame.

Acceleration is calculated as CRS units per second squared, except if the CRS is geographic (e.g. EPSG:4326 WGS84) then speed is calculated in meters per second squared.

add_angular_difference(overwrite=False, name='angular_difference')¶

Add angular difference to the trajectory’s DataFrame.

Angular difference is calculated as the absolute smaller angle between direction for points along the trajectory. Values are [0, 180.0]

add_direction(overwrite=False, name='direction')¶

Add direction column and values to the trajectory’s DataFrame.

The direction is calculated between consecutive locations. Direction values are in degrees, starting North turning clockwise. Values are [0, 360).

Parameters:: overwrite (bool) – Whether to overwrite existing direction values (default: False)

add_distance(overwrite=False, name='distance')¶

Add distance column and values to the trajectory’s DataFrame.

Distance is calculated as CRS units, except if the CRS is geographic (e.g. EPSG:4326 WGS84) then distance is calculated in meters.

Parameters:: overwrite (bool) – Whether to overwrite existing distance values (default: False)

add_speed(overwrite=False, name='speed')¶

Add speed column and values to the trajectory’s DataFrame.

Speed is calculated as CRS units per second, except if the CRS is geographic (e.g. EPSG:4326 WGS84) then speed is calculated in meters per second.

Parameters:

overwrite (bool) – Whether to overwrite existing speed values (default: False)
name (str) – Name of the speed column (default: “speed”)

add_timedelta(overwrite=False, name='timedelta')¶

Add timedelta column and values to the trajectory’s DataFrame.

Timedelta is calculated as the time difference between the current and the previous row. Values are instances of datetime.timedelta.

Parameters:

overwrite (bool) – Whether to overwrite existing timedelta values (default: False)
name (str) – Name of the timedelta column (default: “timedelta”)

add_traj_id(overwrite=False)¶

Add trajectory id column and values to the trajectory’s DataFrame.

Parameters:: overwrite (bool) – Whether to overwrite existing trajectory id values (default: False)

apply_offset_minutes(column, offset)¶

Shift column by the specified offset in minutes.

Parameters:

column (str) – Name of the column to shift
offset (int) – Number of minutes to shift by, can be positive or negative

apply_offset_seconds(column, offset)¶

Shift column by the specified offset in seconds.

Parameters:

column (str) – Name of the column to shift
offset (int) – Number of seconds to shift by, can be positive or negative

clip(polygon, point_based=False)¶

Return trajectory segments clipped by the given polygon.

By default, the trajectory’s line representation is clipped by the polygon. If pointbased=True, the trajectory’s point representation is used instead, leading to shorter segments.

Parameters:

polygon (shapely Polygon) – Polygon to clip with
point_based (bool) – Clipping method

Returns:

Clipped trajectory segments

Return type:

TrajectoryCollection

copy()¶

Return a copy of the trajectory.

Return type:: Trajectory

distance(other)¶

Return the minimum distance to the other geometric object (based on shapely https://shapely.readthedocs.io/en/stable/manual.html#object.distance).

Parameters:: other (shapely.geometry or Trajectory) – Other geometric object or trajectory
Returns:: Distance
Return type:: float

get_angular_difference_column_name()¶

Retrun name of the angular difference column

Return type:: string

get_bbox()¶

Return the trajectory’s bounding box.

Returns:: Bounding box values (minx, miny, maxx, maxy)
Return type:: tuple

get_direction()¶

Return the direction of the trajectory.

The direction is calculated between the trajectory’s start and end location. Direction values are in degrees, starting North turning clockwise.

Returns:: Direction of the trajectory in degrees
Return type:: float

get_direction_column_name()¶

Return name of the direction column

Return type:: string

get_distance_column_name()¶

Return name of the distance column

Return type:: string

get_duration()¶

Return the trajectory’s duration from start to end.

Returns:: Trajectory duration
Return type:: datetime.timedelta

get_end_location()¶

Return the trajectory’s end location.

Returns:: Trajectory end location
Return type:: shapely Point

get_end_time()¶

Return the trajectory’s end time.

Returns:: Trajectory end time
Return type:: datetime.datetime

get_geom_column_name()¶

Return name of the geometry column

Return type:: string

get_length()¶

Return the length of the trajectory.

Length is calculated using CRS units, except if the CRS is geographic (e.g. EPSG:4326 WGS84) then length is calculated in metres.

Returns:: Length of the trajectory
Return type:: float

get_linestring_between(t1, t2, method='interpolated')¶

Return LineString of segment between times t1 and t2.

Parameters:

t1 (datetime.datetime) – Start time for the segment
t2 (datetime.datetime) – End time for the segment
method (str) – Extraction method

Returns:

Extracted trajectory segment

Return type:

shapely LineString

get_mcp()¶

Return the Minimum Convex Polygon of the trajectory data

Returns:: mcp – The polygon or line (in case of only two points) of the Minimum Convex Polygon
Return type:: Shapely object

get_position_at(t, method='interpolated')¶

Compute and return position at time t.

Parameters:

t (datetime.datetime) – Timestamp to extract a row for
method (str) – Interpolation method

Returns:

Position at time t

Return type:

shapely Point

Examples

If the trajectory contains a position at the given timestamp, it is returned:

>>> traj.get_position_at(datetime(2018, 1, 1, 12, 6))
Point (6 0)

If there is no trajectory position for the given timestamp, the default behaviour is to interpolate the location:

>>> traj.get_position_at(datetime(2018, 1, 1, 12, 9))
POINT (6 4.5)

To get the trajectory position closest to the given timestamp, specify method=’nearest’:

>>> traj.get_position_at(datetime(2018, 1, 1, 12, 9), method='nearest')
POINT (6 6)

get_row_at(t, method='nearest')¶

Return row of the trajectory’s DataFrame at time t.

Parameters:

t (datetime.datetime) – Timestamp to extract a row for
method (str) – Interpolation method (Pandas get_loc method)

Returns:

Row of the DataFrame at time t

Return type:

Pandas series

get_sampling_interval()¶

Return the sampling interval of the trajectory.

The sampling interval is computed as the median time difference between consecutive rows in the trajectory’s DataFrame.

Returns:: Sampling interval
Return type:: datetime.timedelta

get_segment_between(t1, t2)¶

Return Trajectory segment between times t1 and t2.

Parameters:

t1 (datetime.datetime) – Start time for the segment
t2 (datetime.datetime) – End time for the segment

Returns:

Extracted trajectory segment

Return type:

Trajectory

get_speed_column_name()¶

Return name of the speed column

Return type:: string

get_start_location()¶

Return the trajectory’s start location.

Returns:: Trajectory start location
Return type:: shapely Point

get_start_time()¶

Return the trajectory’s start time.

Returns:: Trajectory start time
Return type:: datetime.datetime

get_timedelta_column_name()¶

Return name of the timedelta column

Return type:: string

hausdorff_distance(other)¶

Return the Hausdorff distance to the other geometric object (based on shapely https://shapely.readthedocs.io/en/stable/manual.html#object.hausdorff_distance). The Hausdorff distance between two geometries is the furthest distance that a point on either geometry can be from the nearest point to it on the other geometry.

Parameters:: other (shapely.geometry or Trajectory) – Other geometric object or trajectory
Returns:: Hausdorff distance
Return type:: float

hvplot(*args, **kwargs)¶

Generate an interactive plot using HoloViews.

The following parameters are set by default: geo=True, tiles=’OSM’.

Parameters:

args – These parameters will be passed to the TrajectoryPlotter
kwargs – These parameters will be passed to the TrajectoryPlotter

Return type:

Holoviews plot

Examples

Plot speed along trajectory (with legend and specified figure size):

>>> trajectory.hvplot(c='speed', line_width=7.0, width=700, height=400, colorbar=True)

interpolate_position_at(t)¶

Compute and return interpolated position at time t.

Parameters:: t (datetime.datetime) – Timestamp to interpolate at
Returns:: Interpolated position along the trajectory at time t
Return type:: shapely Point

intersection(feature, point_based=False)¶

Return the trajectory segments that intersects the given feature.

Feature attributes are appended to the trajectory’s DataFrame.

By default, the trajectory’s line representation is clipped by the polygon. If pointbased=True, the trajectory’s point representation is used instead, leading to shorter segments.

Parameters:

feature (shapely Feature) – Feature to intersect with
point_based (bool) – Clipping method

Returns:

Segments intersecting with the feature

Return type:

TrajectoryCollection

intersects(polygon)¶

Return whether the trajectory intersects the given polygon.

Parameters:: polygon (shapely.geometry.Polygon) – Polygon to test for intersections
Return type:: bool

is_valid()¶

Return whether the trajectory meets minimum requirements.

Return type:: bool

plot(*args, **kwargs)¶

Generate a plot using GeoPandas default plotting (Matplotlib).

Parameters:

args – These parameters will be passed to the TrajectoryPlotter
kwargs – These parameters will be passed to the TrajectoryPlotter

Return type:

Matplotlib plot

Examples

Plot speed along trajectory (with legend and specified figure size):

>>> trajectory.plot(column='speed', legend=True, figsize=(9,5))

size()¶

Returns number of rows in Trajectory.df

Returns:: size – Number of rows
Return type:: int

to_crs(crs)¶

Returns the trajectory reprojected to the target CRS.

Parameters:: crs (pyproj.CRS) – Target coordinate reference system
Return type:: Trajectory

Examples

Reproject a trajectory to EPSG:4088

>>> from pyproj import CRS
>>> reprojected = trajectory.to_crs(CRS(4088))

to_line_gdf()¶

Return the trajectory’s line segments as GeoDataFrame.

Return type:: GeoDataFrame

to_linestring()¶

Return trajectory geometry as LineString.

Return type:: shapely LineString

to_linestringm_wkt()¶

Return the WKT string of the trajectory LineStringM representation.

Returns:: WKT of trajectory as LineStringM
Return type:: string

to_point_gdf()¶

Return the trajectory’s points as GeoDataFrame.

Return type:: GeoDataFrame

to_traj_gdf(wkt=False, agg=False)¶

Return a GeoDataFrame with one row containing the trajectory as a single LineString.

Parameters:

wkt (bool) – If True, adds WKT column representing the trajectory geometry
agg (dict) – Adds columns with aggregate values computed from trajectory dataframe columns according to specified aggregation mode, using pandas.DataFrame.agg(), and shortcuts for “mode” and quantiles (e.g. “q5” or “q95”)

Examples

>>> traj.to_traj_gdf(agg={"col1": "mode", "col2": ["min", "q95"]})

Return type:: GeoDataFrame

MovingPandas.Trajectory¶

Table of Contents

Previous topic

Next topic

This Page