Trace (Trace Network)

Summary

Returns selected features in a trace network based on connectivity or traversability from the specified starting points.

The trace capabilities of the trace network allow you to analyze paths in your network. Traversability refers to paths established by connected features that also meet configuration requirements.

By default, trace results are returned as a selection and include the entire line feature. To return partial feature results, set the Result Types parameter to Aggregate Geometry. When a starting point or barrier is placed on a junction with midspan connectivity, trace results will return partial elements of the edge feature. When a barrier is placed along an edge, trace results can be stopped at the nearest junction with midspan connectivity. 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 a trace network

Usage

  • The network topology must be enabled.

  • When working with an enterprise geodatabase, an input trace network must be from a feature service; a trace network from a database connection is not supported.

  • Because the Trace tool relies on the network topology, the trace results are not guaranteed to be accurate if dirty areas exist in the trace extent. The network topology for the area to be traced must be validated to reflect the most recent edits or updates to the network.

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

Parameters

LabelExplanationData Type
Input Trace Network

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

Trace Network; Trace Network Layer
Trace Type

Specifies the type of trace to execute.

  • Connected—A connected trace that begins at one or more starting points and spans outward along connected features will be used.
  • Upstream—An upstream trace that discovers features upstream from a location in the network will be used. This type of trace requires the flow direction to be set.
  • Downstream—A downstream trace that discovers features downstream from a location in the network will be used. This type of trace requires the flow direction to be set.
  • Shortest path—A 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.

  • 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 requires the flow direction to be set.
  • DownstreamA downstream trace that discovers features downstream from a location in the network will be used. This type of trace requires the flow direction to be set.
  • 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
Starting Points

A feature layer created using the Starting Points tab in the Trace Locations pane, or a table or feature class containing one or more records that represent the starting points of the trace. The TN_Temp_Starting_Points feature class is used by default and is generated in the default geodatabase of the project when you create starting points using the Starting Points tool in the Trace Locations pane.

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. The TN_Temp_Barriers feature class is used by default and is generated in the default geodatabase of the project when you create barriers using the Barriers tab in the Trace Locations pane.

Feature Layer; Table View
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.
  • Upstream pathThe upstream path between the two starting points will be used.
  • Downstream pathThe 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 Barrier Features
(Optional)

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

  • Checked—Traversability barrier features will be included in the trace results. This is the default.
  • Unchecked—Traversability 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.

  • Checked—The trace will return an error if dirty areas are encountered in any of the traversed features. This is the default.
  • Unchecked—The 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.

  • Checked—Barriers at starting points will be ignored in the trace.
  • Unchecked—Barriers at starting points will not be ignored in the trace. This is the default.

Boolean
Allow Indeterminate Flow
(Optional)

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

  • Checked—Features with indeterminate or uninitialized flow direction will be traced.
  • Unchecked—Features with indeterminate or uninitialized flow direction will not be traced. This is the default.

