Trace Proximity Events (GeoAnalytics Desktop)

Summary

Traces events that are near each other in space (location) and time. The time-enabled point data must include features that represent an instant in time.

Illustration

Trace Proximity Events tool illustration
An example of trace events (orange circles) and tracks (red circles) is shown.

Usage

  • The following are examples of use cases that can be performed with the Trace Proximity Events tool:

    • An organization monitors company-issued devices carried by workers. The company wants to determine 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 6 meters and 5 minutes of the contagious person and other possibly contagious employees.
    • An NGO is monitoring salmon populations using GPS and wants to track the spread of salmon lice between escaped farmed salmon and wild populations. Some GPS-tagged farmed salmon are tracked to determine 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 find fish at a similar depth.

  • The following terminology is used in the Trace Proximity Events tool:

    • Entity—An object that has its position periodically recorded, for example, an animal, person, or vehicle. An entity can be stationary or moving.
    • Entities of interest—The specific entities used to start a trace, for example, a person infected with COVID-19.
    • Proximity event—The period of time when two entities are near each other, for example, 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 farther down the trace (downstream). For example, 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.
  • When tracing proximity events, it is your responsibility to understand organizational, local, and national guidelines regarding data sensitivity and privacy.

  • 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.

    Trace Proximity Events tool diagram 1

    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.

    Trace Proximity Events tool diagram 2

    In diagram 3, a proximity event occurs between entities B and A. The depth of the trace is 2.

    Trace Proximity Events tool diagram 3

    In diagram 4, a proximity event occurs between entities C and D. The depth of the trace is 1.

    Trace Proximity Events tool diagram 4

    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; then proximity events 2 and 3 occur. The tool will return event 1 as the trace event. Proximity events 2 and 3 are not returned in the Output Proximity Events parameter layer. All features after proximity event 1 are returned in the Output Tracks parameter.

    First trace event

  • Features must meet both the Spatial Search Distance and Temporal Search Distance parameter criteria to be considered near each other.

    Spatial Search Distance diagram
    Figure A: The two features are within a spatial search distance of each other.
    Temporal Search Distance diagram
    Figure B: The two features are within a time distance (temporal search distance) of each other.
  • Specifying a larger temporal search distance and spatial search distance will result in more events and take longer to process the results. Smaller distances will result in fewer events and a shorter processing time.

  • 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 Define Entities of Interest Using parameter supports the following options:

    • Entities of Interest IDs—This option enables the Entities of Interest IDs parameter, which requires Entity ID values and optional Starting From time values to start tracing from.
    • Selected features in a specified entity of interest layer—This option enables the Entities of Interest Layer parameter, which allows you to choose a layer that includes entity IDs and, optionally, times to start tracing from. For this layer, the entity ID field name must match the entity ID field name from the input layer. Time will be used on this layer if the layer is time enabled.
  • The entity of interest is where the proximity tracing will begin. If you specify a starting from time, tracing will begin at that time for that entity. If you do not specify a time, tracing will begin on January 1, 1970, for that entity.

  • 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 Attribute Match Criteria parameter to specify constraining attributes. For example, to constrain entities on the same floor, specify the Floor field.

  • The Output Proximity Events layer will contain 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).
    • date—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.

    The Output Proximity Events layer can be visualized using the time slider or in a link chart to visualize the trace results.

  • You can use the optional Output Tracks parameter to create a layer that contains the first trace event and all subsequent features for that entity. These results are helpful for visualizing where entities travelled and can be used in the Reconstruct Tracks tool. The Output Tracks parameter will include the following fields:

    • entity_id—The entity ID.
    • depth—The degree of separation between the entity of interest and the trace track. The depth will be the same across a single track.
    • instant_datetime—The date of each feature. This will be the same date as the record from the input features.
  • 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), consider 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 Attribute Match Criteria parameter to constrain proximity events when required. For example, use attributes to constrain the room, floor, or elevation.

  • If you want to calculate all proximity events and don't want to trace downstream from an entity of interest, use the Join Features tool.

  • You can improve performance of the Trace Proximity Events tool by doing one or more of the following:

    • Use smaller values for the Spatial Search Distance and Temporal Search Distance parameters.
    • Limit the entities of interest using the Attribute Match Criteria parameter.
    • Specify a Maximum Trace Depth parameter value to limit the number of downstream traces for a given entity and the entity of interest.
    • Set the extent environment so that you only analyze data of interest.
    • Use data that is local to where the analysis is being run.

  • This geoprocessing tool is powered by Spark. Analysis is completed on your desktop machine using multiple cores in parallel. See Considerations for GeoAnalytics Desktop tools to learn more about running analysis.

  • When running GeoAnalytics Desktop tools, the analysis is completed on your desktop machine. For optimal performance, data should be available on your desktop. If you are using a hosted feature layer, it is recommended that you use ArcGIS GeoAnalytics Server. If your data isn't local, it will take longer to run a tool. To use your ArcGIS GeoAnalytics Server to perform analysis, see GeoAnalytics Tools.

Parameters

LabelExplanationData Type
Input Points

The time-enabled point feature class that will be used to trace proximity events.

Feature Layer
Entity ID Field

The text field representing unique IDs for each entity.

Field
Output Proximity Events

The output feature class containing the trace proximity events.

Feature Class
Distance Method

