Trace a stream network

You're a hydrologist working at a government agency. You get a call that someone noticed discolored water entering a storm drain in their neighborhood. You want to discern where the pollution may have originated and what downstream locations may be affected.

In this tutorial, you'll learn how to use trace analysis on a stream network to look both upstream and downstream from a specified location, with and without barriers. In particular, you'll trace streams flowing within the Ashokan Reservoir watershed, which is one of the reservoirs that serve as the water supply for New York City.

This tutorial was last tested on February 2, 2024 using ArcGIS Pro 3.2. If you're using a different version of ArcGIS Pro, you may encounter different functionality and results.

Requirements

• ArcGIS Pro (see options for software access)

Create a trace network

To determine the potential upstream and downstream impacts of a pollution event in the Ashokan Reservoir, you first need to create a trace network. A trace network is a dataset of streams with information about which way each stream is flowing (also known as directionality).

Create a project

First, you'll download the data for this tutorial and add it to a new project in ArcGIS Pro.

1. Download the Ashokan_Data zipped folder.
2. Locate the downloaded folder on your computer.

   Note:

   Depending on your web browser, you may have been prompted to choose the file's location before you began the download. Most browsers download to your computer's Downloads folder by default.

3. Right-click the folder and choose Extract All. For Select a Destination and Extract Files, click the Browse button.
4. Browse to a folder to store the tutorial data, such as the Documents folder, click Select Folder and click Extract.

   The extracted folder contains a geodatabase with several feature classes you can use in ArcGIS Pro.

5. Start ArcGIS Pro. If prompted, sign in using your licensed ArcGIS organizational account.

   Note:

   If you don't have access to ArcGIS Pro or an ArcGIS organizational account, see options for software access.

6. Under New Project, click Map.

   

7. In the Create a New Project window, for Name, type Ashokan_Trace. Click OK.

   A project is created with a default map. You'll add a folder connection to the geodatabase you downloaded so you can quickly access its data.

8. In the Catalog pane, right-click Databases and choose Add Database.

   

9. In the Select Existing Geodatabase window, browse to and select the Ashokan_Data.gdb geodatabase you extracted. Click OK.

   The geodatabase is added to the Catalog pane.

Map the data

Next, you'll add the Ashokan Reservoir data to the map and familiarize yourself with it.

1. In the Catalog pane, expand Databases and expand Ashokan_Data.gdb.

   The geodatabase contains three feature classes: Ashokan_Streams, Permitted_Discharger_Origin, and Storm_Drain_Origin. The streams data is from the United States Geological Survey (USGS), while the other two feature classes were created for this tutorial to represent pollution points of origin.

2. Right-click Ashokan_Streams and choose Add To Current Map.

   

   The streams network is added to the map. (Your streams may have different default symbology than the example image.)

   

   The streams are located around a large reservoir. You'll look at the data's attributes to learn more.

3. In the Contents pane, right-click Ashokan Streams and choose Attribute Table.

   

   The table appears. It contains a large number of attributes. There is one attribute of particular importance to trace analysis: Flow Direction.

   

   This attribute indicates the directionality of each stream segment. In this dataset, every stream segment has a flow direction of 1. In this dataset, a 1 means the flow direction is the same as the direction in which the feature was originally digitized. (Water flows from the first vertex in the line toward the last vertex in the line.)

   Note:

   When using or creating your own streams dataset for a trace network, you must ensure that all stream segments are correctly digitized so that they flow together in the same direction. This tutorial won't cover the process for adding flow direction to a streams dataset. To learn more, read the topic Flow direction in a trace network.

4. Close the table.
5. From the Catalog pane, add the Storm_Drain_Origin and Permitted_Discharger_Origin datasets to the map.

   The Storm_Drain_Origin layer is the location where the pollution was spotted. The Permitted_Discharger_Origin layer is a possible source of the pollution. Both locations are on the northern end of the reservoir.

   

Create a trace network

In GIS, a network is typically a group of line features with special properties. For instance, a network dataset contains line features that represent streets with specific properties (such as speed limits, ability to make U-turns, and so on) and is necessary for analysis that determines the best or fastest route to a location. A utility network contains line features that represent pipes, electric lines, and other infrastructure owned by utility companies.

