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.

Adds a column with the acceleration to each point from 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) –
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)

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

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

Adds a column with the distance to each point from 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)
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.

Adds a column with the speed to each point from 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) –
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 metres.

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

MovingPandas.Trajectory¶

Table of Contents

Previous topic

Next topic

This Page