Note:
This functionality is currently only supported in Map Viewer Classic (formerly known as Map Viewer). It will be available in a future release of the new Map Viewer.
The Trace Proximity Events tool traces events near each other in space (location) and time. The input layer must be time-enabled points that represent an instant in time.
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 | Definition | Example |
|---|---|---|
Entity | A moving object with position periodically recorded. | An animal, person, or vehicle. An entity may be stationary or moving. |
Entities of interest | The specific entities used to start a trace. | A person infected with COVID-19. |
Proximity event | When two entities are near each other within a period of time. | Two people that come within 3 meters of each other and within a 1-minute window of each other. |
Depth | The degree of separation between an entity of interest and an entity further down the trace (downstream). | A proximity event between the entity of interest and someone else is depth 1. |
Trace event | The first contact for a specified entity downstream from the entities of interest. |
Examples
An organization monitors company-issued devices carried by workers. The company is interested in determining which employees were near an individual known to have coronavirus disease 2019 (COVID-19). Using the point layer representing device locations and time, they identify devices that have been within six meters and five minutes of the contagious person and other possibly contagious employees.
An NGO is monitoring salmon populations using GPS and is interested in tracking the spread of salmon lice between escaped farmed salmon and wild populations. Some GPS-tagged farmed salmon are tracked to see if they come in close proximity with tagged wild populations, and how those wild populations may further spread the disease. The measurements also include a depth field, which the NGO uses to only find fish at a similar depth.
Usage notes
When tracing proximity events, it is your responsibility to understand organizational, local, and national guidelines regarding data sensitivity and privacy.
Input points that do not have time values, geometry values, or an entity ID field are not included in the results.
When using proximity tracing to find the transmission (such as a disease), be aware of the following:
- The presence of a trace event does not guarantee that it has been transmitted; it is only a potential encounter.
- The absence of a trace event does not mean that something hasn’t been transmitted. In cases such as a disease, there may be transmission through other vectors.
- When possible, use the Select one or more entity attributes to match parameter to constrain proximity events when required. For example, use attributes to constrain the room, floor, or elevation.
Specifying a larger temporal search distance and spatial search distance results in more events and takes longer to process the results. Smaller distances results in fewer events and a shorter processing time.
Features must meet both the spatial search distance and temporal search distance parameter criteria to be considered near each other.
 |  |
