Extract catchment metrics from the river network
Summary :: Usage :: Parameters :: Outputs :: Warnings :: Limitations :: Code sample
Summary
This tool will extract a variety of metrics from the river network and write the results to a table. Such data could help explain phenomena observed in a catchment or simply provide summary statistics for each catchment within the network.
Usage
This tool takes a river network and generates a table of catchment metrics. To be able to use this tool you must have encoded into the river network the following RivEX attributes:
RivEX uses these attributes to efficiently derive a range of metrics. Catchment ID is used to aggregate data and this can introduce unusual results if the network has multiple mouths, such as a deltaic scenario.
If a selection exists on the river network this is cleared.
Optional tasks
Add attribute index - Tick this on (default) and RivEX will create an index for the Catchment ID field in the output Table, this will improve any query/join performance using this field.
Parameters
|
Name |
Help |
Data type |
|
River Network |
The river network. For best results the network should be within a File GeoDatabase |
Feature Layer |
|
Output table name |
The output table name for your catchment metrics data. You do not have control over the location where this table is created, RivEX controls that, but you can decide its name. The table name must be a geodatabase compliant name, so must not have spaces, other unusual characters or start with a number. Output will be stored in fGDB_Network.gdb in the RivEX Workspace Output folder. |
String |
|
Add an attribute index to output |
Indicates if RivEX will create an attribute index for the catchment ID field in the output table.
If you plan to join or relate data then it is STRONGLY recommended you create attribute indices for the outputs; an index can significantly speed up query operations. |
Boolean |
Outputs
The output of this tool is a table written to the File GeoDatabase fGDB_Network.gdb which is stored in the Outputs folder in the RivEX Workspace. You can control the name of the Table but not its location. The output name must be a valid file geodatabase name.
The output table will contain the following fields:
|
Field |
Description |
|
CatchID |
The catchment ID. This is the unique ID given to the catchment by the Add Catchment ID tool. |
|
NumMouths |
The number of mouths or "outlets" in the catchment. Typically this 1 but can be higher if the catchment has channels feeding into canals or becomes a delta system at the coastline. |
|
NumSources |
The number of sources in a catchment, this will typically be 1 or more but can be assigned a zero value if the catchment has multiple mouths. See warning section for further advices. |
|
NumNodes |
The total number of nodes within the catchment. |
|
NumPseudo |
The number of pseudo nodes within the catchment. A node is classified as pseudo if it has a valency of 2. |
|
NumTribs |
The number of tributary junctions. A tributary junction is defined as a node with a valency of 3 or more with at least two different incoming source IDs. See warning section for further advices. |
|
NumLoops |
The number of loops within the catchment. A loop is defined by the rule set used in the Add Loop ID tool. |
|
SumNet |
The sum length of network for the catchment, reported in units of the dataset (metres/feet). |
|
LongestRoute |
This is the furthest distance from the network mouth for the catchment, reported in units of the dataset (metres/feet). |
|
MaxStrahler |
This is the Strahler order at the catchment mouth and thus the largest stream order to be achieved within the catchment. |
Advice on the structure of the error log table and how it can be used is found within this section of the manual. Take note of the warning if you plan to construct a model using the error log output in subsequent processing.
Warnings
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.
This tool counts nodes aggregated by the catchment ID encoded into the network. If two catchments are connected by a segment, then the end of the segment which is a distributary node is not counted as a source node. This can lead to the unusual situation of a catchment counting zero sources.
To be counted as tributary node it must have a valency of 3 or more with at least two different incoming source ID's. Thus a node at the bottom end of a loop is not counted as tributary junction as typically both inflowing branches will have the same source ID. Thus catchments with loops will not tally up to the value counted in NumNodes.
When this tool is used in a script the river network parameter must be a full path to the Feature Class and not a layer object, see advice here.
Limitations
- This tool will reject river networks that do not have linear units. Networks in latitude/longitude will be rejected.
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
# This Feature Class must have the required 5 RivEX attributes as specified in the
# tools help page.
fc = r"C:\Temp\ORN\ORN.gdb\ORN"
# Run RivEX tool to create metrics table and add an index to CatchID field
res = arcpy.scrCatchmentMetrics_RivEX(fc, "tblORNMetrics", True)
# Count the number catchments which have a main stem of more than 100Km long
table = res.getOutput(0)
n = 0
sQuery = "LongestRoute > 100000" # Units will be in metres
with arcpy.da.SearchCursor(table,"CatchID", sQuery) as cursor:
for row in cursor:
n += 1
print("Number of catchments with a main stem longer than 100Km = " + str(n))
except arcpy.ExecuteError:
print("FAILED to run create network metrics tool")
