Calculate Journeys

The Calculate Journeys tool Calculate Journeys tool analyzes point-based observations of moving entities and generates either journeys or dwell locations based on user-defined distance and time span tolerances.

Examples

  • A shipping company wants to better understand ship movement to identify the routes ships have taken, the distance traveled in each journey, and the mean speed for that journey. You can use Calculate Journeys to generate polyline journeys containing this information as well as additional attributes regarding start and end dwell locations.
  • A transportation department is monitoring vehicle movement to identify dwell locations. You can use the Calculate Journeys tool to identify dwell locations where vehicles have not exceeded a certain speed threshold.

Usage notes

  • The Track ID and Start Time key fields must be identified on the input layer to use this tool.
  • When using the Calculate Journeys tool, you must choose whether to generate journeys or dwell locations. If you want to generate both, configure two instances of the Calculate Journeys tool with two separate outputs.
  • If you generate journeys, the output will be a polyline layer. If you generate dwell locations, the output will be a point layer.
  • The values in the Distance Tolerance and Time Span Tolerance parameters are combined to form a speed threshold. This speed threshold is used to identify dwell locations.
    • When a track's speed is below the defined speed threshold (distance tolerance divided by time span tolerance), a resulting journey polyline ends and a dwell location is identified.
    • The Minimum Observation Duration and Minimum Observation Distance parameters designate the minimum required duration or distance between individual sequential features to identify the start of a dwell feature.
    • You can use the Minimum Observation Duration and Minimum Observation Distance parameters to protect against situations in which sequential track features are very close together in time or distance and you do not want the journey polyline to be split and a dwell to be identified. For example, if the track has a feature with the same geometry and is one second apart from the prior feature, a minimum observation duration of five seconds will require sequential track points to be at least five seconds apart and for the feature to be below the defined speed threshold to identify a dwell.
  • When generating journeys, you must choose whether to include gaps. If chosen, gaps are created as a type of journey in the output.
  • You can calculate additional statistics using the Summary Fields parameter. The summary fields statistics that are available depend on the field type you are summarizing. A string attribute field can use the Any, Count, and Count Distinct statistics. A numeric attribute field can use the Any, Count, Count Distinct, Sum, Sum of Squares, Min, Max, Range, Variance, and Standard Deviation statistics. A date attribute field can use the Any, Count, Min, Max, and Range statistics.

Parameters

ParameterDescriptionData type

Input Layer

The point features for which either journeys or dwell locations will be calculated.

Features

Distance Tolerance

The distance tolerance value that will be used to determine dwell locations. The values in the Distance Tolerance and Time Span Tolerance parameters are combined to form a speed threshold.

String

Time Span Tolerance

The time span tolerance value that will be used to determine dwell locations. The values in the Distance Tolerance and Time Span Tolerance parameters are combined to form a speed threshold.

String

Output

Specifies whether to return the journeys (line segments) or the dwell locations (points) from the journey analysis.

String

TRACK_ID Fields

You must select the fields to uniquely identify features that will be processed. This parameter will be automatically populated if a Track ID key field has been set on the input layer.

String

Method

Specifies whether the distance calculation method will be set to Geodesic or Planar (Euclidean).

String

Include Gaps

Specifies whether to include gaps as a type of journey in the output.

This parameter only applies when an output type of Journeys (line segments) is set.

Boolean

Gap Duration

The tolerance for determination of gaps between observations. Sequential observations farther apart than this time span will be considered a gap, and the previous journey will terminate at the start of the gap.

This parameter only applies when an Output type of Journeys (line segments) is set.

String

Minimum Observation Duration

The minimum duration needed between a point and its previous track point for the current point to be labeled as an idle point and break a journey polyline.

For example, if the track has a feature with the same geometry and is one second apart from the prior feature, a minimum observation duration of five seconds will require sequential track points to be at least five seconds apart and for the feature to be below the defined speed threshold to identify a dwell.

String

Minimum Observation Distance

The minimum distance needed between a point and its previous track point for the current point to be labeled as an idle point and break a journey polyline.

For example, if the track has a feature with geometry one inch away from the prior observation and is one second apart from the prior feature, a minimum observation distance of three inches will require sequential track points to be at least three inches apart and for the feature to be below the defined speed threshold to identify a dwell.

String

Summary Fields