Specifies the distance type that will be used with the Spatial Search Distance parameter.

  • PlanarPlanar distance will be used between features. This is the default.
  • GeodesicGeodesic distance will be used between features. This line type takes into account the curvature of the spheroid and correctly deals with data near the dateline and poles.
String
Spatial Search Distance
(Optional)

The maximum distance between two points to be considered in proximity. Features within the spatial search distance and temporal search distance criteria are considered to be in proximity of each other.

Linear Unit
Temporal Search Distance
(Optional)

The maximum duration between two points to be considered in proximity. Features within the temporal search distance and that meet the spatial search distance criteria are considered to be in proximity of each other.

Time Unit
Define Entities of Interest Using
(Optional)

Specifies the entities of interest.

  • Entities of Interest IDsEntity names and times will be used as the entities of interest. This is the default.
  • Selected features in a specified entity of interest layerThe selected feature in a specified entity of interest layer will be used as the entities of interest.
String
Entities of Interest IDs

The entity names and start times for the entities of interest. This parameter is supported only when Entities of Interest IDs is specified for the Define Entities of Interest Using parameter.

  • Entity ID—A unique entity name. The names are case sensitive and must be strings.
  • Starting From—An optional starting time to trace an entity of interest. If a time is not specified, January 1, 1970, will be used.

Value Table
Entities of Interest Layer

The layer or table that contains the entities of interest. This parameter is supported only when Selected features in a specified entity of interest layer is specified for the Define Entities of Interest Using parameter.

Table View
Output Tracks
(Optional)

An output layer containing the first trace event and all subsequent features for that specified entity.

Feature Class
Maximum Trace Depth

The maximum degrees of separation between an entity of interest and an entity farther down the trace (downstream).

Long
Attribute Match Criteria
(Optional)

The fields used to constrain the proximity event.

Field

arcpy.geoanalytics.TraceProximityEvents(in_points, entity_id_field, out_feature_class, distance_method, {spatial_search_distance}, {temporal_search_distance}, {entities_of_interest_input_type}, entities_interest_ids, entities_interest_layer, {out_tracks_layer}, max_trace_depth, {attribute_match_criteria})
NameExplanationData Type
in_points

The time-enabled point feature class that will be used to trace proximity events.

Feature Layer
entity_id_field

The text field representing unique IDs for each entity.

Field
out_feature_class

The output feature class containing the trace proximity events.

Feature Class
distance_method

Specifies the distance type that will be used with the Spatial Search Distance parameter.

  • PLANARPlanar distance will be used between features. This is the default.
  • GEODESICGeodesic distance will be used between features. This line type takes into account the curvature of the spheroid and correctly deals with data near the dateline and poles.
String
spatial_search_distance
(Optional)

The maximum distance between two points to be considered in proximity. Features within the spatial search distance and temporal search distance criteria are considered to be in proximity of each other.

Linear Unit
temporal_search_distance
(Optional)

The maximum duration between two points to be considered in proximity. Features within the temporal search distance and that meet the spatial search distance criteria are considered to be in proximity of each other.

Time Unit
entities_of_interest_input_type
(Optional)

Specifies the entities of interest.

  • ID_START_TIMEEntity names and times will be used as the entities of interest. This is the default.
  • SELECTED_FEATUREThe selected feature in a specified entity of interest layer will be used as the entities of interest.
String
entities_interest_ids
[entities_interest_ids,...]

The entity names and start times for the entities of interest. This parameter is supported only when ID_START_TIME is specified for the entities_of_interest_input_type parameter.

  • Entity ID—A unique entity name. The names are case sensitive.
  • Starting from—An optional starting time to trace an entity of interest. If a time is not specified, January 1, 1970, will be used.

Value Table
entities_interest_layer

The layer or table that contains the entities of interest. This parameter is supported only when SELECTED_FEATURE is specified for the entities_of_interest_input_type parameter.

Table View
out_tracks_layer
(Optional)

An output layer containing the first trace event and all subsequent features for that specified entity.

Feature Class
max_trace_depth

The maximum degrees of separation between an entity of interest and an entity farther down the trace (downstream).

Long
attribute_match_criteria
[attribute_match_criteria,...]
(Optional)

The fields used to constrain the proximity event.

Field

Code sample

TraceProximityEvents (stand-alone script)

The following stand-alone script demonstrates how to use the TraceProximityEvents function.

# Name: TraceProximityEvents.py
# Description: Trace proximity events for user1 and user4 with 30 feet 
#              spatial search distance and 10 minute temporal search distance.

# Import system modules
import arcpy

# Set workspace
arcpy.env.workspace = r"C:/data/TraceData.gdb"

# Use time-enabled multifile feature connection dataset
inFeatures = r"C:/data/Example.mfc/example_tracks"

entityIDField = "user_id"
outFile = "ProximityEvents" 
spatialDistance = "30 Feet"
temporalDistance = "10 Minutes"
entitiesOfInterest = [['user1', '3/30/2020 9:00:00 AM'], ['user4', '3/30/2020 9:00:00 AM']]
outTracks = "out_tracks"
max_trace_depth = 3

# Run Trace Proximity Events
arcpy.gapro.TraceProximityEvents(inFeatures, entityIDField, outFile, "PLANAR",
                                 spatialDistance, temporalDistance, 
                                 "ID_START_TIME", entitiesOfInterest, None, 
                                 outTracks, max_trace_depth)