Use domain-specific knowledge to determine the values used for the spatial search distance and temporal search distance parameters. Consider factors such as the accuracy of the device when setting the distances.
The entity of interest is where the proximity tracing begins. If you specify a starting from time, tracing begins at that time for that entity. If you do not specify a time, tracing begins on January 1, 1970, for that entity.
By default, entity tracks are created using a geodesic method for distance calculation. It is recommended that you use geodesic distance in the following circumstances:
- Tracks cross the international date line—When using the geodesic method, input layers that cross the international date line will have tracks that correctly cross the international date line. Your input layer or processing spatial reference must be set to a spatial reference that supports wrapping around the international date line, for example, a global projection such as World Cylindrical Equal Area.
- Your dataset is not in a local projection—If your input data is in a local projection, use the planar distance method. For example, use the planar method to examine trace events within a single state. Your input layer or processing spatial reference must be set to a spatial reference local to your dataset.
Use Advanced Options to specify maximum trace depth and entity attributes to match:
- You can set additional requirements for a proximity event. For example, you can trace only individuals in a particular building on a campus, or you can trace only within one level of a building. Use the Select one or more entity attributes to match parameter to specify constraining attributes. For example, to constrain entities on the same floor, specify the Floor field.
- By default, all traces between an entity of interest and an entity farther down the trace are found. Use the Maximum trace depth parameter to limit the depth.
The output proximity events layer contains the first proximity event for the entities in the trace, as well as the following fields:
- from_id—The upstream entity ID.
- to_id—The downstream entity ID.
- depth—The degree of separation between the entity of interest and the to_id field.
- duration_minutes—The duration of the trace event in minutes. This field is calculated as the difference between the start and end times. For example, 1.5 minutes is 90 seconds. A value of 0 means that there is a single proximity event (same start and end time).
- instant_datetime—The date and time of the proximity event. This field is calculated as the first recorded time that meets the criteria of the proximity event.
You can visualize the output proximity events layer using the time slider or in a link chart in ArcGIS Pro to visualize the trace results.
You can use the optional Include tracks layer parameter to create a layer that contains the first trace event and all subsequent features for that entity. Additionally, the features for the entity of interest are always included in the output track layer. These results are helpful for visualizing where entities travelled and can be used in the Reconstruct Tracks tool. The output tracks layer includes the following fields:
- entity_id—The entity ID.
- depth—The degree of separation between the entity of interest and the trace track. The depth is the same across a single track.
- instant_datetime—The date of each feature. This is the same date as the record from the input features.
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
The input proximity events must be a point layer with time-enabled features of type instant. Any features that do not have time are not included in the output results.
How Trace Proximity Events works
The diagrams below show how the Trace Proximity Events tool processes data. In these diagrams, time is on the x-axis. In each diagram, there are four entities: A, B, C, and D. The highlighted text describes the trace events that occur between two entities (the from and to entities) and the depth of the proximity event. In this example, entity C is the entity of interest that is being traced downstream.
In diagram 1, entity C is the chosen entity of interest. The depth is 0.
In diagram 2, a proximity event occurs between entities C and B. The depth of the trace is 1. When multiple features are subsequent proximity events, this is a sustained proximity event.
In diagram 3, a proximity event occurs between entities B and A. The depth of the trace is 2.
In diagram 4, a proximity event occurs between entities C and D. The depth of the trace is 1.
In the image below, entity B is the entity of interest and comes in proximity with entity A three times, denoted by the blue circles. Assuming that time is on the x-axis, the first proximity event is 1, followed by a break without contact, and then proximity events 2 and 3. The tool returns event 1 in the proximity events layer. Proximity events 2 and 3 are not returned. If the Include tracks layer parameter is selected, all features after proximity event 1 are returned in the output tracks layer.
ArcGIS API for Python example
The Trace Proximity Events tool is available through ArcGIS API for Python.
This example finds the proximity events for all entities in the input layer that came into proximity with an entity called entity_3.
# Import the required ArcGIS API for Python modules
import arcgis
from arcgis.gis import GIS
# Connect to your ArcGIS Enterprise portal and confirm 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)
# Search for and list the big data file shares in your portal
search_result = portal.content.search("", "Big Data File Share")
# Look through the search results for the big data file share of interest
bd_layer = next(x for x in search_result if x.title == "bigDataFileShares_EntityLocationPoints")
# Run the Trace Proximity Events tool
result = arcgis.geoanalytics.use_proximity.trace_proximity_events(input_points = bd_layer,
entity_id_field = "UniqueID",
entities_of_interest_ids = [{"entityId": "entity_3", "epochTimeStamp": None}],
spatial_search_distance = 6,
spatial_search_distance_unit = "feet",
distance_method = "Geodesic",
temporal_search_distance = 10,
temporal_search_distance_unit = "minutes",
max_trace_depth = None,
attribute_match_criteria = None,
include_tracks_layer = None,
output_name = "TPE_output")
# Visualize the results if you are running Python in a Jupyter Notebook
processed_map = portal.map()
processed_map.add_layer(result)
processed_map
Similar tools
Use Trace Proximity Events to trace events that are near each other in space (location) and time. Other tools may be useful in solving similar but slightly different problems.
Map Viewer Classic analysis tools
If you are interested in calculating all proximity events and aren’t interested in tracing downstream from an entity of interest, use the Join Features tool.
If you want to reconstruct points to the paths travelled or visualize your output tracks, use the Reconstruct Tracks tool.
ArcGIS Desktop analysis tools
The Trace Proximity Events tool is also available in ArcGIS Pro.
To run the tool from ArcGIS Pro, your project's active portal must be running ArcGIS Enterprise 10.9 or later. At 10.9, you must sign in to the portal using an account with privileges to perform spatial analysis in the portal.