RivEX

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

Summary

Adds a new numeric field recording the Hack Order of each polyline.

Usage

Requirement for using this tool:

To use this tool you must have attributed the network with:

• Source ID
• Upstream Length

This tool adds a new numeric field called Hack, if the field already exists, it creates a new field with a simple numeric suffix (e.g. hack_1). 

The Hack stream order is an alternative method for assigning a hierarchy to the river network. Starting at the mouth of the river the route to source is labelled 1. All tributaries and their route to source are labelled 2, all tributaries of these and their route to source are labelled 3 and so on. A stylized example is shown below.

Hack Stream Order

This tool uses the existing source ID values encoded into the polyline and sorted mouths (largest first) to encode Hack Order into the network.  RivEX does not use catchment area, it is the network distance that defines the source location.

Catchments with multiple mouths, break "dendritic logic", these will typically take on the Hack order of the line they connect with.  Any mouth found "within" the network having a valency greater than 1 have the polyline assigned -1.

The tool will initially appear to run slowly, this is because the algorithm sorts by upstream length and begins with the largest. The tool speeds up as it progressively processes smaller catchments.

Parameters

Outputs

An updated river network with a new numeric field recording the Hack Order of each polyline.

Warnings

Hack Order is typically applied to single threaded networks, usually derived from DTM's. Your vector river network may contain loops or highly braided sections. So how does RivEX deal with those? RivEX uses the source ID value to help it traverse the network when determining the Hack order of a polyline. Once a source ID value has been found this is logged and RivEX continues with the traversal of the river network. RivEX then applies the Hack Order to all polylines with the same source ID. In Braided sections many polylines will have the same source ID so they are all given the same Hack Order.

Hack Order applied to a vector river network. The first order (red) just below the legend has a loop.

All polylines within that loop were assigned the same Hack order value.

The Hack Ordering tool relies on the typical scenario of rivers flowing to a single mouth. For most networks this is the norm. But if after running the Hack Order tool you discover that the expected sequence is incorrect it is most likely down to the complex scenario shown below. Here we see a "false" mouth node which is not the mouth of the main river. The polylines upstream of the bifurcation will have the catchment ID of the main river. The polylines downstream of the bifurcation flowing to the "false" mouth will have another catchment ID. The Hack Ordering starts at mouth nodes so if this mouth node was created before the main river mouth then this is processed first. As the algorithm traverses upstream it will identify sources ID's in an invalid sequence and Hack Order will be incorrect. 

To resolve this situation you need to manually delete out the polylines leading to the "false" mouth and then re-run your network through the Extract Network Topology and write to Workspace tool to rebuild and correctly attribute the node and polyline fields in your river network.

RivEX uses upstream length and Source ID to compute Hack Order, a false mouth in a network will corrupt the sequence polylines are visited.

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.

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.scrAttrHackOrder_RivEX(fc)
    
    # Show output Feature Class name which is same as input 
    updatedfc = res.getOutput(0)
    print(updatedfc)
except arcpy.ExecuteError:
    print("FAILED to add Hack order")