# Trajectory Analysis

{% hint style="warning" %}
This extension leverages Python UDFs in your data warehouse, which may offer different performance than other Workflow components. At the moment we recommend working with datasets smaller than 10M trajectory points at a time, and applying optimizations such as [Trajectory Simplifier](#trajectory-simplifier) or [Trajectory Cleaner](#trajectory-cleaner) before running other components or analysis. Before using this extension:

1. Make sure that your data warehouse allows the usage of Python UDFs
2. Please get in touch if your use case requires a larger scale.
   {% endhint %}

Trajectories and data from moving vehicles, collected from vehicles, pedestrians, GPS, AIS, and other sources, are a key input for many geospatial analyses, especially within the logistics and mobility industries. 

This CARTO extension provides a set of tools to analyze trajectory data, including cleaning and simplifying trajectories, computing metrics (speeds, positions, distances...), stop detection, and more.

{% hint style="success" %}
The CARTO Trajectory Analysis extension provides similar functionality as the [Moving Pandas](https://movingpandas.org/) Python library, with the additional benefit of running within your Data Warehouse, orchestrated with CARTO Workflows.
{% endhint %}

## Trajectory from Points

**Description**

This component converts a table containing **points with timestamps into trajectories**, where each row represents a complete trajectory. The resulting table is ready to be used with the rest of the Trajectory Analysis extension components. 

**Inputs**

* `Input table [Table]` : A table containing points with timestamps, and optional properties.
* `Trajectory IDs column [Column]` : The column in the *input table* that will be used as the Trajectory ID. This must be unique per trajectory/trip.
* `Geometry column [Column]` : The location information for each trajectory point. Must be a geography/geometry type column.
* `Timestamp column [Column]` : The timestamp for each point in the trajectory. Must be a timestamp-type column.
* `Trajectory points column name [String]` : The desired name for the resulting column in the *Output table* that will contain points for each trajectory. By default it is `tpoints`.
* `Properties columns [Column(s)]` : Select the extra properties (columns) for each point that you wish to keep in the resulting table. Typically these will be things like *temperature, speed, vehicle\_id,* etc. You can select multiple columns.

**Outputs**

* `Output table [Trajectories Table]` 

## Trajectory to Points

**Description**

This component converts a table containing **nested trajectories into a flattened list of points**, where each row represents a point in a trajectory. The resulting table is ready to be visualized and analyzed point-to-point. 

**Inputs**

* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs .
*  `Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory. 
*  `Return step-by-step lines [Boolean]` : Activate this so that the *output table* contains line geometries for each segment, allowing continuous visualization of the trajectory, rather than point-based visualizations.

**Outputs**

* `Output table [Table]` 

## Trajectory Splitter

**Description**

This component splits a trajectory into different segments, based on a criteria like stop detection, speed changes, angle changes, etc...

**Inputs**

* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs
*  `Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory. 
* `Split method [Selection]` : there are different criteria options to decide when to split the trajectories. Based on this selection, you'll have specific inputs for each method.
  * **Stops:** Split trajectories at detected stops. A stop is detected if the movement stays within an area of specified size for at least the specified duration.
    * `Minimum duration [Number]` : Only stops longer than this duration will be considered for splitting.
    *  `Duration unit [Selection]` : The time unit for the *minimum duration*: `Seconds`, `Minutes`, `Hours`, or `Days`.
    * `Maximum stop diameter (m) [Number]` : The area size, in meters, to determine whether two or several points represent a stop.
  * **Temporal:** Split trajectories into subtrajectories using regular time intervals.
    *  `Temporal split mode [Selection]` : The fixed time-interval that will be used to split trajectories: `Hour`, `Day`, `Month`, or `Year`.
  * **Speed:** Split trajectories if there are no speed measurements above the speed limit for the specified duration.
    * `Minimum speed (m/s) [Number]` : The speed limit desired. If a trajectory falls below this speed for the specified duration, it will be split.
    * `Minimum duration [Number]` : The amount of time that will be considered for splitting when the trajectory is below the minimum speed.
    *  `Duration unit [Selection]` : The time unit for the *minimum duration*: `Seconds`, `Minutes`, `Hours`, or `Days`.
  * **Observation Gap:** Split trajectories into subtrajectories whenever there is a gap in the observations.
    * `Minimum duration [Number]` : Only observation gaps longer than this duration will be considered for splitting.
    *  `Duration unit [Selection]` : The time unit for the *minimum duration*: `Seconds`, `Minutes`, `Hours`, or `Days`.
  * **Value Change:** Split trajectories into subtrajectories whenever there is a change in the specified column values.
    * *<mark style="color:$info;">This method is not yet supported on Snowflake.</mark>*
    * `Column to check for changes in consecutive values [String]` : The name of the column that will be used to split trajectories, looking at how consecutive values change within said column (EG: 1 → 2)
  * **Angle Change:** Split trajectories into subtrajectories whenever there is a specified change in the heading angle.&#x20;
    * *<mark style="color:$info;">This method is not yet supported on Snowflake.</mark>*
    * `Minimum angle [Number]` : Angle changes above this number of degrees (0-360) will be considered a breaking point, and a new trajectory will be splitted.
    * `Minimum speed (m/s) [Number]` : Minimum speed threshold, in meters per second, at which the angle change will be considered for a given point.
* `Minimum segment length (m) [Number]` : Desired minimum length of resulting trajectories, in meters. Shorter trajectories will be discarded.

**Outputs**

* `Output table [Trajectories Table]`&#x20;

## Trajectory Cleaner

**Description**

This component cleans outliers (spikes) in a trajectory when the speed exceeds the defined threshold.

**Inputs**

* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs
* &#x20;`Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory.
* &#x20;`Speed threshold [Number]` : The maximum speed above which a point will be considered an outlier. Please note that if the resulting trajectory is invalid (e.g. <2 points remaining), the original trajectory is returned.
* `Distance units [Selection]` : Desired distance unit for the *speed threshold:* `Kilometers`, `Meters` , `Miles`, `Nautical miles`.
* `Time units [Selection]` : Desired time unit for the *speed threshold:* `Seconds`, `Hours`.

**Outputs**

* `Output table [Trajectories Table]`&#x20;

## Trajectory Simplifier

**Description**

This component simplifies trajectories by reducing the number of points stored without losing meaningful information, using the *Douglas-Peucker* algorithm.

**Inputs**

* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs
* &#x20;`Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory.
* `Tolerance [Number]` : The tolerance to use when simplifying the trajectory, which can be generally considered as the number of *meters* that are acceptable to distort the trajectory when simplifying.&#x20;
* `Rounding precision [Number]` : Decimal precision to be used when rounding the coordinates to simplify the trajectory.

**Outputs**

* `Output table [Trajectories Table]`&#x20;

## Compute Trajectory Metrics

**Description**

This component computes derived metrics for each segment (consecutive points) within a trajectory, including distances, durations, directions, speeds, and accelerations.

**Inputs**

* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs
* &#x20;`Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory.
* `Compute distances [Boolean]` : If enabled, it will compute the distance between consecutive points in each trajectory, in a new property within the properties field.
  * `Distance property name [String]` : Name to be assigned to the distance property (default: "distance").
  * `Distance unit [Selection]` : Unit for distance computation: `Kilometers`, `Meters`, `Miles`, or `Nautical Miles`&#x20;
* `Compute durations [Boolean]` : If enabled, it will compute the duration of each trajectory segment, in a new property within the properties field.
  * `Duration property name [String]` : Name to be assigned to the duration property.
  * `Duration unit [Selection]` : Unit for duration computation: `Seconds` or `Hours`
* `Compute directions [Boolean]` : If enabled, it will compute the direction (0-360 where 0 represents north) of each trajectory segment, in a new property within the properties field.
  * `Direction property name [String]` : Name to be assigned to the direction property.
* `Compute speeds [Boolean]` : If enabled, it will compute the speed for each trajectory segment, in a new property within the properties field.
  * `Speed property name [String]` : Name to be assigned to the speed property
  * `Speed distance unit [Selection]` : Distance unit for speed computation: `Kilometers`, `Meters`, `Miles`, or `Nautical Miles`&#x20;
  * `Speed time unit [Selection]` : Time unit for speed computation: `Seconds` or `Hours`&#x20;
* `Compute accelerations [Boolean]` : If enabled, it will compute the acceleration for each trajectory segment, in a new property within the properties field.
  * `Acceleration property name [String]` : Name to be assigned to the acceleration property.
  * `Acceleration distance unit [Selection]` : Distance unit for acceleration computation: `Kilometers`, `Meters`, `Miles`, or `Nautical Miles`&#x20;
  * `Acceleration time unit [Selection]` : Time unit for acceleration computation: `Seconds` or `Hours`

**Outputs**

* `Output table [Trajectories Table]`&#x20;

## Distance from Trajectory

**Description**

This component returns the minimum distance from one or more input positions to one or more trajectories.

**Inputs**

* `Positions table [Table]` : Table containing the positions
* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs
* &#x20;`Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory.
* `Join type [Selection]` : Defines how the trajectories and positions will be joined to calculate distances: `Key Join` or `Cross Join` .&#x20;
  * **Key Join:** the component will join the trajectories and positions using a key column.&#x20;
    * `Join Key (Trajectories) [Column]` : Column from the *trajectories table* to be used as key when joining with the positions.
    * `Join Key (Positions) [Column]` : Column from the *positions table* to be used as key when joining with the trajectories.&#x20;
  * **Cross Join:** the component will join the trajectories and positions using all the rows in the trajectories and positions tables. Using `Cross Join` could result in a large number of rows in the *output table*.
* `Position geometries column [Column]` : Column containing the geometries of the positions in the *positions table*
* `Return position properties [Boolean]` : If enabled, the component will also return all the columns from the *positions table*
  * **If not enabled:**
    * `Position ID column [Column]` : Column from the *positions table* to help identify in the final table which position the distance was computed from.
* `Distance from [Selection]` : Defines the point in the trajectory from which the distance will be computed:  `Nearest Point`, `First Point`, or `Last Point` .
  * If `Nearest Point` is selected, the component will compute the distance from the nearest point in the trajectory to the position.
  * If `First Point` is selected, the component will compute the distance from the first point in the trajectory to the position.&#x20;
  * If `Last Point` is selected, the component will compute the distance from the last point in the trajectory to the position.
* `Distance column name [String]` : Name to be assigned to the output column containing the distances
* `Distance units [Selection]` : Unit for the computed distances: `Kilometers`, `Meters`, `Miles`, or `Nautical Miles` .

**Outputs**

* `Output table [Table]`&#x20;

## Get Position at Timestamp

**Description**

This component returns, for each trajectory ID, the interpolated position at the time closest to the provided timestamp.

**Inputs**

* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs
* &#x20;`Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory.
* `Timestamp [String]` : The timestamp to get the positions at. The timestamp must be in the format `YYYY-MM-DDTHH:MM:SSZ`

**Outputs**

* `Output table [Table]`&#x20;

## Trajectory Intersection

**Description**

This component returns only the trajectory segments that intersect a given polygon or list of polygons.

**Inputs**

* `Polygon table [Table]` : Table containing the polygon(s) to intersect
* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs
* &#x20;`Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory.
* `Join type [Selection]` : How to join trajectories and polygons: `Key Join` or `Cross Join` .
  * **Key Join:** the component will join the trajectories and polygons using a key column.&#x20;
    * `Join Key (Trajectories) [Column]` : Column from the *trajectories table* to be used as key when joining with the polygons.
    * `Join Key (Polygons) [Column]` : Column from the *polygon table* to be used as key when joining with the trajectories.
  * **Cross Join:** the component will join the trajectories and polygons using all the rows in the trajectories and polygons tables. Using `Cross Join` could result in a large number of rows in the *output table*.
* `Polygon geometries column [Column]` : Column containing the geometries of the polygons in the *polygon table*
* `Return polygon properties [Boolean]` : If enabled, the component will also return all the columns from the *polygon table.*
* `Intersection method [Selection]` : Whether to return the individual points or segments that intersect: `Segments` or `Points`

**Outputs**

* `Output table [Table]`&#x20;

## Stop Detection

**Description**

This component detects and returns only the stops in a trajectory.

**Inputs**

* `Input table [Trajectories Table]` : A table containing trajectories, as defined by [Trajectory from Points](#trajectory-from-points).
* `Trajectory IDs column [Column]` : The column in the *input table* that contains the trajectory IDs
* &#x20;`Trajectory points column [Column]` : The column in the *input table* that contains the list of points with properties for each trajectory.
* `Return [Selection]` : Whether to return points representing the stops or trajectory segments before and after the stops: `Points` or `Segments`&#x20;
  * `Points`: the points representing the stops.&#x20;
  * `Segments`: the trajectory segments before and after the stops.
* `Minimum stop duration [Number]` : Minimum duration for a stop.
* `Duration unit [Selection]` : Unit for the minimum stop duration: `Seconds`, `Minutes`, `Hours`, or `Days` .
* `Maximum stop diameter (m) [Number]` : Maximum stop diameter accepted, in meters.

**Outputs**

* `Output table [Table]`&#x20;