Create upstream nearby network

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

Summary

Builds the nearby network in an upstream direction and can optionally buffer output.

Usage

This tool extracts the upstream network for each snapped site to the inputted distance (m). This upstream network is referred to as the "Nearby network" and is different from a reach which is a linear extract following a single river.

Upstream nearby network

An example of a 2Km upstream nearby network along with a 50m buffer.

The extraction of the upstream nearby network will include upstream traverses of any tributaries that fall within the desired nearby network length.

You may want to extract a nearby network if you are doing a habitat study and for example you wish to know the impact to all channels 5km upstream of a site. The tool can process all sites or just a subset if a selection exists and you have ticked the Process only selected sites checkbox. The nearby network distance can be a constant value or a value taken from a numeric field. Your site layer could potentially have a different nearby network distance for every site, for example scaled by Strahler order. Nearby network distance values must be greater than zero and in metre units.

The nearby network distance may not be achieved for some sites as they are closer to a network source than the distance you have entered. If this happens the nearby network is flagged as truncated. A Nearby network is considered NOT truncated if the desired nearby network distance was achieved along all tributaries and bifurcations.

If the section of network contains a multi-threaded section then the final limit reached is dictated by the digitizing order of the polylines. This is shown in the image below where the green and red bars indicate the limit of the extracted network. If the traverse upstream (or downstream) the network happened to follow the green (right hand side) route then as this is straighter it will achieve a further distance downstream\upstream. If it had followed the red (left hand side) route the final distance would appear shorter due the sinuosity of the left side, yet it has still travelled the required distance.

Influence of loop on nearby network

Which side of the loop RivEX traverses first will influence the final position of the network limit.

The default output will typically be the polylines upstream of the site and where the desired distance has been achieved a clipped polyline. Thus the nearby network will not necessarily share the same topology as the base river network it is extracted from. If you wish to treat the collection of polylines that make up the nearby network as a single entity then tick on Create multipart features and the polylines making up the nearby network will be dissolved to create a single multi-part feature.

If you have chosen to add to map (default) any Error log table created you can optionally get RivEX to construct a relate between it and the site layer to help you locate and deal with any sites that failed to process. Sites that fail to process are sites that are not intersecting the network.

You can by ticking on Buffer nearby network, create a buffer polygon around each nearby network which is a constant width or based upon a numeric value encoded into the site dataset. The buffer width must be greater than zero.

Parameters

Name	Help	Data type
River Network	The river network. For best results the network should be within a File GeoDatabase	Feature Layer
Site layer	A point layer for which you want to construct a upstream nearby network. This layer must conform to these specifications: Points are snapped to the network, if not, you can use the RivEX snap site tool. Layer must be in the same coordinate system as the river network. Layer must not have a table join. Contain a numeric (integer) field, uniquely identifying the sites. Geometry is a simple point, Multipoint geometry is not allowed.	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: CHECKED - Only sites that are selected will be processed. UNCHECKED (default) - All sites will be processed, any existing selection will be cleared before processing.	Boolean
Nearby network length generated using	This parameter allows you to switch between generating nearby networks using a constant length or use distances encoded into a field within the site layer. The options are: A constant value A distance from a field in site layer	String
Distance (m)	If the Nearby network length parameter was set to A Constant value then this parameter allows you to enter a positive number that is the length of the nearby network to be built for each site. Warning: a site may not achieve this length if it is placed near a river network mouth.	Double
Distance field	If the Nearby network length parameter was set to A Distance from a field in the site layer then this parameter will allow you to choose a numeric field. Values within your chosen field must be greater than zero and in the units of the river network. Warning: a site may not achieve this length if it is placed near a river network mouth.	Field
Create multipart features	The resulting nearby network can be outputted in one of two forms: individual polylines or as a single multi-part feature: CHECKED - The nearby network will be dissolved into a multi-part feature. In the attribute table you see one row for the nearby network but on the map you will have many polylines making up the nearby network. UNCHECKED (default) - The nearby network retains the original polyline geometries with the exception of when the limit of the nearby network has been reached and clipping of the polyline is required.	Boolean
Buffer nearby network	A check box used to indicate if you wish to run the optional buffering steps: CHECKED - You intend to construct buffers around the extracted nearby network. UNCHECKED (default) - No buffers are built and the optional step skipped.	Boolean
Nearby network buffer generated using	This parameter allows you to switch between generating nearby network buffers using a constant length or use distances encoded into a field within the site layer. The options are: A constant value A distance from a field in site layer	String
Buffer distance (m)	If the Nearby network buffer parameter was set to A Constant value then this parameter allows you to enter a positive number that is the constant buffer distance (m) of the nearby network to be built for each site.	Double
Buffer distance field (m)	If the Nearby network buffer parameter was set to A Distance from a field in the site layer then this parameter will allow you to choose a numeric field from your site layer. Values within your chosen field must be greater than zero.	Field
Add an attribute index to output	Indicates if RivEX will create an attribute index for the site ID field in the output layers CHECKED - RivEX will attempt to add an index to the site ID field in the output layer(s). UNCHECKED (default) - No index will be added to any output layer(s). If you plan to join or relate data then it is STRONGLY recommended you create attribute indices for the outputs; an index can significantly speed up query operations.	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 main output of this tool is the nearby network feature class, if the tool successfully runs and nearby networks are generated these are added to the active map. You do not have control over the location or name of this dataset. It is written to the file geodatabase fGDB_Sites.gdb which is in the RivEX workspace folder ..\RivEX_Workspace\Outputs\ and the Feature Class takes on the name of site name + "_USNearbyNet".

