RivEX

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

Summary

Checks for cycles within the network, any found are logged in the error log table.

Usage

This tool checks for cycles within the network. A cycle is formed when the direction of one or more polylines causes a downstream search to revisit a polyline already visited in the search. Such cycles would affect the outcome of any processing such as stream ordering or site linking.

By removing cycles from a network you are ensuring that the river network is a Directed Acyclic Graph, this is a river network which has all polylines flowing in a downstream direction.

The tool works by starting at all nodes that are a bifurcation and traversing the network in a downstream direction until a mouth node is found. If the search downstream visits a polyline that had already been traversed then a cycle exists and this needs to be corrected. You would correct the cycle by flipping the orientation of a polyline to ensure its flowing in a source to sea (downstream) direction. Guidance on flipping a polyline is given here.

In the image below, polyline 226484 is reported in the error log. In ArcPro with direction of polyline visualized it is clear 246320 & 251608 are pointing in the upstream direction and require flipping. You must treat the ID's in the cycles error log table as a pointer to the general location within the river network where a cycle is forming. The polylines that are actually causing the cycle are usually within a few segments of the reported polyline.

Any selection on the input river network is cleared as the tool checks the whole network. Any cycles found have a polyline ID written to an error log table called tbCycles. If the table already exists then a new table name is created with a simple numeric suffix.

The tool optionally adds the error log table to the map (default) and if selected builds a standard relate between river network layer and error log table. You can use the relate to select and jump to the polyline to streamline your editing experience.

Parameters

Outputs

This tool creates a stand alone table named tblCycles, if any cycles are encountered within the river network.  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

This tool traps for cycles by continuously checking if a polyline ID has been added to a list as it traverses in a downstream direction towards the river mouth. If an ID is found in the list the tool collects the ID it stopped at. This may not be the polyline that is causing the cycle. Think of the ID as a general locator and you need to search the nearby network for the invalid polyline, these are almost always a few polylines away.  Please refer to the RivEX help file for further advice.

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

None.

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 quality control tool
    res = arcpy.scrQCCycles_RivEX(fc, False, False)
    
    # The rivers Feature Class, a derived output
    fcRivers = res.getOutput(0)
    
    # Get error table
    tblError = res.getOutput(1)

    # Check if error table exists
    if arcpy.Exists(tblError):
        # Count number of rows
        res = arcpy.GetCount_management(tblError)
        n = int(res.getOutput(0))
        if n > 0:
            print(str(n) + " error(s) were recorded")
    else:
        print("No error table created!")
except arcpy.ExecuteError:
    print("FAILED to quality control network")