MovingPandas.Trajectory

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

class movingpandas.Trajectory(df, traj_id, traj_id_col=None, obj_id=None, t=None, x=None, y=None, crs='epsg:4326', parent=None)
__init__(df, traj_id, traj_id_col=None, 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', units=(None, None, None, None))

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

Acceleration values are computed between the current point and the previous:

If no units have been declared:

  • For geographic projections, in meters per second squared

  • For other projections, in CRS units per second squared

If units have been declared:

  • For geographic projections, using declared units

  • For known CRS units, using declared units

  • For unknown CRS units, using declared units as if CRS distance units are meters

  • If only distance units are declared, returns distance per second squared

  • If distance and one time unit declared, returns distance/time per second

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

  • name (str) – Name of the acceleration column (default: “acceleration”)

  • units (tuple(str)) –

    Units in which to calculate acceleration

    distancestr

    Abbreviation for the distance unit (default: CRS units, or metres if geographic)

    timestr

    Abbreviation for the time unit (default: seconds)

    time2str

    Abbreviation for the second time unit (default: seconds)

    For more info, check the list of supported units at https://movingpandas.org/units

Examples

If no units are declared, the acceleration will be calculated in meters per second squared for geographic projections and in CRS distance units per second squared for all other projections

>>>traj.add_acceleration()

The default column name is “acceleration”. If a column of this name already exists, a new column name can be specified

>>>traj.add_acceleration(name=”acceleration (CRS units/s2)”)

If units are declared, acceleration will be calculated in those units except if the CRS distance units are unknown, in which case the CRS distance units are assumed to be meters

>>>traj.add_acceleration(units=(“km”, “h”, “s”))

It is suggested to declare a name for the new column specifying units

>>>traj.add_acceleration(name=”US Survey Feet/s2”, units=(“survey_ft”, “s”)) >>>traj.add_acceleration(name=”mph/s”, units=(“mi”, “h”, “s”))

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)

  • name (str) – Name of the direction column (default: “direction”)

add_distance(overwrite=False, name='distance', units=None)

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

Distance values are computed between the current point and the previous:

If no units have been declared:

  • For geographic projections (e.g. EPSG:4326 WGS84), in meters

  • For other projections, in CRS units

If units have been declared:

  • For geographic projections, in declared units

  • For known CRS units, in declared units

  • For unknown CRS units, in declared units as if CRS is in meters

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

  • name (str) – Name of the distance column (default: “distance”)

  • units (str) – Units in which to calculate distance values (default: CRS units) For more info, check the list of supported units at https://movingpandas.org/units

Examples

If no units are declared, the distance will be calculated in meters for geographic projections (e.g. EPSG:4326 WGS84) and in CRS units for all other projections

>>>traj.add_distance()

The default column name is “distance”. If a column of this name already exists, a new column name can be specified

>>>traj.add_distance(name=”distance (CRS units)”)

If units are declared, the distance will be calculated in those units except if the CRS units are unknown, in which case the CRS units are assumed to be in meters

>>>traj.add_distance(units=”km”)

It is suggested to declare a name for the new column specifying units

>>>traj.add_distance(name=”distance (miles)”, units=”mi”) >>>traj.add_distance(name=”distance (US Survey Feet)”, units=”survey_ft”)

add_speed(overwrite=False, name='speed', units=(None, None, None, None))

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

Speed values are computed between the current point and the previous:

If no units have been declared:

  • For geographic projections, in meters per second

  • For other projections, in CRS units per second

If units have been declared:

  • For geographic projections, in declared units

  • For known CRS units, in declared units

  • For unknown CRS units, in declared units as if CRS distance units are meters

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

  • name (str) – Name of the speed column (default: “speed”)

  • units (tuple(str)) –

    Units in which to calculate speed

    distancestr

    Abbreviation for the distance unit (default: CRS units, or metres if geographic)

    timestr

    Abbreviation for the time unit (default: seconds)

    For more info, check the list of supported units at https://movingpandas.org/units

Examples

If no units are declared, the speed will be calculated in meters per second for geographic projections (e.g. EPSG:4326 WGS84) and in CRS distance units per second for all other projections

>>>traj.add_speed()

The default column name is “speed”. If a column of this name already exists, a new column name can be specified

>>>traj.add_speed(name=”speed (CRS units)”)

If units are declared, the speed will be calculated in those units except if the CRS distance units are unknown, in which case the CRS distance units are assumed to be meters

>>>traj.add_speed(units=(“km”, “h”))

It is suggested to declare a name for the new column specifying units

>>>traj.add_speed(name=”speed (mph)”, units=(“mi”, “h”)) >>>traj.add_speed(name=”US Survey Feet/s”, units=(“survey_ft”, “s”))

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, units=(None, None, None, None))

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

If units have been declared:

  • For geographic projections, in declared units

  • For known CRS units, in declared units

  • For unknown CRS units, in declared units as if CRS is in meters

Parameters:
  • other (shapely.geometry or Trajectory) – Other geometric object or trajectory

  • units (str) – Units in which to calculate distance values (default: CRS units) For more info, check the list of supported units at https://movingpandas.org/units

Returns:

Distance

Return type:

float

drop(**kwargs)

Drop columns or rows from the trajectory DataFrame

Examples

>>> trajectory.drop(columns=['abc','def'])
get_angular_difference_col()

Return 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_column_names()

Return the list of column names

Return type:

list

get_crs()

Return the CRS of the trajectory

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_col()

Return name of the direction column

Return type:

string

get_distance_col()

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_col()

Return name of the geometry column

Return type:

string

get_length(units=(None, None, None, None))

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

If units have been declared:

  • For geographic projections, in declared units

  • For known CRS units, in declared units

  • For unknown CRS units, in declared units as if CRS is in meters

Parameters:

units (tuple(str)) – Units in which to calculate length values (default: CRS units) For more info, check the list of supported units at https://movingpandas.org/units

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_max(column)

Return maximum value in the provided DataFrame column

Parameters:

column (string) – Name of the DataFrame column

Returns:

Maximum value

Return type:

Sortable

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_min(column)

Return minimum value in the provided DataFrame column

Parameters:

column (string) – Name of the DataFrame column

Returns:

Minimum value

Return type:

Sortable

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_col()

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_col()

Return name of the timedelta column

Return type:

string

get_traj_id_col()

Return name of the trajectory ID column

Return type:

string

hausdorff_distance(other, units=(None, None, None, None))

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.

If units have been declared:

  • For geographic projections, in declared units

  • For known CRS units, in declared units

  • For unknown CRS units, in declared units as if CRS is in meters

Parameters:
  • other (shapely.geometry or Trajectory) – Other geometric object or trajectory

  • units (str) – Units in which to calculate distance values (default: CRS units) For more info, check the list of supported units at https://movingpandas.org/units

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’, marker_size=200, line_width=2.0

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 polygon 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_latlon()

Return True if the trajectory CRS is geographic (e.g. EPSG:4326 WGS84)

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)

Return 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(columns=None)

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_orig_tz=False)

Return the trajectory’s points as GeoDataFrame.

Parameters:

return_orig_tz (bool) – If True, adds timezone info back to df

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