RivEX

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.

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.

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

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:

The optional output buffer feature class contains the following fields:

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

1. 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.
2. The site data cannot be a in-memory layer.
3. Sites must be a simple point feature class, multi-point data is not allowed.
4. The site layer must be in the same coordinate system as the river network.
5. 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!")