MovingPandas.Trajectory

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

class movingpandas.Trajectory(df, traj_id, obj_id=None, parent=None)
__init__(df, traj_id, obj_id=None, parent=None)

Create Trajectory from GeoDataFrame.

Parameters:
  • df (GeoDataFrame) – GeoDataFrame with point geometry column and timestamp index
  • traj_id (any) – Trajectory ID
  • obj_id (any) – Moving object ID
  • 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_direction(overwrite=False)

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

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

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

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)
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, pointbased=False)

Return trajectory 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
  • pointbased (bool) – Clipping method
Returns:

Clipped trajectory segments

Return type:

list

copy()

Return a copy of the trajectory.

Returns:
Return type:Trajectory
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_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

Returns:
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_position_at(t, method='interpolated')

Compute and return position at time t.

Parameters:
  • t (datetime.datetime) – Timestamp to extract a row for
  • method (str) – Access 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) – Pandas get_loc method
Returns:

Row of the dataframe at time t

Return type:

Pandas series

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

Returns:
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
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
Returns:

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, pointbased=False)

Return the trajectory segment 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
  • pointbased (bool) – Clipping method
Returns:

Trajectory segment intersecting with the feature

Return type:

Trajectory

intersects(polygon)

Return whether the trajectory intersects the given polygon.

Parameters:polygon (shapely Polygon) – Polygon to test for intersections
Returns:
Return type:bool
is_valid()

Return whether the trajectory meets minimum requirements.

Returns:
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
Returns:

Return type:

Matplotlib plot

Examples

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

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

Split trajectory into subtrajectories using regular time intervals.

Parameters:mode (str) – Split mode
Returns:List of trajectories
Return type:list
split_by_observation_gap(gap)

Split the trajectory into subtrajectories whenever there is a gap in the observations.

Parameters:gap (datetime.timedelta) – Time gap threshold
Returns:List of trajectories
Return type:list
to_crs(crs)

Returns the trajectory reprojected to the target CRS.

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

Examples

Reproject a trajectory to EPSG:4088

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

Return trajectory geometry as LineString.

Returns:
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