Add Catchment ID

Summary :: Usage :: Parameters :: Outputs :: Warnings :: Limitations :: Code sample

Summary

Adds a new numeric field identifying the catchment ID of a polyline in the river network.

Usage

This tool adds a new numeric field called CatchID which is the catchment ID.

Catchment ID Example

The Isle of Lewis, UK river network colour coded by Catchment ID.

If the field exists it creates a new field with a simple numeric suffix (e.g. CatchID_1). Catchment ID can be derived from a simple numeric count as the network is processed (default) or the actual node ID of the mouth node.

Catchment ID's

A catchment is defined as a set of connected polylines that flow to a single node (the mouth). Thus small catchments that flow to a sink hole and appear to be small disconnected catchments will be treated as an individual catchment.

Using the force longest route option (which is default, but can be turned off) can significantly influence the output. To understand the implications click here for more information.

Parameters

Name	Help	Data type
River Network	The river network. For best results the network should be within a File GeoDatabase	Feature Layer
Assign Catchment ID using	Choose how the catchment ID is generated: Unique ID - The catchment ID starts at 1 and counts up until all polylines are assigned their appropriate catchment ID. Node ID - Polylines within a catchment are all assigned the node ID of the mouth node for the catchment.	String
Force longest Route	Some algorithms that RivEX use are sensitive to the digitising sequence of the network (i.e. the row order of the Feature Class). This can generate unusual attribution with catchments that have multiple mouths. Multiple mouths can occur in karst regions or as channels feeding into man made water courses. These are legitimate parts of the network yet they can significantly alter the output by RivEX. The force longest route option changes the behaviour of the algorithm and will influence any catchments with multiple mouths. This option is turned on as default but you can choose to ignore it by simply un-ticking the check box.	Boolean

Outputs

An updated river network with a new numeric field recording the catchment ID.

Warnings

Examine the image below for a situation that can occur within river networks. Here we have two catchments (#5 & #6) that join each other by a link as indicated by the arrow. Depending upon the orientation of the link most of the polylines will fall within one catchment even though in the real world the link is probably nothing more than a small drain with periodic flow.

Catchment link

Removing the link completely or breaking its topological connection at one of its nodes will ensure the rest of the polylines are attributed with correct catchment IDs.

With the release of ArcGIS Pro 3.2.1 a switch control appears on parameters that accept tables\feature classes, do not interact with it! More advice here.

Limitations

Any selection on the input layer is cleared and then the tool processes all polylines in the river network.
River network must not be a compressed dataset.

Code sample

A minimum code example showing how to call this tool in a python script. This can be run in console or your preferred IDE. If you right click on the tool in the RivEX toolbox and select properties you can view parameter order.

import arcpy

# Import RivEX toolbox
arcpy.ImportToolbox(r"C:\RivEX_ArcPro\RivEX.atbx")

try:
# Input river Feature Class
fc = r"C:\Temp\ORN\ORN.gdb\ORN"

# Run RivEX tool
res = arcpy.scrAttrCatchmentID_RivEX(fc, "Unique ID", True)

# Show output Feature Class name which is same as input
updatedfc = res.getOutput(0)
print(updatedfc)
except arcpy.ExecuteError:
print("FAILED to add Catchment ID")