The statistics that will be calculated for specified fields. Different statistics are available depending on whether the specified field is a string, numeric, or date field.

  • Any—A sample string from a field of type string.
  • Count—Calculates the number of nonnull values. It can be used on numeric fields or strings. The count of [null, 0, 2] is 2.
  • Count Distinct—Calculates the number of distinct, nonnull values. It can be used on numeric fields or strings. The count distinct result of [null, 4, 3, 4] is 2.
  • Sum—The sum of numeric values in a field. The sum of [null, 1, 3] is 4.
  • Sum of Squares—The sum, over all observations, of the squared differences of each observation from the overall mean. The sum of squares of [null, 2.2, 3.1, 4.7] is 3.206.
  • Min—The minimum value of a numeric field. The minimum of [0, 2, null] is 0.
  • Max—The maximum value of a numeric field. The maximum value of [0, 2, null] is 2.
  • Mean—The mean of numeric values. The mean of [0, 2, null] is 1.
  • Range—The range of a numeric field. This is calculated as the minimum value subtracted from the maximum value. The range of [0, null, 1] is 1. The range of [null, 4] is 0.
  • Variance—The variance of a numeric field in a track. The variance of [1] is null. The variance of [null, 1, 1, 1] is 1.
  • Standard Deviation—The standard deviation of a numeric field. The standard deviation of [1] is null. The standard deviation of [null, 1, 1, 1] is 1.

String

Output layer

The output layer will contain the Track ID field of the input observations as well as a variety of attributes. The attributes present on the output depend on the value chosen for the Outputparameter (Journeys or Dwell Locations).

Journeys output layer attributes

Field nameDescriptionField type

TRACK_ID

The Track ID key field used for processing.

any

JourneyId

A sequentially numbered ID value for the journey. The first journey for a given track is 1, the second journey is 2, and so forth. These IDs are used as the basis for the PreviousJourneyId and NextJourneyId attributes.

Int32

JourneyType

Specifies whether the line segment is a journey or a gap.

String

JourneyStartTime

The start time of the journey. If the journey begins at a dwell location, the start time is the time of the latest feature in the dwell location.

Date

JourneyEndTime

The end time of the journey. If the journey ends at a dwell location, the start time is the time of the earliest feature in the dwell location.

Date

JourneyDuration

The amount of time in milliseconds between the start and end time of the journey.

Float64

JourneyDistanceTraveled

The distance traveled along the journey. If the journey begins at a dwell location, the x,y coordinates of the dwell centroid are used for the journey's first point, and likewise for the end location if the journey ends in a dwell.

Float64

JourneyMeanSpeed

The mean speed of the journey (JourneyDistanceTraveled value divided by the JourneyDuration value).

Float64

JourneyObservationCount

The number of observations that make up the journey.

Float64

PreviousJourneyId

The ID of the journey immediately before the journey.

Float64

NextJourneyId

The ID of the journey immediately after the journey.

Int32

StartDwellX

The x-coordinate of the centroid of the observations that make up the dwell location at the beginning of the journey. This attribute is null if the journey began based on a gap.

Float64

StartDwellY

The y-coordinate of the centroid of the observations that make up the dwell location at the beginning of the journey. This attribute is null if the journey began based on a gap.

Float64

StartDwellStartTime

The time stamp of the earliest point in the group of points that define the dwell.

Date

StartDwellEndTime

The time stamp of the latest point in the group of points that define the dwell.

Date

StartDwellDuration

The duration (in milliseconds) of the dwell at the beginning of the journey.

Float64

StartDwellMeanDistance

The mean distance, of any point participating in the dwell, from the centroid of the dwell.

Float64

StartDwellObservationCount

The number of observations that make up the dwell.

Float64

EndDwellX

The x-coordinate of the centroid of the observations that make up the dwell location at the end of the journey. This attribute is null if the journey ends based on a gap.

Float64

EndDwellY

The y-coordinate of the centroid of the observations that make up the dwell location at the end of the journey. This attribute is null if the journey ends based on a gap.

Float64

EndDwellStartTime

The time stamp of the earliest point in the group of points that define the dwell.

Date

EndDwellEndTime

The time stamp of the latest point in the group of points that define the dwell.

Date

EndDwellDuration

The duration (in milliseconds) of the dwell at the end of the journey.

Float64

EndDwellMeanDistance

The mean distance, of any point participating in the dwell, from the centroid of the dwell.

Float64

EndDwellObservationCount

The number of observations that make up the dwell.

Float64

Dwell locations output layer attributes

Field nameDescriptionField type

TRACK_ID

The Track ID key field used for processing.

any

DwellObservationCount

The number of observations that make up the dwell.

Float64

DwellDuration

The duration (in milliseconds) of the dwell.

Float64

DwellStartTime

The time stamp of the earliest point in the group of points that define the dwell.

Date

DwellEndTime

The time stamp of the latest point in the group of points that define the dwell.

Date

DwellMeanDistance

The mean distance, of any point participating in the dwell, from the centroid of the dwell.

Float64

DwellX

The x-coordinate of the centroid of the observations that make up the dwell location.

Float64

DwellY

The y-coordinate of the centroid of the observations that make up the dwell location.

Float64