Streams and other linear objects with directionality (such as railroads) are best represented by a trace network. In this type of network, line features contain information about the direction they move.

Your streams dataset contains an attribute field named Flow Direction that indicates the directionality of each stream feature. You'll use this field to create a trace network, which you can later use to trace locations upstream and downstream from the site of observed pollution.

First, you'll create an empty feature dataset to contain the stream data and trace network. Using a feature dataset ensures that all of the feature classes share a common coordinate system and helps facilitate the creation of the trace network.

1. In the Catalog pane, right-click Ashokan_Trace.gdb, point to New, and choose Feature Dataset.

   

   The Geoprocessing pane appears, showing the Create Feature Dataset tool.

2. For Feature Dataset Name, type Ashokan_Streams_Dataset. For Coordinate System, choose Current Map.

   When you choose Current Map, the map's coordinate system (NAD 1983 StatePlane New York East FIPS 3101) is chosen.

   

3. Click Run.

   The tool runs successfully. The empty feature dataset is created and added to the output geodatabase. You'll move the streams data into this dataset.

4. At the bottom of the Geoprocessing pane, click the Catalog tab.

   

   You return to the Catalog pane.

5. Under Databases, expand Ashokan_Trace.gdb. Right-click Ashokan_Streams_Dataset, point to Import, and choose Feature Class(es).

   

   Tip:

   If you don't see Ashokan_Streams_Dataset, right-click Ashokan_Trace.gdb and choose Refresh.

   The Feature Class To Geodatabase geoprocessing tool opens.

6. For Input Features, choose Ashokan Streams. For Output Geodatabase, confirm that Ashokan_Streams_Dataset is chosen.

   

7. Click Run.

   The tool runs and your streams data is copied to the feature dataset. Now, you're ready to convert the streams into a trace network. To do so, you'll search for the proper geoprocessing tool.

8. In the Geoprocessing pane, click the Back button.

   

9. In the Find Tools search bar, type Create Trace Network. In the list of search results, choose Create Trace Network (Trace Network Tools).

   

10. In the Create Trace Network tool, for Input Feature Dataset, click the Browse button.

    

11. In the Input Feature Dataset window, browse to Ashokan_Trace.gdb and double-click Ashokan_Streams_Dataset.

    For the rest of the parameters, you only need to give your trace network a name and choose the input edges (the streams data). You'll also choose the connectivity policy, which defines whether resources flow from one end of the stream to the other (simple edge) or are siphoned off along the length of the stream (complex edge). For this tutorial, you'll assume streams flow from one end to the other without being siphoned.

12. For Trace Network Name, type Hydro. For Input Edges, for Class Name, choose Ashokan_Streams. Confirm that Connectivity Policy is set to Simple edge.

    

13. Click Run.

    The tool runs and the Hydro Trace Network and Ashokan_Streams layers are added to the map. Before you continue, you'll remove the original streams data you added earlier in the tutorial.

14. In the Contents pane, right-click the original Ashokan Streams layer (the one without an underscore) and choose Remove.

Enable network topology

When you created the trace network, a translucent purple polygon was added to the map, covering the entirety of the map extent. This polygon is the Dirty Areas layer that is included in the trace network. It represents errors in the network topology, which maintains connectivity between features. Currently, the layer covers the entire map because network topology has not been correctly enabled for your trace network.

Before you enable network topology, you'll create and configure a network attribute. A network attribute is an attribute in your original streams feature class that has been configured for trace analysis. Network attributes contain topological information that can be essential for network topology.

In your case, you'll configure a network attribute that includes the length of each stream, based on the Length (KM) attribute in the original data. Unless this attribute is specifically set up as a network attribute, it won't be available for calculating stream length.

1. In the Geoprocessing pane, click the Back button. Search for and open Add Network Attribute (Trace Network Tools).

   This tool creates an empty network attribute. The attribute must have the same type as the original attribute, as well as the same nullable setting (which determines whether null values can be used). In your case, the Length (KM) attribute has the Double type and is nullable.

   Tip:

   To check the type and nullable setting of a field, open the attribute table for the field's layer. On the ribbon, click Fields to open the Fields view. This view lists the settings for all attributes in a layer.

