Summary
Extracts unique identifiers that are moving through space and time at user-defined 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 interval of features from each other. The input features must be time enabled.
To learn how to time enable a dataset, see Set time properties on data.
When selecting a field to use as the unique identifier, select either a field containing whole numbers or text. This will allow for a more efficient grouping for the features and return an optimal output.
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 significantly faster than a time difference of 1 hour and spatial separation of 1 kilometer.
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.
- Y—The y-coordinate of the traveling feature. The coordinate will be in the projection units of the Input Features.
- X_cotraveler—The x-coordinate of the cotraveling feature. The coordinate will be in the projection units of the Input Features.
- Y_cotraveler—The y-coordinate of the cotraveling feature. The coordinate will be in the projection units of the Input Features.
- 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 and the assessed cotraveler. The distance will be in the linear units of the Input Features.
- time_difference—The time separation from the feature identified in the Input Features and the assessed cotraveler. The time difference will be in seconds and can be a positive or negative number. Positive numbers indicate features identified as occurring after the traveler. Negative numbers indicate features identified as occurring before the traveler.
- cotraveling_pair_id—A unique identifier generated for each unique pair of cotraveling features. Two cotraveling features (A, B) will share the same the same cotraveling_pair_id for both (A, B) and (B, A).
There is an optional summary table that can be created from the output features. 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 the same unique_pair_id 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.
Syntax
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})| Parameter | 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 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 identified in one feature class or between two.
| String |
secondary_features (Optional) | A second feature class to identify cotravelers. Potential cotravelers will be evaluated using the following:
| Feature Layer |
secondary_id_field (Optional) | A field from the Secondary Features 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 to create an output summary table.
| Boolean |
out_summary_table (Optional) | The output table that will store the summary information. This option is only enabled when the Create Summary Table parameter value is set to True. | Table |
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"
# Execute tool
arcpy.FindCotravelers_intelligence(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"
# Execute tool
arcpy.FindCotravelers_intelligence(source_features,
output_point_features,
id_field_name,
search_distance,
time_difference,
"TWO_FEATURECLASSES",
unknown_features,
unknown_id_field,
summary_table,
summary_table_name)Licensing information
- Basic: No
- Standard: No
- Advanced: Yes