RivEX

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

Summary

Extracts a variety of standard RivEX attributes and positional related information for each site, including relative position, distance to first upstream and downstream tributary junctions and the distance to the downstream junction where a change in source ID occurs.

Usage

Requirement for using this tool:

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

• Source ID
• Catchment ID
• Distance to Mouth

This tool creates a new stand alone table recording various positional metrics for a site snapped to the network.

RivEX requires these fields to exist as it uses them to compute the distances. RivEX uses the difference between the source and the sites distance to network mouth to compute the distance from site to source. This approach is a rapid way of computing the required distance, it is not a "traditional" network traverse upstream approach as that would require testing every potential source. 

A limitation with the approach used by RivEX is that distance to network mouth encoded into the river network is influenced by loops within the network and which side of the loop RivEX took is based purely upon row order in the table. This means the distance to network mouth may have followed a side-channel instead of the main stem but most networks do not have a main-channel identifier field so RivEX simply takes the first line it comes across. This bias feeds back into this tool when computing the difference.  Channels are often very similar lengths on both sides of a loop so the bias is trivial when considering the wider catchment.  River networks derived from DEM processing typically do not have loops so such networks always yield an accurate distance.

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.

Distance to the first upstream and first downstream tributary junctions are computed along with distance downstream to the tributary junction where a change in source ID occurs. The change in source ID identifies the tributary junction where the river the site is on feeds into a larger river.

RivEX is also capable of computing the relative position the site is within the network, a metric used in this paper in the study of eel distributions.  The relative position of a site is its distance from network mouth divided by the distance the site's source is from the network mouth. To help you understand what relative position is and the variety of attributes extracted out by this tool, review the image and table below.

Black square is a site snapped to the network, magenta dot represents the mouth node of the catchment.

The relative position of the site would be (2050 / 3550) * 100 = 57.8%

Parameters

Outputs

The output table can be given a name but you have no control over where it is stored, this would be in the file geodatabase in the output folder ..\RivEX_Workspace\Outputs\fGDB_Sites.gdb.  Distances reported are in the units of the network.

The output table contains the following fields:

A site can fail to process for three reasons, the site is not snapped to the network, the site was snapped to a network node or during processing a topological error in the network has caused the search to fail. Non-intersecting sites and sites that intersect nodes are excluded from the final output so it's possible to have less rows in the output table than the number of sites that were in the input layer.

Default values of -1 are assigned to fields for specific reasons, these are listed below:

1.        Any sites that fails to process are assigned a -1 value for all fields.

2.        The field Dis2USTrib will be set to -1 if the site is on a source polyline (Strahler order 1) as there is no upstream tributary junction. Upstream of it is a terminal source node, this is not a tributary junction.

3.        The field Dis2DSTrib will be set to -1 if the site is on a mouth polyline as there is no downstream tributary junction. Downstream of it is a terminal mouth node, this is not a tributary junction.

4.        The field Dis2DSTbSc will be set to -1 if the site is on a source ID that continues all the way to the river mouth (Hack order 1) as there is no downstream tributary junction where a change in source ID occurs.

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

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

Sites that fail to intersect the network are excluded from the output. Networks with multiple mouths within a catchment can cause sites to have un-matching source ID's, these are rejected and logged in the Error Log table. Sections of networks where RivEX is unable to determine a sensible source ID are typically flagged up as -1. Any sites that intersect such sections of network are rejected and recorded in the Error Log. Sites that intersect a network node are rejected to avoid unresolvable scenarios and recorded in the Error Log.

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 dataset cannot be a in-memory layer.
3. Site layer must not have a table join.
4. Sites must be a simple point feature class, multi-point data is not allowed.

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\ORN.gdb\ORN_Sampled_100m"

    # Run RivEX tool, extract positional data and index output 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.scrExtractSitePosition_RivEX(fcRivers, fcSites, "SampleID", False, "tblPositionalData", True, False, False)

    # The rivers Feature Class, a derived output
    tblPosData = 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 extract positional data")