The optional buffer dataset is written to the same file geodatabase but uses the output name site name + "_USNearbyNetBuffer". If either of these names exist then RivEX adds a numeric suffix to the Feature Class name.

If errors were generated then this tool creates a stand alone table named tblFailedSitesForUSNearbyNetwork. 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.

The output nearby network feature class contains the following fields:

Field	Description
SiteID	The Site ID the nearby network was built from
Direction	The direction the nearby network was generated, this is always "US" for upstream
Truncated	A Y/N flag to indicate if the nearby network was truncated
NBNDist	The desired nearby network distance (m). This could have been a constant value for all sites or unique to each site taken from a numeric field in the site layer. Note this may not have been achieved if the site is closer to a network source than the desired distance, such cases are truncated networks
BuffDist	If the optional task of buffering the nearby network was chosen then this field is the input buffer width (m). This could have been a constant value for all sites or unique to each site taken from a numeric field in the site layer

The optional output buffer feature class contains the following fields:

Field	Description
SiteID	The Site ID the nearby network was built from
Direction	The direction the nearby network was generated, this is always "US" for upstream
BuffDist	This field is the input buffer width (m). This could have been a constant value for all sites or unique to each site taken from a numeric field in the site layer

If you have selected the optional processing task, add attribute index, then the SiteID field in both output datasets will be indexed. An index can significantly speed up query operations such as joins or relates.

Warnings

This tool checks for stacked points in the input dataset and warns the user if any are found. It returns a count on the number of stacks found to give you a sense of the extent of the issue. RivEX will continue to process such data. If stacked locations are unexpected for your input data then it is recommend you quality control the input layer before continuing with your analysis.

A limitation of this tool run in a script is that it only accepts feature classes for the site layer. It will fail with inputs as layers with/without selections. If you need to process data with selections you need to use the tool directly from the toolbox or python console, more details here.

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

This tool will not process data that has a latitude/longitude coordinate system (e.g. WGS84). You need to project your river network into a coordinate system that uses metres or feet.
The site data cannot be a in-memory layer.
Sites must be a simple point feature class, multi-point data is not allowed.
The site layer must be in the same coordinate system as the river network.
The site layer cannot have a join, you either need to remove the join or make it permanent.

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.

See warning above.

import arcpy

# Import RivEX toolbox
arcpy.ImportToolbox(r"C:\RivEX_ArcPro\RivEX.atbx")

try:
# Input river Feature Class
fcRivers = r"C:\Temp\ORN\ORN.gdb\ORN"

# Input site Feature Class
fcSites = r"C:\Temp\ORN\RivEX_Workspace\Outputs\fGDB_Sampling.gdb\Sites"

# Run RivEX tool, create uptream nearby network to a distance of 500m and do not merge into a multipart, create a buffer layer using a field that holds the buffer width for each site
# 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.scrUpStreamNBN_RivEX(fcRivers, fcSites, "SampleID", False, "A constant value", 500, "#", False, True, "A distance from a field in site layer", "#", "BufferWidth", False, False, False)

# The Upstream nearby network Feature Class, a derived output
fcUSNet = res.getOutput(0)

# The upstream nearby network buffers Feature Class, a derived output
fcUSBuff = res.getOutput(1)

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

# Check if error table exists
if arcpy.Exists(tblError):
# Count number of rows in error table
res = arcpy.GetCount_management(tblError)
n = int(res.getOutput(0))
print(str(n) + " error(s) generated")
else:
# No errors, OK to compute total area of buffers
l = list()
with arcpy.da.SearchCursor(fcUSBuff, "Shape_Area") as cursor:
for row in cursor:
l.append(row[0])

total = sum(l)
print("Total buffer Area (m) = " + str(total))
except arcpy.ExecuteError as e:
print(str(e))
print("FAILED to build upstream nearby network!")