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

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_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)

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

Return type

GeoDataFrame