Tracing in a trace network helps solve problems and answer questions related to the state of your network at any moment. To trace a trace network, use the Trace tool.
Several types of traces are provided with the Trace tool:
Along with these trace types, the Trace tool also includes a comprehensive set of advanced configurations used to refine each provided trace type. These configurations allow you to constitute traversability, distinguish what features should be returned, and set up calculations to be performed. ModelBuilder can be used to save complex configurations and also allows you to reduce the number of parameters presented on the model tool interface. This helps you and others rerun advanced traces with a single click.
Each configuration component is examined in the following sections. See the Trace tool for parameter options and usage information.
Include barriers in results
By default, barrier features are returned in the results of a trace unless the barrier feature exists alongside a starting point. This can be controlled using the Include Barrier Features and Ignore Barriers At Starting Points options.
Include Barrier Features
Include barriers in the results of a trace. This encompasses feature barriers set in the Trace Locations pane as well as dynamically configured barriers: condition barriers, function barriers, filter barriers, and filter function barriers.
The selection set returned by a trace may display unexpected results when barriers are placed on edge features with midspan connectivity and the Include Barrier Features option is disabled. If any part of the feature is returned by the trace, the entire feature is selected and displayed in the trace result.
| Configuration option | Description |
|---|---|
Include Barrier Features |
|
Ignore Barriers At Starting Points
Ignore barriers in the trace configuration if they are starting points.
| Configuration option | Description |
|---|---|
Ignore Barriers At Starting Points |
|
Ensure network consistency
A consistent area of a network is one where the network topology has been validated and does not have any dirty areas. Validation is the only way to guarantee a trace is reading the latest information about your network from the network topology.
The Validate Consistency configuration option on the Trace tool allows you to ensure the trace results are consistent with the network topology. When Validate Consistency is set to true, the trace operation fails if any dirty areas intersect the trace path. When this occurs, the tool returns an error that includes the class name and global id of features in the trace path that are found to be dirty, as shown in the example below:
ERROR 002041: One or more dirty areas were discovered.
[[NHDFlowline: {0DBFACDA-45D6-BA67-33CE-A750BE632C05}]]
Failed to execute (Trace).
To remove dirty areas associated with edits, the network topology must be validated.
Note:
Only dirty areas created from delete operations, updates to existing network features, or creation of error features will cause an error to be raised about inconsistencies in the trace results. Dirty areas from newly created features will not cause a failure with the Validate Consistency check.
A trace that is run without the Validate Consistency check box enabled can lead to unexpected trace results. For example, a feature is deleted from a network that breaks the only path between location A and location B. A dirty area is created for the deleted feature. Before the network topology is validated, a trace is executed to find connected features starting at location A, with the Validate Consistency option unchecked. The trace reaches location B and the tool completes with no warnings. Location B was reached because the deletion of the feature connecting A to B has not been updated in the network topology through the validate operation.
If the Validate Consistency option is checked in the scenario above, when the trace reaches the dirty area marking the deleted feature, an error is returned in the tool to let you know a dirty area was encountered, and the trace fails. After the topology is validated for the area being traced, the trace cannot reach location B, as the deleted feature is now reflected in the network topology. If the network topology is not validated for the entire extent of the area that will be traced, other dirty areas could also be encountered.
| Configuration option | Description |
|---|---|
Validate Consistency |
|
Control what is traced
Barriers are used during a trace to denote a stopping location; features beyond that location are not traced. The results of a trace will not include features past a barrier but can optionally include the barrier itself. Other parameters such as Allow Indeterminate Flow and those found within Advanced Options help to define what controls the traversability of network paths.
Allow Indeterminate Flow
When performing an upstream or downstream trace, the trace analytic uses the value in the Flow direction network attribute to determine directionality. In some scenarios, there may be line features with indeterminate flow direction specified that signify bidirectional flow. This option specifies whether features along a path with indeterminate flow are traced or stop the traversability of the trace. This parameter is only honored when running an upstream or downstream trace.
| Configuration option | Description |
|---|---|
Allow Indeterminate Flow |
|
Advanced Options
The Advanced Options section of the Trace tool includes Condition Barriers and Function Barriers to control the traversability of a trace. Condition barriers are expressions based on network attributes that define where a trace should stop. Function barriers define where a trace should stop when a condition is satisfied.
Traversability scope is further controlled by the traversability_scope parameter labeled Apply Traversability To in the Trace tool. This parameter determines whether traversability is applied to both junctions and edges, junctions only, or edges only. For example, if traversability is applied to junctions only and an edge satisfies the condition specified in a condition barrier, the trace does not stop at the edge due to the traversability scope.
To learn more, see Barriers.
Set up functions
A function is a trace configuration that allows you to run calculations on network attributes associated with traced features. An optional network attribute filter may be added to each function. When specified, the function will only be applied to features that satisfy the network attribute filter. Filters in functions are used to introduce a conditional requirement. For example, add up the length of all the lines where the PathType attribute includes the value Paved. More than one function can be specified for a trace.
Control what is returned
To control what is returned in the results of a trace, two parameters are provided, Output Conditions and Result Types.
Output Conditions
The Output Conditions filter supports the use of network attributes and screens every feature encountered during a trace to see if it meets the criteria specified in the filter. Network attributes live in the network topology and are associated with a field in one or more feature classes. In an output condition, the name of the network attribute, an operator, and a value valid for the network attribute are specified.
Consider a scenario involving a trail network, in this case a network attribute is input to return paved trails. In this case, the Trails class has a field named PathType. This field is associated with a network attribute named Surface. The Output Conditions parameter is configured to look for feature classes with the Surface network attribute where the value is equal to Paved. The results of the trace include features from a feature class with this field and the Paved value, as well as features from classes without the PathType field.
Multiple Output Conditions values can be implemented using the Combine Using parameter. Both types of outputs can be used and more than one output type can be set up. Combining output types allows you to do such things as return all paved trails that exceed 1,000 meters in length.
Result Types
The optional Result Types parameter allows you to control the type of results returned by the trace. The Aggregated Geometry, Selection, Network Layers, Connectivity, and Elements result types can be specified independently or concurrently to generate output geometries, generate a selection set, return trace results as selection sets on feature layers in a group layer, return a connectivity graph of network features connected through geometric coincidence, or return feature-based information to a .json file, respectively.
| Parameter | Options |
|---|---|
Result Types |
Note:For enterprise geodatabases, the Connectivity option requires ArcGIS Enterprise 10.9.1 or later. |
The Aggregated Geometry option enables trace results to be returned as multipart geometry in a feature class. This honors the location of starting points and barriers placed midspan on edge features to return partial feature results.
Review the images below to compare the differences between the selection and aggregated geometry result type options in a downstream trace. The network below contains five line features (represented as f1, f2, f3, f4, and f5) that are composed of nine edge elements (represented as e1, e2, e3, and so on).
In this example which includes barrier features, the selection result returns five point features and three line features consisting of seven edge elements (f1::e1,e2,e3, f2::e1,e2, and f5::e1,e2). The aggregated geometry result returns the same features but excludes edge elements f1::e1,e2 and f5::e2.
When a barrier is placed along an edge with the Include Barrier Features configuration option checked, the trace will stop at the barrier feature and return partial feature geometry for the edge in the trace results. If the Include Barrier Features option is unchecked, the trace will stop at the prior line end or junction encountered with midspan connectivity.
The images below show the difference in trace results when using the Include Barrier Features option to include or exclude barrier features in the trace results. In this example, both the starting point and barrier are placed along an edge. With this option enabled, the selection result returns four point features and three line features consisting of seven edge elements (f1::e1,e2,e3, f2::e1,e2, and f5::e1,e2). The aggregated geometry result will return the same three features but excludes edge elements f1::e1 and f5::e2. The selection result would not change if we were to exclude barrier features with Include Barrier Features unchecked; however, the aggregated geometry results would additionally exclude f1::e2.
When the Aggregated Geometry option is selected for the result type, four additional parameters are provided to define the trace output behavior.
- Clear All Previous Trace Results
- Trace Name
- Aggregated Points
- Aggregated Lines
The Clear All Previous Trace Results check box provides an option to truncate or append to the contents of the feature classes chosen to store aggregated geometry. The default option overwrites the previous trace results and presents aggregated geometry only for the current trace operation.
| Parameter | Options |
|---|---|
Clear All Previous Trace Results |
|
The optional Trace Name parameter enables the creation of a string identifier for the trace operation to assist with identification of trace results. When used with the Clear All Previous Trace Results parameter check box unchecked, this parameter allows you to run multiple trace operations and compare the results in the output aggregated geometry feature classes.
The Aggregated Points and Aggregated Lines parameters enable you to specify feature classes for storage of the aggregated result geometry. By default, each parameter is populated with a system generated feature class stored in the project's default geodatabase:
- Trace_Results_Aggregated_Lines—A line feature class
- Trace_Results_Aggregated_Points—A multipoint feature class
These feature classes are created automatically if they do not exist. Existing feature classes may also be used to store aggregated geometry. If a feature class other than the default is used, it must contain a String field called TRACENAME and match the geometry type of the output.
The generation of output geometry with partial feature results provides a more accurate representation of the trace and enables comparison and reuse of trace results for other tasks.
Note:
Disabling the geoprocessing option Allow geoprocessing tools to overwrite existing datasets can cause tool validation issues if the output feature classes for aggregated geometry result types exist in the default geodatabase for the project. This can be addressed by enabling the geoprocessing option or by renaming the aggregated points, lines, and polygons feature classes in the default geodatabase of the project.
When the Selection option is selected for the result type, an additional Selection Type parameter is provided to define how the selection will be applied and what action to perform if a selection already exists.
| Parameter | Options |
|---|---|
Selection Type |
|
The Network Layers result types option allows you to return trace results as selection sets on feature layers in a group layer. When this option is selected in ArcGIS Pro, a new group layer is added to the map. Feature layers are only created for classes that contain features returned by the trace. Each feature layer contains a selection set of features returned by the trace that can be used to work with the results of a trace in ModelBuilder and Python.
When the Network Layers option is selected, an additional Output Group Layer Name parameter is provided to name the output group layer that is created. When working in ArcGIS Pro a new group layer is added to the active map with the specified name.
The Connectivity result types option returns trace results as a connectivity graph of network features connected through geometric coincidence. When this option is selected, connectivity is output to a .json file in the specified location that can be parsed and imported into other systems to build your own graph representation of the data. Connectivity information is only returned for network features returned by the trace.
When the Connectivity option is selected for the result type, an additional Output JSON parameter is provided to give the location of the output .json file.
The Elements result types option returns trace results as feature-based information. When this option is selected, feature-based information is output to a .json file in the specified location that can be used as an input to perform additional analysis.
When the Elements option is selected, an additional Output JSON parameter is provided to give the location of the output .json file. The output .json file contains the following information for all traversed network features under elements:
- networkSourceId
- globalId
- objectId
Additional information is returned for line features:
- positionFrom and positionTo
Load named trace configurations
Named trace configurations allow complex traces to be created for sharing and reuse. The Trace tool enables you to load an existing named trace configuration to define the properties for a trace. This simplifies the user experience associated with tracing and provides consistency through the reuse of common traces in an organization.
| Parameter | Options |
|---|---|
Use Trace Configuration |
|
A Trace Configuration Name parameter is provided to specify the name of the trace configuration that will be used to define the properties of the trace. This parameter is only available when Use Trace Configuration is enabled.