Trace (Utility Network)

Summary

Returns selected features based on connectivity or traversability from the specified starting points.

Utility network tracing capabilities allow you to analyze the paths in your network. This tool runs a trace that returns features based on connectivity or traversability from the specified starting points. Traversability refers to paths established by connected or associated features that also meet configuration requirements.

By default, trace results are returned as a selection and include the entire line feature. The Result Types parameter option Aggregated Geometry can be specified to return partial feature results.

With the Aggregated Geometry option, starting points placed along an edge will return the edge element from the previous junction with midspan connectivity or endpoint. When a barrier is placed along an edge with the Include Barrier Features parameter checked, the trace will stop at the next junction encountered with midspan connectivity or the line end. If the Include Barrier Features parameter is unchecked, the trace will stop at the previous junction encountered with midspan connectivity or previous line end.

The resulting selection set or output feature class generated by the trace can then be propagated to another map, propagated to a diagram view of the network, or used as input to another tool or trace.

Learn more about tracing utility networks

Usage

  • The network topology must be enabled. Since the Trace tool relies on the network topology, the results of a trace are not guaranteed to be accurate if dirty areas are traced. The network topology for the area to be traced must be validated to reflect the most recent edits or updates made to the network.

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

  • When executing a subnetwork-based trace using the Trace tool via Python, the Subnetwork Trace Configuration of the subnetwork definition is not used for the input Tier and must be manually specified.

  • When working with network attributes assigned to a date field for filter barriers, filter function barriers, functions, and output conditions, the date value should be formatted as yyyy-mm-dd hh:mm:ss, for example, 2020-10-12 18:45:31.

Syntax

arcpy.un.Trace(in_utility_network, trace_type, {starting_points}, {barriers}, {domain_network}, {tier}, {target_tier}, {subnetwork_name}, {shortest_path_network_attribute_name}, {include_containers}, {include_content}, {include_structures}, {include_barriers}, {validate_consistency}, {condition_barriers}, {function_barriers}, {traversability_scope}, {filter_barriers}, {filter_function_barriers}, {filter_scope}, {filter_bitset_network_attribute_name}, {filter_nearest}, {nearest_count}, {nearest_cost_network_attribute}, {nearest_categories}, {nearest_assets}, {functions}, {propagators}, {output_assettypes}, {output_conditions}, {include_isolated_features}, {ignore_barriers_at_starting_points}, {include_up_to_first_spatial_container}, {result_types}, selection_type, {clear_all_previous_trace_results}, {trace_name}, {aggregated_points}, {aggregated_lines}, {aggregated_polygons}, {allow_indeterminate_flow}, {validate_locatability}, {use_trace_config}, {trace_config_name})
ParameterExplanationData Type
in_utility_network

The utility network on which the trace will be run. When working with an enterprise geodatabase, an input utility network must be from a feature service; a utility network from a database connection is not supported.

Utility Network; Utility Network Layer
trace_type

Specifies the type of trace to execute.

  • CONNECTED A connected trace begins at one or more starting points and spans outward along connected features. This is the default.
  • SUBNETWORK A subnetwork trace begins at one or more starting points and spans outward to encompass the extent of the subnetwork.
  • SUBNETWORK_CONTROLLERSA subnetwork controllers trace locates sources and sinks on subnetwork controllers associated with a subnetwork.
  • UPSTREAMAn upstream trace discovers features upstream from a location in the network.
  • DOWNSTREAMA downstream trace discovers features downstream from a location in the network.
  • LOOPS Loops are areas of the network where flow direction is ambiguous. A loops trace spans outward from the starting point based on connectivity.
  • SHORTEST_PATHA shortest path trace identifies the shortest path between two starting points.
  • ISOLATIONAn isolation trace discovers features that isolate an area of a network.
String
starting_points
(Optional)

A table or feature class containing one or more records that represent the starting points of the trace. This feature class or table must include the FEATUREGLOBALID field to store information from the associated network feature. To view the specific format, create starting points using the Starting Points tool in the Trace Locations pane and view the schema of the UN_Temp_Starting_Points feature class stored in your default geodatabase.

Feature Layer; Table View
barriers
(Optional)

A table or feature class containing one or more features that represent the barriers of the trace that prevent the trace from traversing beyond that point. This feature class or table must include the FEATUREGLOBALID field to store information from the associated network feature. To view the specific format, create barriers using the Barriers tool in the Trace Locations pane and view the schema of the UN_Temp_Barriers feature class stored in your default geodatabase.

Feature Layer; Table View
domain_network
(Optional)