2. For the Add Network Attribute tool, set the following parameters:
   • For Input Trace Network, choose Hydro Trace Network.
   • For Attribute Name, type Length_KM.
   • For Attribute Type, choose Double (64-bit floating point).
   • Check Nullable.

   

3. Click Run.

   The tool runs and the empty network attribute is created. Next, you'll set the network attribute to use an existing attribute in the original Ashokan Streams feature class.

4. Click the Back button. Search for and open Set Network Attribute (Trace Network Tools).
5. Set the following parameters:
   • For Input Trace Network, choose Hydro Trace Network.
   • For Network Attribute, choose Length_KM.
   • For Feature Class, choose Ashokan_Streams.
   • For Field, choose lengthkm.

   

6. Click Run.

   The tool runs and the network attribute is set. Now that you have a network attribute containing important topological information, you'll enable network topology for your trace network. Network topology is essential for running trace analysis and creating network diagrams.

7. Click the Back button. Search for and open Enable Network Topology (Trace Network Tools).

   This tool requires only a single input parameter. If your trace network has been created correctly, the tool will run successfully.

8. For Input Trace Network, choose Hydro Trace Network.

   

9. Click Run.

   The large translucent polygon covering the entire map disappears, replaced by points at the ends of each stream feature. Due to setting the length of each stream and enabling network topology, the trace network now correctly identifies where each stream begins and ends.

   

10. On the Quick Access Toolbar, click the Save button to save the project.

    

You've successfully downloaded the data for the tutorial, mapped it in ArcGIS Pro, and created a trace network with accurate network topology. Next, you'll use your trace network to trace upstream and downstream from observed pollution.

Perform trace analysis

Your configured trace network is ready for analysis. You now want to know what areas are upstream and downstream from the location where pollution was spotted. An upstream trace will help you understand where the pollution may have originated, while a downstream trace will help you understand where the pollution may go.

Select a starting point

First, you'll select a starting point in the trace network that represents the storm drain where pollution was spotted and where you want your trace analysis to begin. You already have a layer that represents this point, so you can use it for reference.

1. In the Contents pane, uncheck Hydro Trace Network to turn it off.

   The network is hidden, making it easier to see the storm drain point.

2. On the map, zoom to the Storm Drain Origin point.

   

   The point itself is not part of the trace network, as it is from a different layer than your streams data. You'll add a new point to the trace network based on the location.

3. On the ribbon, click the Trace Network tab.

   

   This tab was added to the ribbon when you created your trace network.

4. In the Tools group, click the Trace drop-down menu and choose Starting Points.

   

   The Trace pane appears. By default, Add features is selected, allowing you to create a point on the network.

5. On the map, click the trace network near the location of the Storm Drain Origin point, which is located just north of Boulevard Road.

   Note:

   If you attempt to click the trace network at the exact location of the point, you may not be able to create a point because you are clicking the Storm Drain Origin feature instead of the trace network. In this example, it's OK to add the point slightly off from the origin point, as the trace uses the entire stream segment where the point is located as its starting point.

   

   A green point is added at the location you clicked. In the Trace pane, a new starting point called Ashokan_Streams is added. The number 98 refers to the ID of the stream segment where the point is located. (Depending on where you clicked, you may see a different number.)

Perform an upstream trace

Next, you'll perform an upstream trace from the starting point you chose.

1. On the ribbon, on the Trace Network tab, in the Tools group, click Upstream.

   

   The Geoprocessing pane appears, showing the Trace tool. Several parameters have been set by default.

2. Confirm that the following parameters are chosen:
   • For Input Trace Network, confirm that Hydro Trace Network is chosen.
   • For Trace Type, confirm that Upstream is chosen.
   • For Starting Points, confirm that TN_Temp_Starting_Points is chosen.
   • For Barriers, confirm that TN_Temp_Barriers is chosen.
   • Confirm that Include Barrier Features and Validate Consistency are checked.

   

   These settings will use your trace network and the starting point you created to perform an upstream trace. Your trace network has no barriers currently, so it doesn't matter if you include barrier features or not.

   The Validate Consistency option ensures that trace results are consistent with network topology. When this option is checked, the tool will fail if any dirty areas intersect the trace path. Because you properly enabled network topology earlier, you shouldn't receive any errors.

