Add Trace Configuration (Trace Network)

Summary

Creates a trace configuration in the trace network.

Trace configurations allow you to configure and store the properties of complex traces for reuse and sharing. Trace configurations stored in a trace network can be loaded and executed from the Trace tool or shared through a map service consumed by a web map or field app.

Learn more about how to add a trace configuration

Usage

  • The input trace network must be version 2 or later.

  • When working with an enterprise geodatabase, the input trace network must be from a trace network service.

  • The connected portal account is listed as the creator of the trace configuration.

    • Operating system authentication is used to store the creator of a trace configuration when working with a trace network in a file geodatabase.

Syntax

arcpy.tn.AddTraceConfiguration(in_trace_network, trace_config_name, trace_type, {description}, {tags}, {path_direction}, {shortest_path_network_attribute_name}, {include_barriers}, {validate_consistency}, {ignore_barriers_at_starting_points}, {allow_indeterminate_flow}, {condition_barriers}, {function_barriers}, {traversability_scope}, {functions}, {output_conditions}, {result_types})
ParameterExplanationData Type
in_trace_network

The trace network that will contain the new trace configuration.

Trace Network; Trace Network Layer
trace_config_name

The name for the trace configuration.

String
trace_type

Specifies the type of trace that will be configured.

  • CONNECTEDA connected trace that begins at one or more starting points and spans outward along connected features will be used.
  • UPSTREAMAn upstream trace that discovers features upstream from a location in the network will be used. This type of trace uses flow direction.
  • DOWNSTREAMA downstream trace that discovers features downstream from a location in the network will be used. This type of trace uses flow direction.
  • SHORTEST_PATHA shortest path trace that finds the shortest path between two starting points in the network regardless of flow direction will be used. The cost of traversing the path is determined based on the network attribute set for the shortest_path_network_attribute_name parameter.
String
description
(Optional)

The description of the trace configuration.

String
tags
[tags,...]
(Optional)

A set of tags used to identify the trace configuration. The tags can be used in searches and indexing.

String
path_direction
(Optional)

Specifies the direction of the trace path. The cost of traversing the path is determined by the shortest_path_network_attribute_name parameter value. This parameter is only honored when running a SHORTEST_PATH trace type.

  • NO_DIRECTIONThe path between the two starting points regardless of the direction of flow will be used. This is the default.
  • PATH_UPSTREAMThe upstream path between the two starting points will be used.
  • PATH_DOWNSTREAMThe downstream path between the two starting points will be used.
String
shortest_path_network_attribute_name
(Optional)

The name of the network attribute used to calculate the path. When running a shortest path trace type, the shortest path is calculated using a numeric network attribute such as shape length. Cost and distance based paths can both be achieved. This parameter is required when running a shortest path trace.

String
include_barriers
(Optional)

Specifies whether the traversability barrier features will be included in the trace results.

  • INCLUDE_BARRIERSTraversability barrier features will be included in the trace results. This is the default.
  • EXCLUDE_BARRIERSTraversability barrier features will not be included in the trace results.
Boolean
validate_consistency
(Optional)

Specifies whether an error will be returned if dirty areas are encountered in any of the traversed features. This is the only way to guarantee a trace is passing through features with consistent status in the network. To remove dirty areas, validate the network topology.

  • VALIDATE_CONSISTENCYThe trace will return an error if dirty areas are encountered in any of the traversed features. This is the default.
  • DO_NOT_VALIDATE_CONSISTENCYThe trace will return results regardless of whether dirty areas are encountered in any of the traversed features.
Boolean
ignore_barriers_at_starting_points
(Optional)

Specifies whether barriers in the trace configuration will be ignored for starting points.

  • IGNORE_BARRIERS_AT_STARTING_POINTSBarriers at starting points will be ignored in the trace.
  • DO_NOT_IGNORE_BARRIERS_AT_STARTING_POINTSBarriers at starting points will not be ignored in the trace. This is the default.
Boolean
allow_indeterminate_flow
(Optional)

Specifies whether features that have indeterminate or uninitialized flow will be traced. This parameter is only honored when running an upstream or downstream trace.

  • TRACE_INDETERMINATE_FLOWFeatures that have indeterminate or uninitialized flow direction will be traced.
  • IGNORE_INDETERMINATE_FLOWFeatures that have indeterminate or uninitialized flow direction will not be traced. This is the default.
Boolean
condition_barriers
[[Name, Operator, Type, Value, Combine Using],...]
(Optional)

Sets a traversability barrier condition on features based on a comparison to a network attribute. A condition barrier uses a network attribute, an operator and a type, and an attribute value. For example, stop a trace when a feature has the Code attribute equal to the specific value of ArtificialPath. When a feature meets this condition, the trace stops. If you're using more than one attribute, you can use the Combine Using component to define an And or an Or condition.

Condition barrier components are as follows:

  • Name—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of different operators.
  • Type—Choose a specific value or network attribute from the value specified in the Name component.
  • Value—Provide a specific value for the input attribute type that would cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

Operator components are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.

Type components are as follows:

  • SPECIFIC_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.

Combine Using component are as follows:

  • ANDCombine the condition barriers.
  • ORUse or if either condition barrier is met.