The name of the domain network where the trace will be run. This parameter is required when running the subnetwork, subnetwork controllers, upstream, and downstream trace types.

String
tier
(Optional)

The name of the tier to start the trace. This parameter is required when running the subnetwork, subnetwork controllers, upstream, and downstream trace types.

String
target_tier
(Optional)

The name of the target tier to which the input tier flows. If this parameter is missing for upstream and downstream traces, those traces will stop when they reach the boundary of the starting subnetwork. This parameter can be used to allow these traces to continue either farther up or farther down the hierarchy.

String
subnetwork_name
(Optional)

The name of the subnetwork where the trace will be run. This parameter can be used when running a subnetwork trace type. If a subnetwork name is specified, the Starting Points parameter (the starting_points parameter in Python) is not required.

String
shortest_path_network_attribute_name
(Optional)

The network attribute used to calculate the shortest 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_containers
(Optional)

Specifies whether the container features will be included in the trace results.

  • INCLUDE_CONTAINERSContainer features will be included in the trace results.
  • EXCLUDE_CONTAINERSContainer features will not be included in the trace results. This is the default.
Boolean
include_content
(Optional)

Specifies whether the trace will return content in containers in the results.

  • INCLUDE_CONTENTContent in container features will be included in the trace results.
  • EXCLUDE_CONTENTContent in container features will not be included in the trace results. This is the default.
Boolean
include_structures
(Optional)

Specifies whether structure features and objects will be included in the trace results.

  • INCLUDE_STRUCTURESStructure features and objects will be included in the trace results.
  • EXCLUDE_STRUCTURESStructure features and objects will not be included in the trace results. This is the default.
Boolean
include_barriers
(Optional)

Specifies whether the traversability barrier features will be included in the trace results. Traversability barriers are optional even if they have been preset in the subnetwork definition. This parameter does not apply to device features with terminals.

  • 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
condition_barriers
[[Name, Operator, Type, Value, Combine Using],...]
(Optional)

Sets a traversability barrier condition on features based on a comparison to a network attribute or check for a category string. 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 Device Status attribute equal to the specific value of Open. When a feature meets this condition, the trace stops. If you're using more than one attribute, you can use the Combine using parameter 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 operators.
  • Type—Choose a specific value or network attribute from the value that is specified in the name parameter.
  • 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.

The condition barriers operator value 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The condition barriers Type value options are as follows:

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

The condition barriers Combine Using value options are as follows:

  • ANDCombine the condition barriers.
  • ORUse if either condition barrier is met.

Learn more about using multiple conditional expressions

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 to do such things as restrict how far the trace travels from the starting point, or 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 that is calculating 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 will 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.

The function barrier function value 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. Subnetwork controllers and loops trace types do not support the subtract function.

The function barrier operator value options are as follows:

  • IS_EQUAL_TOThe function result is equal to the value.
  • DOES_NOT_EQUALThe function result is not equal to the value.
  • IS_GREATER_THANThe function result is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe function result is greater than or equal to the value.
  • IS_LESS_THANThe function result is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe function result is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The function barrier Use Local Values options are as follows:

  • TRUELocal values will be used.
  • FALSEGlobal values will be used. This is the default.
Value Table
traversability_scope
(Optional)

The type of traversability to enforce. Traversability scope dictates whether traversability is enforced at junctions, edges, or both. For example, if a condition barrier is defined to stop the trace if Device Status is equal to Open and traversability scope is set to edges only, the trace will not stop—even if it encounters an open device—because Device Status is only applicable to junctions. In other words, this parameter indicates to the trace whether to ignore junctions, edges, or both.

  • BOTH_JUNCTIONS_AND_EDGESApply traversability to both junctions and edges. This is the default.
  • JUNCTIONS_ONLYApply traversability to junctions only.
  • EDGES_ONLYApply traversability to edges only.
String
filter_barriers
[[Name, Operator, Type, Value, Combine Using],...]
(Optional)

Specifies when a trace will stop for a specific category or network attribute. For example, stop a trace at features that have a life cycle status attribute that is equal to a certain value. This parameter is used to set a terminator based on a value of a network attribute that is defined in the system. If you're using more than one attribute, you can use the Combine Using option to define an And or an Or condition.

Filter barrier components are as follows:

  • Name—Filter by category or 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 that is specified in the name parameter.
  • 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.

The filter barriers operator value 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES NOT INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INLCUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The filter barriers Type value options are as follows:

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

The filter barriers Combine Using value options are as follows:

  • ANDCombine the condition barriers.
  • ORUse if either condition barrier is met.

Learn more about using multiple conditional expressions