3. Click Run.

   Note:

   If you receive an error message, the issue might be due to improper topology. You can try unchecking Validate Consistency and running the tool again; doing so will allow the trace to run through dirty areas caused by errors in the data. Improperly set flow direction won't display an error, but may stop the trace or display unexpected results.

   The tool runs and the trace is completed. Areas that are upstream of the starting point are highlighted on the map. These are the areas where pollution may have originated.

   

   The entire stream segment where your starting point was located is selected, even though your starting point was not at the beginning of the segment. This result is expected, as only an entire feature can be selected, not part of one.

   These results are only a temporary selection on your data, which is useful for running trace analysis quickly. However, it would also be useful to save the trace analysis results as a new feature class so you can compare the results of this analysis to other results. You'll run the analysis again, this time changing parameters to save the results.

4. On the ribbon, click the Edit tab. In the Selection group, click Clear.

   

   The selection is cleared.

5. In the Geoprocessing pane, expand Advanced Options.

   

   This section contains more options for trace analysis, including options for the results. You'll save the aggregated geometry, which will store the results as a multipart feature class for each type of geometry (points, lines, and polygon).

6. Scroll to the bottom of the section. For Result Types, choose Aggregated Geometry.

   You'll turn off the option to clear previous trace results, which will enable the creation of multiple records from different trace analysis operations for purposes of comparison.

7. Uncheck Clear All Previous Trace Results.
8. For Trace Name, type Trace_Interactive.

   

9. Click Run.

   The tool runs. Two layers, Trace_Results_Aggregated_Points and Trace_Results_Aggregated_Lines, are created and added to the map. The points layer shows the endpoints of each stream segment, while the lines show the segments themselves.

   

   Unlike when you only selected upstream segments, the new feature class does not include the entire stream segment where the starting point was located, but only parts that are upstream. While you can't select part of an existing feature, you can create a feature that only contains part of an existing one.

   You've performed an upstream trace. Before you continue, you'll clear the starting point you created.

10. At the bottom of the Geoprocessing pane, click the Trace tab.
11. In the Trace pane, click Clear All.

    

    The starting point is cleared, removing it from the pane and the map.

    Tip:

    Alternatively, you can clear starting points by clicking the Trace Network tab on the ribbon, clicking the Trace Locations drop-down menu, and choosing Clear All.

12. Save the project.

Snap points to the trace network

When you ran the trace analysis, you used an approximation of the origin point that you interactively added to the map. While this approximation was useful for quickly running the analysis, what if you wanted more accuracy? You can run trace analysis by using a point from another feature class that is not included in the network. However, the point needs to be located on the network exactly. Being close isn't enough, and even the smallest differences in feature geometry can lead to unexpected results.

Next, you'll snap the Storm Drain Origin and Permitted Discharger Origin layers to the trace network. Snapping ensures that one feature is exactly aligned with another, making it usable in analysis requiring exact topology.

First, you'll copy the feature classes to a new feature class so the changes made to the feature geometry during snapping won't affect your original data. It's always a good idea to make a copy of a layer before modifying its geometry.

1. In the Geoprocessing pane, click the Back button. Search for Copy Features and open Copy Features (Data Management Tools).
2. For Input Features, choose Storm Drain Origin. For Output Feature Class, type Storm_Drain_Snap.

   

3. Click Run.

   The feature class is copied and the copy is added to the map. Next, you'll snap it to the streams data.

4. In the Geoprocessing pane, click the Back button. Search for Snap and choose Snap (Editing Tools).

   You'll snap the storm drain point to the nearest vertex in the streams data within a maximum distance of 50 meters.

5. Set the following parameters:
   • For Input Features, choose Storm_Drain_Snap.
   • Under Snap Environment, for Features, choose Ashokan_Streams.
   • For Type, choose Vertex.
   • For Distance, type 50 and choose Meters.

   