Boolean
Condition Barriers
(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 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 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 to—The attribute is equal to the value.
  • Does not equal—The attribute is not equal to the value.
  • Is greater than—The attribute is greater than the value.
  • Is greater than or equal to—The attribute is greater than or equal to the value.
  • Is less than—The attribute is less than the value.
  • Is less than or equal to—The attribute is less than or equal to the value.

Type components are as follows:

  • Specific Value—Filter by a specific value.
  • Network Attribute—Filter by a network attribute.

Combine using components are as follows:

  • And—Combine the condition barriers.
  • Or—Use if either condition barrier is met.

  • 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.
  • Specific valueFilter by a specific value.
  • Network attributeFilter by a network attribute.
  • AndCombine the condition barriers.
  • OrUse if either condition barrier is met.
Value Table
Function Barriers
(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:

  • Minimum—The minimum of the input values.
  • Maximum—The maximum of the input values.
  • Add—The sum of the input values.
  • Average—The average of the input values.
  • Count—The number of features.
  • Subtract—The difference between the input values.

For example, you have a starting point feature with a value of 20. The next feature has a value of 30. If you use the minimum function, the result is 20, maximum is 30, add is 50, average is 25, count is 2, and subtract is -10.

Operator components are as follows:

  • Is equal to—The attribute is equal to the value.
  • Does not equal—The attribute is not equal to the value.
  • Is greater than—The attribute is greater than the value.
  • Is greater than or equal to—The attribute is greater than or equal to the value.
  • Is less than—The attribute is less than the value.
  • Is less than or equal to—The attribute is less than or equal to the value.

Use Local Values components are as follows:

  • Checked—Local values will be used.
  • Unchecked—Global values will be used. This is the default.

  • 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.
  • 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.
Value Table
Apply Traversability To
(Optional)

Specifies the type of traversability that will be applied. Traversability scope determines whether traversability is applied to junctions, edges, or both. For example, in a network of recreational trails, if a condition barrier is defined to stop a trace if a surfacetype attribute contains a value of gravel and the traversability scope is set to junctions only, the trace will not stop even if it encounters an edge feature with this value in the surfacetype field, because the surfacetype attribute is only applicable to edges.

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

The calculation function or functions 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:

  • Min—The minimum of the input values.
  • Max—The maximum of the input values.
  • Add—The sum of the input values.
  • Average—The average of the input values.
  • Count—The number of features.
  • Subtract—The difference between the input values.

For example, you have a starting point feature with a value of 20. The next feature has a value of 30. If you're 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 to—The attribute is equal to the value.
  • Does not equal—The attribute is not equal to the value.
  • Is greater than—The attribute is greater than the value.
  • Is greater than or equal to—The attribute is greater than or equal to the value.
  • Is less than—The attribute is less than the value.
  • Is less than or equal to—The attribute is less than or equal to the value.

Filter Type component options are as follows:

  • Specific Value—Filter by a specific value.
  • Network Attribute—Filter by a network attribute

  • 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.
  • 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.
Value Table
Output Conditions
(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.

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 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 component options are as follows:

  • Is equal to—The attribute is equal to the value.
  • Does not equal—The attribute is not equal to the value.
  • Is greater than—The attribute is greater than the value.
  • Is greater than or equal to—The attribute is greater than or equal to the value.
  • Is less than—The attribute is less than the value.
  • Is less than or equal to—The attribute is less than or equal to the value.

Type component options are as follows:

  • Specific Value—Filter by a specific value.
  • Network Attribute—Filter by a network attribute.

  • 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.
Value Table
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 in the active map.
  • Network LayersThe trace results will be added to feature layers as a selection set in a group layer.
  • ConnectivityThe trace results will be returned as a connectivity graph in a specified output .json file. This option enables the Output JSON parameter.
  • ElementsThe trace results will be returned as feature-based information in a specified output .json file. This option enables the Output JSON parameter.
String
Selection Type

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

  • New selectionThe resulting selection will replace the current selection. This is the default.
  • Add to the current selectionThe resulting selection will be added to the current selection if one exists. If no selection exists, this is the same as the new selection option.
  • Remove from the current selectionThe resulting selection will be removed from the current selection. If no selection exists, this option has no effect.
  • Select subset from the current selectionThe resulting selection will be combined with the current selection. Only records that are common to both remain selected.
  • Switch the current selectionThe resulting selection will be 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.

  • Checked—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.
  • Unchecked—The 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 to 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 to the aggregated geometry result type.

Feature Class
Output Group Layer Name
(Optional)

The name of the output group layer that contains feature layers with selection sets of features returned by the trace. The layer provides access to work with the output of a trace in ModelBuilder and Python.

This parameter is only applicable to the network layers result type.

Group Layer
Use Trace Configuration
(Optional)

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

  • Checked—An existing named trace configuration will be used to define the properties of the trace. All parameters except Trace Configuration Name, Starting Points, and Barriers will be ignored.
  • Unchecked—An existing named trace configuration will not be used to define the properties of the trace. This is the default.

Note:

This parameter requires Trace Network Version 2 or later.

Boolean
Trace Configuration Name
(Optional)

The name of the trace configuration that will be used to define the properties of the trace. This parameter is only active when the Use Trace Configuration parameter is checked.

Note:

This parameter requires Trace Network Version 2 or later.

String
Output JSON
(Optional)

The name and location of the .json file that will be generated.

File

Derived Output

LabelExplanationData Type
Updated Trace Network

The updated trace network.

Any Value

arcpy.tn.Trace(in_trace_network, trace_type, starting_points, {barriers}, {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}, selection_type, {clear_all_previous_trace_results}, {trace_name}, {aggregated_points}, {aggregated_lines}, {out_network_layer}, {use_trace_config}, {trace_config_name}, {out_json_file})
NameExplanationData Type
in_trace_network

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

Trace Network; Trace Network Layer
trace_type

Species the type of trace to execute.

  • 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 requires the flow direction to be set.
  • DOWNSTREAMA downstream trace that discovers features downstream from a location in the network will be used. This type of trace requires the flow direction to be set.
  • 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
starting_points

A feature layer created using the Starting Points tab in the Trace Locations pane, or a table or feature class containing one or more records that represent the starting points of the trace. The TN_Temp_Starting_Points feature class is used by default and is generated in the default geodatabase of the project when you create starting points using the Starting Points tool in the Trace Locations pane.

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. The TN_Temp_Barriers feature class is used by default and is generated in the default geodatabase of the project when you create barriers using the Barriers tab in the Trace Locations pane.

Feature Layer; Table View
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 with indeterminate or uninitialized flow will be traced. This parameter is only honored when running an upstream or downstream trace.

  • TRACE_INDETERMINATE_FLOWFeatures with indeterminate or uninitialized flow direction will be traced.
  • IGNORE_INDETERMINATE_FLOWFeatures with 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 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to 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 the type of traversability that will be applied. Traversability scope determines whether traversability is 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.

  • 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 or functions 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, you have a starting point feature with 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to 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_THAN_OR_EQUAL_TOThe attribute is less than or equal to 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 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 in the active map.
  • NETWORK_LAYERSThe trace results will be added to feature layers as a selection set in a group layer.
  • CONNECTIVITYThe trace results will be returned as a connectivity graph in a specified output .json file. This option enables the out_json_file parameter.
  • ELEMENTSThe trace results will be returned as feature elements in a specified output .json file. This option enables the out_json_file parameter.
String
selection_type

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

  • NEW_SELECTIONThe resulting selection will replace the current selection. This is the default.
  • ADD_TO_SELECTIONThe resulting selection will be 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 will be removed from the current selection. If no selection exists, this option has no effect.
  • SUBSET_SELECTIONThe resulting selection will be combined with the current selection. Only records that are common to both remain selected.
  • SWITCH_SELECTIONThe resulting selection will be 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 to 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 to the aggregated geometry result type.

Feature Class
out_network_layer
(Optional)

The name of the output group layer that contains feature layers with selection sets of features returned by the trace. The layer provides access to work with the output of a trace in ModelBuilder and Python.

This parameter is only applicable to the network layers result type.

Group Layer
use_trace_config
(Optional)

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

  • USE_TRACE_CONFIGURATIONAn existing named trace configuration will be used to define the properties of the trace. All parameters except trace_config_name, starting_points, and barriers will be ignored.
  • DO_NOT_USE_TRACE_CONFIGURATIONAn exiting named trace configuration will not be used to define the properties of the trace. This is the default.
Note:

This parameter requires Trace Network Version 2 or later.

Boolean
trace_config_name
(Optional)

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.

Note:

This parameter requires Trace Network Version 2 or later.

String
out_json_file
(Optional)

The name and location of the .json file that will be generated.

File

Derived Output

NameExplanationData Type
updated_trace_network

The updated trace network.

Any Value

Code sample

Trace example (Python window)

Run a downstream trace on a trace network named HydroNetwork using the Trace function.

import arcpy
arcpy.Trace_tn(r"C:\MyProject\NHD.gdb\Hydro\HydroNetwork", 
               "DOWNSTREAM", r"C:\MyProject\NHD.gdb\TN_Temp_Starting_Points")

Environments

This tool does not use any geoprocessing environments.

Licensing information

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

Related topics