Value Table
filter_function_barriers
[[Function, Attribute, Operator, Value, Use Local Values],...]
(Optional)

Filters the results of the trace for a specific category.

Filter function barriers 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 that is calculating the sum of Shape length where 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 will 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, or the trace continues.

The filter function barriers function value 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. Subnetwork controllers and loops trace types do not support the subtract function.

The filter function barriers operator value 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The filter function barriers Use Local Values options are as follows:

  • TRUELocal values will be used.
  • FALSEGlobal values will be used. This is the default.
Value Table
filter_scope
(Optional)

Specifies whether the filter for a specific category will be enforced at junctions, edges, or both. For example, if a filter barrier is defined to stop the trace if Device Status is equal to Open and traversability scope is set to edges only, the trace will not stop—even if the trace encounters an open device—because Device Status is only applicable to junctions. In other words, this parameter indicates to the trace whether to ignore junctions, edges, or both.

  • BOTH_JUNCTIONS_AND_EDGESThe filter will be applied to both junctions and edges. This is the default.
  • JUNCTIONS_ONLYThe filter will be applied to junctions only.
  • EDGES_ONLYThe filter will be applied to edges only.
String
filter_bitset_network_attribute_name
(Optional)

The name of the network attribute that will be used to filter by bitset. This parameter is only applicable to upstream, downstream, and loops trace types. This parameter can be used to add special logic during a trace so the trace more closely reflects real-world scenarios. For example, for a loops trace, the Phases current network attribute can determine if the loop is a true electrical loop (the same phase is energized all around the loop, that is, A) and return only real electrical loops for the trace results. An example for an upstream trace is when tracing an electric distribution network, specify a Phases current network attribute, and the trace results will only include valid paths that are specified in the network attribute, not all paths.

String
filter_nearest
(Optional)

Specifies whether the k-nearest neighbors algorithm will be used to return a number of features of a certain type within a given distance. When this parameter is used, you can specify a count and a cost as well as a collection of categories, an asset type, or both.

  • FILTER_BY_NEARESTThe k-nearest neighbors algorithm will be used to return a number of features as specified in the nearest_count, nearest_cost_network_attribute, nearest_categories, or nearest_assets parameter.
  • DO_NOT_FILTERThe k-nearest neighbors algorithm will not be used to filter results. This is the default.
Boolean
nearest_count
(Optional)

The number of features to be returned when filter_nearest is FILTER_BY_NEAREST.

Long
nearest_cost_network_attribute
(Optional)

The numeric network attribute that will be used to calculate nearness, cost, or distance when filter_nearest is FILTER_BY_NEAREST—for example, Shape length.

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

The categories that will be returned when filter_nearest is FILTER_BY_NEAREST—for example, Protective.

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

The asset groups and asset types that will be returned when filter_nearest is FILTER_BY_NEAREST—for example, ElectricDistributionDevice/Transformer/Step Down.

String
functions
[[Function, Attribute, Filter Name, Filter Operator, Filter Type, Filter Value],...]
(Optional)

Applies a calculation function 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.

The functions Function value 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.Subnetwork controllers and loops trace types do not support the subtract function.

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

The Filter Operator value 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The functions Filter Type value options are as follows:

  • SPECIFIC_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.
Value Table
propagators
[[Attribute, Substitution Attribute, Function, Operator, Value],...]
(Optional)

Specifies the network attributes to propagate as well as how that propagation will occur during a trace. Propagated class attributes denote the key values on subnetwork controllers that are disseminated to the rest of the features in the subnetwork. For example, in an electric distribution model, you can propagate the phase value.

Propagators components are as follows:

  • Attribute—Filter by any network attribute defined in the system.
  • Substitution Attribute—Use a substituted value instead of bitset network attribute values. Substitutions are encoded based on the number of bits in the network attribute being propagated. A substitution is a mapping of each bit in phase to another bit. For example, for Phase AC, one substitution could map bit A to B, and bit C to null. In this example, the substitution for 1010 (Phase AC) is 0000-0010-0000-0000 (512). The substitution captures the mapping so you know that Phase A was mapped to B and Phase C was mapped to null, and not the other way around (that is, Phase A was not mapped to null and Phase C was not mapped to B).
  • Function—Choose from a number of calculation functions.
  • Operator—Choose from a number of operators.
  • Value—Provide a specific value for the input attribute type that would cause termination based on the operator value.

The propagators function value options are as follows:

  • PROPAGATED_BITWISE_ANDCompare the values from one feature to the next.
  • PROPAGATED_MINGet the minimum value.
  • PROPAGATED_MAXGet the maximum value.