6. Click Run.

   The storm drain point is now snapped to a vertex on the stream feature.

   You'll repeat the process of copying and snapping for the Permitted Discharger Origin point. This point represents a possible source of the pollution. In subsequent trace analysis, you'll use it as a barrier, so it needs to be snapped to the streams network as well.

7. In the Geoprocessing pane, click the Back button. Search for and open the Copy Features tool.
8. For Input Features, choose Permitted Discharger Origin. For Output Feature Class, type Permitted_Discharger_Snap.
9. Click Run.

   The point is copied.

10. In the Geoprocessing pane, click the Back button. Search for and open the Snap tool.
11. Set the following parameters:
    • For Input Features, choose Permitted_Discharger_Snap.
    • Under Snap Environment, for Features, choose Ashokan_Streams.
    • For Type, choose Vertex.
    • For Distance, type 50 and choose Meters.
12. Click Run.

    Both points are now snapped to the trace network and ready for analysis. You no longer need the original point layers, so you can remove them from the project.

13. In the Contents pane, right-click Storm Drain Origin and choose Remove. Remove the Permitted Discharger Origin layer too.

Perform a trace with a barrier

You'll run the upstream trace analysis again, this time using the snapped storm drain point as the starting point instead of a starting point you chose interactively, like in your first analysis. Using the snapped point will provide more precise results.

You'll also run the analysis using the snapped permitted discharger layer as a barrier. A barrier indicates an ending point where trace analysis stops. In this example, if you assume the permitted discharger is the source of the pollution, you may want to trace the areas between the source and where the pollution was spotted so that you know which areas are already polluted.

1. On the ribbon, click the Trace Network tab. In the Tools group, click Upstream.

   The Trace tool appears. You'll set the parameters similarly to your previous analysis, but use the snapped points as the starting point and barrier.

2. Set the following parameters:
   • For Input Trace Network, confirm that Hydro Trace Network is chosen.
   • For Trace Type, confirm that Upstream is chosen.
   • For Starting Points, choose Storm_Drain_Snap.
   • For Barriers, choose Permitted_Discharger_Snap.
3. Expand Advanced Options. For Result Types, choose Selection.

   Selection is the default option if no result type is chosen. When you ran your analysis for the first time without setting advanced options, the result was a selection on the trace network. You'll add another result type to receive both a selection and a new feature class with aggregated geometry.

4. For Result Types, click the new drop-down menu under Selection and choose Aggregated Geometry.
5. Uncheck Clear All Previous Trace Results. For Trace Name, type Trace_with_Barrier.

   

   The Aggregated Points and Aggregated Lines parameters display a warning. These warnings inform you that the feature classes indicated by these parameters already exist. (You created them the last time you ran trace analysis.)

   In many other geoprocessing tools, using an output feature class that already exists overwrites the existing feature class. This tool, however, will only add a new feature to the existing feature class, allowing you to compare the results of multiple trace analyses using the attribute table. You'll ignore the warning.

6. Click Run.

   The analysis runs. A selection is added to the map, highlighting stream segments between the starting point and the barrier.

   

   As before, the selection encompasses entire stream segments, not only the parts of the segments that are upstream. This occurs because the selection is made on the original trace network, where it is impossible to select only part of a stream segment.

7. On the ribbon, click the Edit tab. In the Selection group, click Clear.

   When you clear the selection, the aggregated lines feature class appears to encompass the entire area downstream of the starting point, without accounting for the barrier you chose. However, this is because you added your results to the same feature class as your previous analysis. You can compare and visualize the results using the attribute table.

8. In the Contents pane, right-click Trace_Results_Aggregated_Lines and choose Attribute Table.

   The table contains two records: Trace_Interactive (your previous trace analysis result) and Trace_with_Barrier (your most recent result). The table also lists the length of each trace.

   

   Note:

   Your values may be slightly different.

9. For Trace_Interactive, click the 1 to the left of the record to select it.

   Selecting the record in the table also selects it on the map. The selection encompasses the area of your previous trace analysis, without a barrier.