Value Table
function_barriers
[[Function, Attribute, Operator, Value, Use Local Values],...]
(Optional)

Sets a traversability barrier on features based on a function. Function barriers can be used, for example, to restrict how far the trace travels from the starting point or to set a maximum value to stop a trace. For example, the length of each line traveled is added to the total distance traveled so far. When the total length traveled reaches the value specified, the trace stops.

Function barrier components are as follows:

  • Function—Choose from a number of calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Value—Provide a specific value for the input attribute type that, if discovered, will cause the termination.
  • Use Local Values—Calculate values in each direction as opposed to an overall global value. For example, a function barrier calculates the sum of shape length in which the trace terminates if the value is greater than or equal to 4. In the global case, after you have traversed two edges with a value of 2, you have already reached a shape length sum of 4, so the trace stops. If local values are used, the local values along each path change, and the trace continues.

Function components are as follows:

  • AVERAGEThe average of the input values.
  • COUNTThe number of features.
  • MAXThe maximum of the input values.
  • MINThe minimum of the input values.
  • ADDAdd the values.
  • SUBTRACTSubtract the values.

Operator components are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THANThe attribute is less than the value.

Use Local Values components are as follows:

  • TRUEUse local values.
  • FALSEUse global values. This is the default.
Value Table
traversability_scope
(Optional)

Specifies whether traversability will be applied to junctions, edges, or both. For example, in a network of recreational trails, if a condition barrier is defined to stop the trace if the path type is gravel and traversability scope is set to junctions only, the trace will not stop even if it encounters a gravel path, because the path type is only applicable to edges. In other words, this parameter indicates to the trace whether to ignore junctions, ignore edges, or include both junctions and edges in the trace.

  • BOTH_JUNCTIONS_AND_EDGESTraversability will be applied to both junctions and edges. This is the default.
  • JUNCTIONS_ONLYTraversability will be applied to junctions only.
  • EDGES_ONLYTraversability will be applied to edges only.
String
functions
[[Function, Attribute, Filter Name, Filter Operator, Filter Type, Filter Value],...]
(Optional)

The calculation function that will be applied to the trace results.

Functions components are as follows:

  • Function—Choose from a number of calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Filter Name—Filter the function results by attribute name.
  • Filter Operator—Choose from a number of operators.
  • Filter Type—Choose from a number of filter types.
  • Filter Value—Provide a specific value for the input filter attribute.

Function component options are as follows:

  • AVERAGEThe average of the input values.
  • COUNTThe number of features.
  • MAXThe maximum of the input values.
  • MINThe minimum of the input values.
  • ADDThe sum of the values.
  • SUBTRACTThe difference between the values.

For example, a starting point feature has a value of 20. The next feature has a value of 30. If you are using the MIN function, the result is 20. MAX is 30, ADD is 50, AVERAGE is 25, COUNT is 2, and SUBTRACT is -10.

Filter Operator component options are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THANThe attribute is less than the value.

Filter Type component options are as follows:

  • SPECIFIC_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.
Value Table
output_conditions
[[Name, Operator, Type, Value, Combine Using],...]
(Optional)

The types of features that will be returned based on a network attribute. For example, in a trace configured to filter out everything but Tap features, any traced features that do not have the Tap attribute assigned to them are not included in the results. Any traced features that do are returned in the result selection set. If using more than one attribute, you can use the Combine Using option to define an And or an Or condition.

Output conditions components are as follows:

  • Name—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Type—Choose a specific value or network attribute from the value =specified in the Name component.
  • Value—Provide a specific value of the input attribute type that would cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

Operator component options are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THANThe attribute is less than the value.

Type component options are as follows:

  • SPECIFIC_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.

Combine Using component options are as follows:

  • ANDCombine the conditions.
  • ORUse or if either condition is met.
Value Table
result_types
[result_types,...]
(Optional)

Specifies the type of results that will be returned by the trace.

  • SELECTION The trace results will be returned as a selection set on the appropriate network features. This is the default.
  • AGGREGATED_GEOMETRY The trace results will be aggregated by geometry type and stored in feature classes displayed in layers on the active map.
String

Derived Output

NameExplanationData Type
updated_trace_network

The updated trace network.

Trace Network

Code sample

AddTraceConfiguration example (Python window)

This sample script adds a trace configuration named Upstream_HUC12 to a trace network called HydroNetwork.

import arcpy
arcpy.AddTraceConfiguration_un(
        r"HydroNetwork", "Upstream_HUC12", "UPSTREAM", 
        "Upstream trace for HUC12_allow indeterminate", "HUC12;Upstream", 
        "NO_DIRECTION", '', "INCLUDE_BARRIERS", "VALIDATE_CONSISTENCY", 
        "DO_NOT_IGNORE_BARRIERS_AT_STARTING_POINTS", "TRACE_INDETERMINATE_FLOW", 
        None, None, "BOTH_JUNCTIONS_AND_EDGES", None, None, None)

Environments

This tool does not use any geoprocessing environments.

Licensing information

  • Basic: No
  • Standard: Yes
  • Advanced: Yes

Related topics