The propagators operator value 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

Note:

This parameter is only available via Python.

Value Table
output_assettypes
[output_assettypes,...]
(Optional)

Filters the output asset types to be included in the results—for example, only return overhead transformers.

String
output_conditions
[[Name, Operator, Type, Value, Combine Using],...]
(Optional)

Specifies the types of features that will be returned based on a network attribute or category. For example, in a trace configured to filter out everything but Tap features, any traced features that do not have the Tap category assigned to them are not included in the results. Any traced features that do are returned in the result selection set. If you're 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 that is specified in the name parameter.
  • 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.

The output conditions operator value 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation where all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation where not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation where at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation where none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The output conditions Type value options are as follows:

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

The output conditions Combine Using value options are as follows:

  • ANDCombine the conditions.
  • ORUse if either condition is met.

Learn more about using multiple conditional expressions

Value Table
include_isolated_features
(Optional)

Specifies whether the isolated features will be included in the trace results. This parameter is only used when running an isolation trace.

  • INCLUDE_ISOLATED_FEATURESIsolated features will be included in the trace results.
  • EXCLUDE_ISOLATED_FEATURESIsolated features will not be included in the trace results. This is the default.
Note:

The isolation trace type requires ArcGIS Enterprise 10.7 or later when using an enterprise geodatabase.

Boolean
ignore_barriers_at_starting_points
(Optional)

Specifies whether dynamic barriers in the trace configuration are ignored for starting points. This may be useful when performing an upstream protective device trace and using the discovered protective devices (barriers) as starting points to find subsequent upstream protective devices.

  • 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
include_up_to_first_spatial_container
(Optional)

Specifies whether to limit the containers returned to only those encountered up to, and including, the first spatial container for each network element in the trace results. If no spatial containers are encountered but nonspatial containers are present for a given network element, all nonspatial containers will be included in the results. This parameter is only applicable when Include Containers is enabled.

  • INCLUDE_UP_TO_FIRST_SPATIAL_CONTAINEROnly containers encountered up to, and including, the first spatial container will be included in the results when nested containment associations are encountered along the trace path. If no spatial containers exist, all nonspatial containers will be included in the results for a given network element.
  • DO_NOT_INCLUDE_UP_TO_FIRST_SPATIAL_CONTAINERAll containers will be returned in the results. This is the default.
Boolean
result_types
[result_types,...]
(Optional)

Specifies the type of results returned by the trace.

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

Specifies how the selection will be applied and what to do if a selection already exists.

  • NEW_SELECTIONThe resulting selection replaces the current selection. This is the default.
  • ADD_TO_SELECTIONThe resulting selection is added to the current selection if one exists. If no selection exists, this is the same as the new selection option.
  • REMOVE_FROM_SELECTIONThe resulting selection is removed from the current selection. If no selection exists, this option has no effect.
  • SUBSET_SELECTIONThe resulting selection is combined with the current selection. Only records that are common to both remain selected.
  • SWITCH_SELECTIONThe resulting selection is switched. Results that were selected are removed from the current selection, while results that were not selected are added to the current selection. If no selection exists, this is the same as the new selection option.
String
clear_all_previous_trace_results
(Optional)

Specifies whether content will be truncated from, or appended to, the feature classes chosen to store aggregated geometry. This parameter is only applicable to the aggregated geometry result type.

  • CLEAR_ALL_PREVIOUS_TRACE_RESULTS The feature classes storing aggregated trace geometry will be truncated. Only the output geometry from the current trace operation will be written. This is the default.
  • DO_NOT_CLEAR_ALL_PREVIOUS_TRACE_RESULTSThe output geometry from the current trace operation will be appended to the feature classes storing aggregated geometry.
Boolean
trace_name
(Optional)

The name of the trace operation. This value is stored in the TRACENAME field of the output feature class to assist with identification of the trace results. This parameter is only applicable to the aggregated geometry result type.

String
aggregated_points
(Optional)

An output multipoint feature class containing the aggregated result geometry. By default, the parameter is populated with a system-generated feature class named Trace_Results_Aggregated_Points that will be stored in the project's default geodatabase.

This feature class will be created automatically if it does not exist. An existing feature class can also be used to store aggregated geometry. If a feature class other than the default is used, it must be a multipoint feature class and contain a string field named TRACENAME. This parameter is only applicable for the aggregated geometry result type.

Feature Class
aggregated_lines
(Optional)

An output polyline feature class containing the aggregated result geometry. By default, the parameter is populated with a system-generated feature class named Trace_Results_Aggregated_Lines that will be stored in the project's default geodatabase.

