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:
- copy()¶
Return a copy of the trajectory.
- Return type:
- 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:
- 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:
- 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:
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