10. For Trace_with_Barrier, click the 2 to the left of the record to select it.

    The selection on the map updates. Now, it shows the results of your trace analysis that includes the barrier. The upstream trace stops when it reaches the location of the permitted discharger points.

    

    Unlike the original selection, this selection only shows the upstream part of the initial stream segment. This occurs because you're looking at a selection of the aggregated points feature class instead of a selection made on the original trace network.

11. In the attribute table, click Clear to clear the selection.

    The Shape_Length field for each feature shows the length in meters of the stream segments included in each trace. The original trace has a length of about 6,378 meters, while the trace with a barrier has a length of about 4,777 meters.

    From these results, you can anticipate that 4,777 meters of stream are between the permitted discharge site and the location where pollution was observed. There are an additional 1,600 meters of stream upstream of the permitted discharge site. If the pollution does not, as you expect, originate from the permitted discharge site, that 1,600 meters would need to be investigated for another potential source.

12. Close the attribute table.

Perform a downstream trace

So far, you've focused your efforts upstream of the observed pollution site. Upstream analysis helps you identify the potential sources of pollution. Next, you'll focus on what areas downstream may be polluted.

Hydrologists assume that pollution is diluted with increased water volume. While volume changes depending on the width and deepness of a stream, for your purposes you'll use the summed length of the stream as a proxy for water volume. Essentially, this means that as pollution travels, increasing far downstream, it becomes more and more diluted. When performing your downstream trace, you'll use a function barrier to indicate this downstream dilution.

1. On the ribbon, click the Trace Network tab. In the Tools group, click Downstream.

   

   The Trace tool appears, this time with Trace Type set to Downstream.

2. Set the following parameters:
   • For Input Trace Network, confirm that Hydro Trace Network is chosen.
   • For Trace Type, confirm that Downstream is chosen.
   • For Starting Points, choose Storm_Drain_Snap.

   

   You'll leave the barrier parameter as its default and set a function barrier in the advanced options. A function barrier is based on a calculation instead of a fixed point feature. It defines the extent of a trace based on whether the specified function condition has been satisfied. Function barriers can be used to set a maximum value that when reached stops the trace.

   In this example, you'll specify a maximum value of 0.5 kilometers (or 500 meters) until the downstream trace is finished. This value is used in this example to approximate the length until the pollution has diluted to near normal levels given no additional sources of pollution entering the waterway. You can set this function barrier using the Length_KM field you previously created and added to the trace network to use in trace analysis.

3. Expand Advanced Options. Under Function Barriers, set the following parameters:
   • For Function, choose Add.
   • For Attribute, choose Length_KM.
   • For Operator, choose Is greater than or equal to.
   • For Value, type 0.5.
   • Confirm that Use Local Values is checked.

   

   For this downstream analysis, you'll use the default selection result type, so you won't change the other parameters.

4. Click Run.

   The downstream trace is performed. On the map, the first 500 meters of cumulative stream length downstream from the starting point is selected.

   

   The selection ends at about the same point the stream reaches the Ashokan Reservoir, a feature that would aid pollution mitigation due to its high water volume.

5. On the ribbon, click the Edit tab. In the Selection group, click Clear.
6. Save the project.

In this tutorial, you wanted to trace a stream network upstream and downstream from a location where pollution was observed. You created the trace network, enabled network topology, and performed multiple trace analyses. Your results helped you determine where pollution may have originated and how far it might travel before it becomes diluted.

You can find more tutorials in the tutorial gallery.

Acknowledgements

• The Ashokan_Streams feature class was acquired from the United States Geological Survey (USGS). USGS-authored data is considered to be in the United States public domain.
• The Permitted_Discharger_Origin and Storm_Drain_Origin feature classes contain fictitious data and were created by Marcia Meixler. No restrictions on use.
• World Topographic Map sources: Esri, HERE, Garmin, FAO, NOAA, USGS, OpenStreetMap contributors, and the GIS User Community
• The gallery image is by Robert Lawton and was accessed from Wikimedia Commons. It is shared under the Creative Commons Attribution-Share Alike 2.5 Generic (CC BY-SA 2.5) license.