The Detect Incidents tool examines time-sequential features using a specified condition. Features that meet the specified condition are marked as incidents. The resulting layer displays the input features in the same format as the input, with additional fields stating if the feature is an incident, the status of the incident, the duration of the incident, and a unique incident identifier.
Workflow diagram
Analysis using GeoAnalytics Tools
Analysis using GeoAnalytics Tools is run using distributed processing across multiple ArcGIS GeoAnalytics Server machines and cores. GeoAnalytics Tools and standard feature analysis tools in ArcGIS Enterprise have different parameters and capabilities. To learn more about these differences, see Feature analysis tool differences.
Terminology
| Term | Description |
|---|---|
Track | A sequence of features that are time enabled with time type instant. Features are determined to be in the sequence by a track identifier field and are ordered by time. For example, a city could have a fleet of snow plow trucks that record their location every 10 minutes. The vehicle ID could represent the distinct tracks. |
Incident | Features that meet a condition of interest. |
Instant | A single moment in time represented by a start time and no end time. It is required that inputs to Detect Incidents have time of type instant. |
Interval | A duration of time represented by a start and end time. |
Feature of interest | Used to describe the feature being analyzed. During analysis, all features are analyzed. |
Examples
Monitoring of water and its contaminants is an important role that sensors play. Each sensor measurement includes a time stamp of when a measurement takes place, as well as a value for the contaminants of interest. You have access to water measurements data from your local area, with the measurement and time stamps at each location. You want to look for sensors that report a large increase in a contaminant over previous time steps.
Usage notes
Detect Incidents is completed on tables, or point, line, or area features. The input layer must be time enabled with features that represent an instant in time.
Only input features that have a time entry will be used. Any feature that does not have time will not be used or included in the output results.
The field or fields used to identify tracks will be returned in the results.
You can specify one or more fields to identify tracks. Tracks are represented by the unique combination of one or more track fields. For example, if the fields flightID and Destination are used as track identifiers, the following features [ID007, Solden] and [ID007, Tokoyo] would be in two separate tracks, since they have different values for the field Destination.
Start and end conditions are created using an expression.
Learn more about using expressions to Detect Incidents with GeoAnalytics Tools
It is optional to apply an end condition. If you only apply a start condition, the incident starts when the start condition evaluates to true and ends when the start condition evaluates to false. For example, if values in a track were [0, 10, 15, 20, 40, 10, 12, -2, -12] and the start condition was $feature["values"] > 15, the features that are incidents are those with [True] and would be [0: False, 10: False, 15: False, 20: True, 40: True, 10: False, 12: False, -2: False, -12: False], where only values above 15 are incidents. If you optionally applied an end condition of $feature["values"] < 0, the results would be as follows: [0: False, 10: False, 15: False, 20: True, 40: True, 10: True, 12: True, -2: False, -12: False]. In this example, the incident starts when the start condition is met, and then each sequential feature is an incident until the end condition is true. These examples are outlined in the table below:
| Position: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|---|
Values | 0 | 10 | 15 | 20 | 40 | 10 | 12 | -2 | -12 |
Start: $feature["values"] > 15 and no End | False | False | False | True | True | True | False | False | False |
Start: $feature["values"] > 15 and End: $feature["values"] < 0 | False | False | False | True | True | True | True | False | False |
Applying a time interval segments tracks at a defined interval. For example, if you set the time interval boundary to be 1 day, starting at 9:00 AM on January 1, 1990, each track will be truncated at 9:00 AM for every day. This split is a fast way to accelerate computing time, as it quickly creates smaller tracks for analysis. If splitting by a recurring time interval boundary makes sense for your analysis, it is recommend for big data processing.
Output features will return the fields in the input as well as additional fields:
- IncidentID—A unique ID given to every feature that is an incident.
- IncidentStatus—A string field representing the status of an incident. The value will be null if the feature is not an incident, Started if the feature is the first incident to meet the start condition, OnGoing if the feature is still an incident, and Ended when a feature is no longer an incident. There can be multiple segments of incidents in a single track. For example, a track with values of [0, 10, 15, 20, 40, 10, 12, -2, -12] and a start condition of $feature["values"] > 15 would result in IncidentStatus values of [0: null, 10: null, 15: null, 20: Started, 40: OnGoing, 10: Ended, 12: null, -2: null, -12: null].
- IncidentDuration—The time in milliseconds that an incident occurs. This is calculated as the difference between the feature of interest and the feature that started the incident.
- Instant_Datetime—The time at which the feature occurs.
If Use current map extent is checked, only the features that are visible within the current map extent will be analyzed. If it's not checked, all input features in the input layer will be analyzed, even if they are outside the current map extent.
Limitations
Inputs must be time-enabled features of type instant. Any features that do not have time will not be included in the output.
How Detect Incidents works
Calculations
Features are sequentially ordered in time by track. Starting from the first feature, the start condition is evaluated until it is true. Once a feature meets the start condition, the next features are evaluated until the start condition is false (if no end condition is specified) or until the end condition is true (if an end condition is true). Once that condition is met, the incident ends, and the process starts over. There may be multiple incident segments in an individual track. For example, with a track with values of [10, 20, 30, 40, 50, 10, 20, 30, 40, 50, 10, 20] and a start condition of $feature["values"] > 20, there would be two segments of incidents: [10: null, 20: null, 30: Started, 40: OnGoing, 50: OnGoing, 10: Ended, 20: null, 30: Started, 40: OnGoing, 50: OnGoing, 10: Ended, 20: null].
The duration of an incident is calculated in milliseconds as the time of the feature minus the start of an incident. The duration is only calculated if the feature has a status of Started, OnGoing, and Ended. The duration for a feature with the status of Started is always 0.
ArcGIS API for Python example
The Detect Incidents tool is available through ArcGIS API for Python.
This example finds when and where snowplows were moving slower than 10 miles per hour by calculating the mean of a moving window of five speed values.# Import the required ArcGIS API for Python modules
import arcgis
from arcgis.gis import GIS
from arcgis.geoanalytics import find_locations
# Connect to your ArcGIS Enterprise portal and check that GeoAnalytics is supported
portal = GIS("https://myportal.domain.com/portal", "gis_publisher", "my_password", verify_cert=False)
if not portal.geoanalytics.is_supported():
print("Quitting, GeoAnalytics is not supported")
exit(1)
# Find the big data file share dataset you're interested in using for analysis
search_result = portal.content.search("", "Big Data File Share")
# Look through search results for a big data file share with the matching name
bd_file = next(x for x in search_result if x.title == "bigDataFileShares_VehicleData")
# Look through the big data file share for snowplow track data
snowplows = next(x for x in bd_file.layers if x.properties.name == "Snowplow_tracks")
# Set the tool environment settings
arcgis.env.verbose = True
arcgis.env.defaultAggregations = True
# Run the tool Detect Incidents
output = find_locations.detect_incidents(input_layer = snowplows,
track_fields = "plowID, dayOfYear",
start_condition_expression = "Mean($track.field["speed"].window(-5, 0)) < 10",
output_name = "Slow_Plow_Incidents")
# Visualize the tool results if you are running Python in a Jupyter Notebook
processed_map = portal.map('Fairbanks, AK', 10)
processed_map.add_layer(output)
processed_map
Similar tools
Use Detect Incidents to find features that are incidents. Other tools may be useful in solving similar but slightly different problems.
Map Viewer analysis tools
If you would like to reconstruct time-enabled features into tracks, use the GeoAnalytics Tools Reconstruct Tracks.
If you would like to calculate values of a field, use the GeoAnalytics Tools Calculate Field.
ArcGIS Desktop analysis tools
The GeoAnalytics Tools Reconstruct Tracks is also available in ArcGIS Pro.
The GeoAnalytics Tools Calculate Field is also available in ArcGIS Pro.
The GeoAnalytics Tools Detect Incidents is available in ArcGIS Pro.
To run this tool from ArcGIS Pro, your active portal must be Enterprise 10.6 or later. You must sign in using an account that has privileges to perform GeoAnalytics Feature Analysis.