Create subnetworks from sites
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:
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:
- 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.
- 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.
- Site ID field holds a unique ID value. If this is not the case then RivEX will abort.
- Site layer must be in the same coordinate system as the river network.
- Sites must intersect the network, non-intersecting sites will be dropped from analysis.
- 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:
- Create a subnetwork statistics table - Tick this on and RivEX will create a stand alone table listing subnetwork lengths against subnetwork ID.
- Create site statistics table - Tick this on and RivEX will generate a stand alone table listing upstream and downstream subnetwork lengths against site ID.
- 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
Name |
Help |
Data type |
River Network |
The river network. Must be single thread, it must not contain loops/braids. For best results the network should be within a File GeoDatabase |
Feature Layer |
Site layer |
A point layer that will be to cut the network up into subnetworks This layer must conform to these specifications:
|
Feature Layer |
Site ID field |
This is a numeric (integer) field that uniquely identifying the sites. Text, Object ID or FID fields are not accepted. |
Field |
Process only selected sites |
Indicates if only selected sites are to be processed.
|
Boolean |
Output feature class name |
The Feature class name, this must be a valid file geodatabase table name, so cannot have spaces, unusual characters or start with a number. You have no control over its location, it will be stored in the output folder in ..\RivEX_Workspace\Outputs\fGDB_Network.gdb |
String |
Create subnetwork statistics table |
An optional task which creates an output table listing network length by sub network ID. The table name is defined by the output feature class name with _NetStats appended. For example, if your output feature class name was sub10k, then the network statistics table will be called sub10k_NetStats. You have no control over its location, it will be stored in the output folder in ..\RivEX_Workspace\Outputs\fGDB_Network.gdb |
Boolean |
Create site statistics table |
An optional task which creates an output table listing Upstream and Downstream network lengths for the site. See help file for more details. The table name is defined by the output feature class name with _SiteStats appended. For example, if your output feature class name was sub10k, then the network statistics table will be called sub10k_SiteStats. You have no control over its location, it will be stored in the output folder in ..\RivEX_Workspace\Outputs\fGDB_Network.gdb |
Boolean |
Join original catchment ID to subnetwork |
An optional task that joins the catchment ID in the input river network to the output sub network. This option is only available if you have encoded catchment ID into the input network. It is able to join such data as the original RivID field is passed over into the newly created subnetwork dataset during the cutting up phase of this tool. This optional also generates a table which gives you the proportion of the catchment that the subnetwork is. This is the subnetworks total length divided by the catchments total length. The table name is defined by the output feature class name with _PropCatchStats appended. For example, if your output feature class name was sub10k, then the network statistics table will be called sub10k_PropCatchStats. You have no control over its location, it will be stored in the output folder in ..\RivEX_Workspace\Outputs\fGDB_Network.gdb |
Boolean |
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
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:
Field |
Description |
New_RivID |
The unique polyline ID for the new network dataset. |
ORIG_RivID |
The polyline ID from the original network. Where a site has been used to split a line you will see the ID duplicate. |
SubNetID |
The subnetwork ID, starting from 1. |
Fnode |
The FROM-node ID of the new network. |
Tnode |
The TO-node ID of the new network. |
catchID |
This only appears if the optional join catchment ID task was selected and the base network has a Catchment ID field. |
If you have chosen the optional tasks of building simple statistic tables then these tables contain the following fields:
Network Statistics:
Field |
Description |
SubNetID |
The subnetwork ID. |
SubNetLen |
The sum of the polyline lengths for the subnetwork. This will be in the units of coordinate system. |
Site Statistics:
Field |
Description |
SiteID |
The site ID. |
US_SubNetID |
The upstream subnetwork ID for the site. |
US_SubNetLen |
The sum of the polyline lengths for the subnetwork. This will be in the units of coordinate system. |
DS_SubNetID |
The downstream subnetwork ID for the site. |
DS_SubNetLen |
The sum of the polyline lengths for the subnetwork. This will be in the units of coordinate system. |
Catchment Proportion Statics:
Field |
Description |
CatchID |
The catchment ID from the input river network |
SubNetID |
The subnetwork ID |
SubNetLen |
The sum of the polyline lengths for the subnetwork. This will be in the units of coordinate system. |
CatchLen |
The sum of the polyline lengths for the catchment ID. This will be in the units of coordinate system. |
SubNetProp |
The proportion of the catchment the subnetwork is. This is the SubNetLen divided by CatchLen |
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
- The site data cannot be a in-memory layer.
- Site layer must not have a table join.
- Sites must be a simple point feature class, multi-point data is not allowed.
- River network must be single threaded, it must not contain loops or braided sections.
- 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!")