RivEX

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

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

1. Any selection on the input layer is cleared and then the tool processes all polylines in the river network.
2. River network must not be a compressed dataset.
3. 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")