Add Shreve Order
Summary :: Usage :: Parameters :: Outputs :: Warnings :: Limitations :: Code sample
Summary
Adds a new field to the river network recording the Shreve Order of each polyline.
Usage
This tool adds a new numeric field called Shreve which is the Shreve Order of the polyline. If the field exists it creates a new field with a simple numeric suffix (e.g Shreve_1). Knowing the Shreve order instantly tells you the number of upstream sources of a polyline. The Shreve ordering algorithm is iterative; it starts at a source and travels down the network incrementing the order of the polylines. It repeats this process for every source, updating any previously traversed polylines.
If the network forms a loop this tool will log the Tnode ID in an Error Log file called tblShreveNodeErrors. If the Error Log table already exists a new table is created with a numeric suffix. A loop occurs when a polyline is flowing in an upstream direction which causes the network traversing algorithm to revisit polylines already processed.
Shreve stream order is not designed for multi-channelled networks. If RivEX encounters a section of multi-channel network such as a braid it will choose a SINGLE route through this section. All other polylines within the multi-channel section remain encoded as ZERO. This route is based purely upon the row order of polylines in the table, i.e. the order in which it was digitised. This order is not always the main course of the river so caution should be used when interpreting the output for river networks with loops.
A network colour coded by Shreve Stream order, this catchment reaches an order of 910 at the outlet.
Parameters
Name |
Help |
Data type |
River Network |
The river network. For best results the network should be within a File GeoDatabase |
Feature Layer |
Add Error Log Table to Map |
If this is ticked (default) the error log table will be added to the map for your convenience if any errors were found. |
Boolean |
Build a Relate for Error Log |
If this tick box is checked then the error log table must be loaded into the map and RivEX builds a standard relate between the Error Log table and the river network layer. You can use the relate to help you jump to and review the error. |
Boolean |
Outputs
An updated river network with a new numeric fields recording the Shreve Order. Polylines encoded as zero will occur in loops. You can take advantage of this if you need a single threaded network by dropping all polylines with a Shreve Order of zero. Be aware that the remaining channel might not actually be the main channel as polylines in loops are assigned an order based upon the row order they were visited.
If errors were generated then this tool creates a stand alone table named tblShreveNodeErrors. The table is created in the RivEX workspace folder and stored in the File GeoDatabase found in ..\RivEX_Workspace\ErrorLogs\fGDB_RivEXErrorLogs.gdb
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.
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.
- Large networks with more than million sources will generate a warning message to inform you that the tool will take longer to run.
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 adding table to map and creating a relate are set to false
res = arcpy.scrAttrShreve_RivEX(fc, False, False)
# Show output Feature Class name which is same as input
updatedfc = res.getOutput(0)
print(updatedfc)
except arcpy.ExecuteError:
print("FAILED to add Shreve")