| Label | Explanation | Data Type |
Input Features
| The time-enabled features representing the known identifier that will be used to find cotravelers. The unique identifiers, time stamps, and locations will be transferred to the output layer to assist with calculating the time and spatial separation. | Feature Layer |
Output Feature Class
| The output feature class that will contain the point track segments identified as cotraveling with the input source layers. This feature class will include the source with which the specified point track segment is associated. Time and spatial separation will be calculated for each point track feature. | Feature Class |
ID Field
| A field from the Input Features parameter that will be used to obtain the unique identifiers per point track. The field will be copied to the output feature class. | Field |
Search Distance
(Optional) | The maximum distance that can separate features before they are considered not to be cotraveling features. The default is 100 feet. | Linear Unit |
Time Difference
(Optional) | The maximum time difference that can separate features before they are considered not to be cotraveling features. The default is 10 seconds. | Time Unit |
Input Type
(Optional) | Specifies whether cotravelers will be detected in one feature class or across two.
| String |
Secondary Features
(Optional) | A second feature class that will identify cotravelers. Potential cotravelers will be evaluated using the following:
| Feature Layer |
Secondary ID Field
(Optional) | A field from the Secondary Features parameter that will be used to obtain the unique identifiers per point track. The field will be copied to the output feature class. | Field |
Create Summary Table
(Optional) | Specifies whether an output summary table will be created.
| Boolean |
Output Summary Table
(Optional) | The output table that will store the summary information. This parameter is only active when the Create Summary Table parameter is checked. Output files must be tables in a file geodatabase, text files, or comma-separated value files (.csv). | Table |
Include Minimum Cotraveling Duration Filter
(Optional) | Specifies whether a filter that only returns cotravelers who meet a minimum time of traveling together will be applied.
| Boolean |
Minimum Cotraveling Duration
(Optional) | The minimum amount of time that two features must be moving through space and time together before they will be considered cotravelers. | Time Unit |
Summary
Extracts unique identifiers that are moving through space and time at specified intervals in a point track dataset.
Usage
The tool identifies unique identifiers from the input features that are moving within a specified time and distance from each other. The input features must be time enabled.
When selecting a field to use as the unique identifier, select either an integer or a text field. This will allow for a more efficient grouping of the features and return an optimal output. Optimally, the dataset will contain an existing Track ID. A good example of a track identifier is Maritime Mobile Service Identity (MMSI). The Name field from .gpx files, aircraft call-sign, or other unique values can be grouped into tracks. Unique identifiers should not be unique to each row. If they are, tracks cannot be formed and either no cotravelers will be identified or, in rarer cases, a significant number of false positives will be generated.
Smaller time and spatial separation intervals are faster to process. For example, a time difference of 10 minutes and a spatial separation of 100 meters will process faster than a time difference of 1 hour and a spatial separation of 1 kilometer.
To optimize the Search Distance and Time Difference parameters to return the appropriate amount of cotraveling features, consider the following:
- Larger Search Distance and Time Difference values will identify more potential cotravelers. This may be ideal if the average spacing between moving objects needs to be larger, such as for ships or large trucks.
- Larger Search Distance and Time Difference values are also ideal for data that has a sample rate measured in minutes. This is due to the likelihood that objects are traveling more during those increased intervals.
- Smaller Search Distance and Time Difference values will identify fewer potential cotravelers. This may be ideal if the spacing between moving objects is smaller, such as people, bicycles, or cars.
- Smaller Search Distance and Time Difference values are ideal for data that is sampled at a second or subsecond rate. With smaller sample rates, the object has less opportunity to travel, allowing for tighter tolerances in detecting cotravelers.
Parameter values for pedestrians must be smaller, while they must be larger for large objects. The Minimum Cotraveling Duration Filter parameter allows the specification of a minimum amount of time that two features must be traveling together before they are considered cotraveling. For example, if a minimum cotraveling duration of 15 minutes is specified, the time from the first instance of a cotraveling event being detected and the last instance of a cotraveling event must be at least 15 minutes before the tool will return the track as a valid cotraveler. If there is a large number of false positives resulting from features such as ports, parking lots, or cotraveling events with a very small number of tracks, it is recommended that you apply a Minimum Cotraveling Duration Filter value and run the tool again. The Minimum Cotraveling Duration Filter value will help remove most of the smaller track segments.
When the Search Distance and Time Difference values are set to larger values, the tool may identify features that may be passing or intersecting as potential cotravelers. To prevent this, set the Minimum Cotraveling Duration Filter parameter to a value that is greater than the sampling rate of the data.
Passing and intersecting objects are not cotraveling. The output features represent the locations of the cotraveling features. Two fields will be added to the output features that indicate the time and spatial separation between the traveler and possible cotraveler in addition to other descriptive fields.
The output features will include the following fields:
- traveler_id—The unique identifier for the traveling feature. This is the identifier the cotraveling feature was moving with and can be considered the source feature.
- cotraveler_id—The unique identifier for the cotraveling feature. This is the identifier that was cotraveling with the traveling feature and can be considered the target feature.
- X—The x-coordinate of the traveling feature. The coordinate will be in the projection units of the Input Features parameter.
- Y—The y-coordinate of the traveling feature. The coordinate will be in the projection units of the Input Features parameter.
- X_cotraveler—The x-coordinate of the cotraveling feature. The coordinate will be in the projection units of the Input Features parameter.
- Y_cotraveler—The y-coordinate of the cotraveling feature. The coordinate will be in the projection units of the Input Features parameter.
- traveler_time—The date and time of the traveling feature.
- cotraveler_time—The date and time of the cotraveling feature.
- distance_difference—The distance between the feature identified in the Input Features parameter and the assessed cotraveler. The distance will be in the linear units of the Input Features parameter.
- time_difference—The time separation from the feature identified in the Input Features parameter and the assessed cotraveler. The time difference will be in seconds and can be a positive or negative number. Positive numbers indicate features that are identified as occurring after the traveler. Negative numbers indicate features that are identified as occurring before the traveler.
- cotraveling_pair_id—A unique identifier generated for each unique pair of cotraveling features.
The cotraveling_pair_id identifier is generated to provide an option to filter and identify all possible combinations of cotravelers. Two cotraveling features (A, B) will share the same identifier for both (A, B) and (B, A).
When a pair of tracks is identified as cotraveling, all instances of that pair will have the same cotraveling_pair_id identifier. An optional summary table can be created. The summary table will include the following fields:
- unique_pair_id—A unique identifier generated for each unique pair of cotraveling features. Two cotraveling features (A, B) will share the same identifier for both (A, B) and (B, A).
- traveler_id—The unique identifier for the traveling feature. This is the identifier the cotraveling feature was moving with and can be considered the source feature.
- cotraveler_id—The unique identifier for the cotraveling feature. This is the identifier that was cotraveling with the traveling feature and can be considered the target feature.
- time_diff_max—The maximum temporal separation between the traveler and cotraveler.
- time_diff_min—The minimum temporal separation between the traveler and cotraveler.
- time_diff_mean—The mean temporal separation between the traveler and cotraveler.
- time_diff_std—The standard deviation of the temporal separation between the traveler and cotraveler.
- dist_diff_max—The maximum distance separation between the traveler and cotraveler.
- dist_diff_min—The minimum distance separation between the traveler and cotraveler.
- dist_diff_mean—The mean distance separation between the traveler and cotraveler.
- dist_diff_std—The standard deviation of the distance separation between the traveler and cotraveler.
- unique_pair_id_count—The total number of features identified as cotraveling for the unique_pair_id field.
The output for the Find Cotravelers tool can be visualized in a link chart.
Link charts allow complex datasets to be drilled down to their component pieces to help visualize and explore the relationships in the data. This is done through the creation of entity types and relationship types. Entity types represent discrete objects, such as people, places, organizations, and unique identifiers. The traveler_id and cotraveler_id fields are examples of types of data that can be turned into an entity type. The other part of a link chart is the relationship types. Relationship types connect the individual entity types to each other in the link chart. Visualizing the outputs from Find Cotravelers increases understanding of which entities are connected and if there are relevant clusters that warrant further exploration.
Once a link chart is created, entity and relationship types can be created for the Find Cotravelers output. It is recommended that you check the Create Summary Table parameter. The Find Cotravelers results can be large and may impact the performance of the link chart. Whether using the optional Create Summary Table value or the Output Feature Class value, it is recommended that you add an entity type from the traveler_id and cotraveler_id fields by creating a multifield entity.
To create a relationship type using the Output Summary Table or Output Feature Class value, use the Entities key type. Set the Source entity key field value to traveler_id and the Target entity key field value to cotraveler_id.
Parameters
arcpy.intelligence.FindCotravelers(input_features, out_featureclass, id_field, {search_distance}, {time_difference}, {input_type}, {secondary_features}, {secondary_id_field}, {create_summary_table}, {out_summary_table}, {include_min_cotraveling_duration}, {min_cotraveling_duration})| Name | Explanation | Data Type |
input_features | The time-enabled features representing the known identifier that will be used to find cotravelers. The unique identifiers, time stamps, and locations will be transferred to the output layer to assist with calculating the time and spatial separation. | Feature Layer |
out_featureclass | The output feature class that will contain the point track segments identified as cotraveling with the input source layers. This feature class will include the source with which the specified point track segment is associated. Time and spatial separation will be calculated for each point track feature. | Feature Class |
id_field | A field from the input_features parameter that will be used to obtain the unique identifiers per point track. The field will be copied to the output feature class. | Field |
search_distance (Optional) | The maximum distance that can separate features before they are considered not to be cotraveling features. The default is 100 feet. | Linear Unit |
time_difference (Optional) | The maximum time difference that can separate features before they are considered not to be cotraveling features. The default is 10 seconds. | Time Unit |
input_type (Optional) | Specifies whether cotravelers will be detected in one feature class or across two.
| String |
secondary_features (Optional) | A second feature class that will identify cotravelers. Potential cotravelers will be evaluated using the following:
| Feature Layer |
secondary_id_field (Optional) | A field from the secondary_features parameter that will be used to obtain the unique identifiers per point track. The field will be copied to the output feature class. | Field |
create_summary_table (Optional) | Specifies whether an output summary table will be created.
| Boolean |
out_summary_table (Optional) | The output table that will store the summary information. This parameter is only enabled when the create_summary_table parameter value is set to CREATE_SUMMARY_TABLE. Output files must be tables in a file geodatabase, text files, or comma-separated value files (.csv). | Table |
include_min_cotraveling_duration (Optional) | Specifies whether a filter that only returns cotravelers who meet a minimum time of traveling together will be applied.
Specifies whether a minimum cotraveler duration filter will be applied.
| Boolean |
min_cotraveling_duration (Optional) | The minimum amount of time that two features must be moving through space and time together before they will be considered cotravelers. | Time Unit |
Code sample
The following Python script demonstrates how to use the FindCotravelers function in a stand-alone script without the output summary table and one input feature class.
# Name: FindCotravelers.py
# Description: Identify cotravelers in a point track dataset.
# Import system modules
import arcpy
arcpy.env.workspace = "C:/data/Tracks.gdb"
# Set local variables
source_features = "Known_Tracks"
output_point_features = "Cotravelers"
id_field = "device_id"
# Run tool
arcpy.intelligence.FindCotravelers(source_features,
output_point_features,
id_field)The following Python script demonstrates how to use the FindCotravelers function in a stand-alone script with the output summary table and two input feature classes.
# Name: FindCotravelers.py
# Description: Identify cotravelers in a point track dataset.
# Import system modules
import arcpy
arcpy.env.workspace = "C:/data/Tracks.gdb"
# Set local variables
source_features = "Known_Tracks"
unknown_features = "Unknown_Tracks"
output_point_features = "Cotravelers"
id_field_name = "device_id"
unknown_id_field = "MMSI"
search_distance = "75 Feet"
time_difference = "5 Seconds"
summary_table = "CREATE_SUMMARY_TABLE"
summary_table_name = "Tracks_Summary_Table"
filter_duration = "MIN_COTRAVELING_DURATION"
cotraveling_duration = "30 Minutes"
# Run tool
arcpy.intelligence.FindCotravelers(source_features,
output_point_features,
id_field_name,
search_distance,
time_difference,
"TWO_FEATURECLASSES",
unknown_features,
unknown_id_field,
summary_table,
summary_table_name,
filter_duration,
cotraveling_duration)Licensing information
- Basic: No
- Standard: No
- Advanced: Yes