This feature class will be created automatically if it does not exist. An existing feature class can also be used to store aggregated geometry. If a feature class other than the default is used, it must be a polyline feature class and contain a string field named TRACENAME. This parameter is only applicable for the aggregated geometry result type.

Feature Class
aggregated_polygons
(Optional)

An output polygon feature class containing the aggregated result geometry. By default, the parameter is populated with a system-generated feature class named Trace_Results_Aggregated_Polygons that will be stored in the project's default geodatabase.

This feature class will be created automatically if it does not exist. An existing feature class can also be used to store aggregated geometry. If a feature class other than the default is used, it must be a polygon feature class and contain a string field named TRACENAME. This parameter is only applicable for the aggregated geometry result type.

Feature Class
allow_indeterminate_flow
(Optional)

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

  • TRACE_INDETERMINATE_FLOWFeatures with indeterminate flow will be traced. This is the default.
  • IGNORE_INDETERMINATE_FLOWFeatures with indeterminate flow will stop traversability and will not be traced.
Note:

This parameter requires Utility Network Version 5 or later.

Boolean
validate_locatability
(Optional)

Specifies whether an error will be returned during a trace if nonspatial junction or edge objects are encountered without the necessary containment, attachment, or connectivity association in their association hierarchy of the traversed objects. This parameter ensures that nonspatial objects returned by a trace or update subnetwork operation can be located through an association with features or other locatable objects.

  • VALIDATE_LOCATABILITYThe trace will return an error if nonspatial junction or edge objects are encountered without the necessary containment, attachment, or connectivity association in their association hierarchy of the traversed objects.
  • DO_NOT_VALIDATE_LOCATABILITYThe trace will not check for unlocatable objects and will return results regardless of whether unlocatable objects are present in the association hierarchy of the traversed objects. This is the default.
Note:

This parameter requires Utility Network Version 4 or later.

Boolean
use_trace_config
(Optional)

Specifies whether an existing trace configuration will be used to populate the parameters of the Trace tool.

  • USE_TRACE_CONFIGURATIONThe trace will use an existing trace configuration to define the properties of the trace. All parameters except trace_config_name, starting_points, and barriers are ignored.
  • DO_NOT_USE_TRACE_CONFIGURATIONThe trace will not use a trace configuration to define the properties of the trace. This is the default.
Note:

This parameter requires Utility Network Version 5 or later.

Boolean
trace_config_name
(Optional)

Specifies the name of the trace configuration that will be used to define the properties of the trace. This parameter is only enabled when the use_trace_config parameter is set to USE_TRACE_CONFIGURATION.

String

Derived Output

NameExplanationData Type
out_utility_network

The updated utility network.

Utility Network

Code sample

Trace example (stand-alone script)

Run a downstream trace on an electric distribution network on the medium-voltage tier that adds up the transformer load on phases A, B, and C.

'''****************************************************************************
Name:        DownstreamTrace.py
Description: This script executes a downstream trace on the Medium Voltage tier 
             that adds up the transformer load on phases A, B, and C.
Created by:  Esri
****************************************************************************'''

# Import required modules        
import arcpy

# Set local variables
in_utility_network = "NapervilleElectric Utility Network"
trace_type = "DOWNSTREAM"
starting_points = "C:\\MyProject\\Bissell.gdb\UN_Temp_Starting_Points"
barriers = "C:\\MyProject\\Bissell.gdb\UN_Temp_Barriers"
domain_network = "ElectricDistribution"
tier = "Medium Voltage Radial"
include_containers = "INCLUDE_CONTAINERS"
include_structures = "INCLUDE_STRUCTURES"
condition_barriers = "'Device Status' IS_EQUAL_TO SPECIFIC_VALUE 1 #"
functions = "ADD 'Transformer Load' 'Phases Normal' INCLUDES_THE_VALUES SPECIFIC_VALUE 4;ADD 'Transformer Load' 'Phases Normal' INCLUDES_THE_VALUES SPECIFIC_VALUE 2;ADD 'Transformer Load' 'Phases Normal' INCLUDES_THE_VALUES SPECIFIC_VALUE 1"

# Run Trace with specified parameters and leave the rest default
arcpy.Trace_un(in_utility_network, 
               trace_type, 
               starting_points, 
               barriers, 
               domain_network, 
               tier,
               include_containers=include_containers,
               include_structures=include_structures,
               condition_barriers=condition_barriers,
               functions=functions)

Environments

This tool does not use any geoprocessing environments.

Licensing information

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

Related topics