RivEX

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

Summary

Create a new network cut up by sites and coded with a unique subnetwork ID. Optionally generates site and network statistic tables.

Usage

Requirement for using this tool:

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

• Catchment ID

This tool will take as input a simplified river network and site layer and use the sites to cut up or "fragment" the network into a new dataset of subnetworks, so that you can compute upstream and downstream networks for a site.  Such sites could represent barriers to fish migration and knowing the available upstream and downstream networks is an important metric for habitat connectivity studies.  You can think of a subnetwork as all available upstream channels to every tributary source but stopping at any upstream sites (barriers).  Conversely the downstream subnetwork is all downstream channels and up any tributaries until a source, mouth or downstream barrier is hit.  The subnetworks ID's are written to a field called SubNetID and the ID's start from a value of 1.

A barrier point dataset snapped to the network has been used to construct subnetworks and the resulting output

has been colour coded by the Subnetwork ID.

An important requirement to this tool is that the input river network is single threaded; it must not contain any loops or braided sections. This allows RivEX to compute the correct subnetwork lengths without being circumvented by side channels.

If a selection exists on the river network this is cleared.  Input sites must be snapped to the network and have a unique numeric ID (which is not the Object ID field). You can choose to process a subset of sites if they have been selected and you have ticked on the appropriate parameter.

RivEX will do a variety of checks on the input data, failing any will lead RivEX to abort the tool:

1. Does the site layer have a table join, if yes then RivEX will abort. Simply run the tool again without the table join on the site layer.
2. Does the network have any loops? RivEX checks the node type dictionaries for bifurcating or diverging nodes, any found and RivEX will abort.  You will need to remove one side of the loop in all loops. A trick to bulk process a whole network is to add Shreve order to the network and delete out all polylines that have Shreve order of zero. Be aware the assignment of Shreve is based upon row order so you could inadvertently delete out a main channel whilst retaining connectivity via a minor drainage channel. A situation you may not want.  You could manually check the assigned Shreve order and swap values before you attempt to drop zero order channels. A worked example in simplifying your network to a single threaded network is discussed on this page.
3. Site ID field holds a unique ID value. If this is not the case then RivEX will abort.
4. Site layer must be in the same coordinate system as the river network.
5. Sites must intersect the network, non-intersecting sites will be dropped from analysis.
6. Some site datasets you have may include STACKED points, these are sites with the same XY coordinates but vary in other information, for example date last surveyed.  Stacked points will be collapsed to a single point so subnetworks can be created.

RivEX can generate simple statistics on the subnetworks as well as joining back the Catchment ID from the input river network, these optional tasks are:

1. Create a subnetwork statistics table - Tick this on and RivEX will create a stand alone table listing subnetwork lengths against subnetwork ID.
2. Create site statistics table - Tick this on and RivEX will generate a stand alone table listing upstream and downstream subnetwork lengths against site ID.
3. Join original catchment ID to subnetwork - If the input river layer has been attributed using RivEX with Catchment ID, then ticking this option on will cause RivEX to transfer the original catchment ID to the subnetwork layer. This is done by matching on the Orig_RivID and copying over the Catchment ID field.

Parameters

Outputs

The primary output of this tool is a new polyline dataset that is the result of cutting up the input river layer by sites.  Lines are split at sites and this fundamentally alters the topology of the network thus any existing attribution in the input river network is not retained with the exception of the polyline ID which is stored in the Orig_RivID field.  You could use that field to join data back from the base network, but be aware any measure-like attribute will be incorrect and categorical data might need splitting at the new node created by the site.  Do not make the mistake of thinking the node fields are the same values as the input river network; they had to be regenerated so the subnetwork ID's could be computed.  The subnetwork feature class and optional statistic tables are written to the File GeoDatabase in ..\RivEX_Workspace\Outputs\fGDB_Network.gdb

The output subnetwork dataset contains following fields:

If you have chosen the optional tasks of building simple statistic tables then these tables contain the following fields:

Network Statistics:

Site Statistics:

Catchment Proportion Statics:

If errors were generated then this tool can create a stand alone table named tblSubnetworkErrors.  The table is created in the RivEX workspace folder and stored in the File GeoDatabase found in ..\RivEX_Workspace\ErrorLogs\fGDB_RivEXErrorLogs.gdb. The error log will record sites that did not intersect the network, sites that are stacked points but not on the network and sites that are stacked and intersecting the network.

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

Sites that fail to intersect the network are excluded from the processing. Stacked sites are reduced to a single point so RivEX is able to construct the subnetworks. Sites that intersect tributary nodes will be processed in a manner that each tributary is a separate subnetwork. As a final quality control check RivEX looks for subnetwork ID's of zero, indicating a topological error exists in your base river network. It is up to you to explore the reason.

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. The site data cannot be a in-memory layer.
2. Site layer must not have a table join.
3. Sites must be a simple point feature class, multi-point data is not allowed.
4. River network must be single threaded, it must not contain loops or braided sections.
5. The optional processing task of joining catchment ID to subnetwork output can only work if the RivEX Catchment ID exists in the input river network.

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
    fcRivers = r"D:\GIS_Data\Data_in_FEET\testriver.shp"

    # Input site Feature Class
    fcSites =  r"D:\GIS_Data\Data_in_FEET\RivEX_Workspace\Outputs\fGDB_Sites.gdb\sites_Snapped_2"

    # Run RivEX tool, create sub network along with optional sub-network statistics table
    # WARNING This tool will fail if site data is a layer with a selection! If you need to pass in selections use tool directly from toolbox
    res = arcpy.scrCreateSubnetworks_RivEX(fcRivers, fcSites, "Id", False, "fcSubNetwork", True, False, False, False, False)

    # The sub network Feature Class, a derived output
    fcSubNet= res.getOutput(0)
    
    # Get sub network statistics table
    tblSubNetStats = res.getOutput(1)

    # Get site statistics table
    tblSiteStats = res.getOutput(2)

    # Get subnet catchment proportion statistics table
    tblSubNetPropCatchStats = res.getOutput(3)

    # Get error table
    tblError = res.getOutput(4)

    # Count number of rows in stats table, this is the number of sub networks created
    res = arcpy.GetCount_management(tblSubNetStats)
    n = int(res.getOutput(0))
    print(str(n) + " sub networks were created")

except arcpy.ExecuteError:
    print("FAILED to build sub networks!")