RivEX

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

Summary

Locates the source of a river for a site and writes various metrics into a table, optionally constructs a polyline to it.

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 metrics on the route from site to source. The source is defined as the point furthest away from the network mouth upstream of your input site.  The source ID returned is the FROM node ID of the polyline and not the ID of the polyline.  In the image below the green point represents a site and the red point is the source that is identified.  The magenta dashed line has been added simply to visualise the route taken.

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 rapidly way of computing the required distance, it is not a "traditional" network traverse upstream approach as that would require testing every potential source.

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.

Any sites that fail to process are excluded from the output table so it's possible to have less rows in the output table than the number of sites that were in the input layer.

A site can fail to process for three reasons:

1. The site is not snapped to the network, i.e it is not intersecting the network.
2. During processing a topological error in the network has caused the search for source to fail, typically this is when source ID is set to -1.
3. The site catchment ID does not match the source catchment ID.  This unusual error is explained below.

A scenario that could exist in your river network is when multiple mouths exist within the catchment, an example is shown in the image below.  Depending where in the network your sites are it would return an incorrect distance to source as the distance to source is calculated as the distance the source is from the mouth minus the distance from mouth that the site is. If the site flows to one mouth and the source flows to another mouth then you get a disparity. RivEX captures these invalid sites and writes them to the Error Log table

If you have checked the optional build routes tick box then after the source table has been created RivEX will attempt to construct polylines that are the routes to source. This is a processor intense task, hence it being optional. The output is a polyline Feature Class that takes on the name of your source table tagged with _Routes.

The polyline is constructed in a source to site direction, so flows down hill. If you require the polyline to flow in an up hill direction (site to source), you need to check the flip direction tick box.

RivEX does a final check on the output routes by checking to see if any routes are not actually touching the site itself. This can occur if you have not cleaned up the network and left self-intersections or non-node intersections within the network. If any invalid routes are found then RivEX will list the site ID's for you to go back and check the network.

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.

The output table contains the following fields:

If you have selected the optional build routes task then output takes on the name of your source table tagged with _Routes.  For example if you called your source table name AmazonSources then the routes Feature Class will be called AmazonSources_Routes.  You have no control over its location, it will be stored in the output folder in ..\RivEX_Workspace\Outputs\fGDB_Sites.gdb.

The Route Feature Class contains two fields:

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

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

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.

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. The site cannot be a in-memory layer.
2. Sites must be a simple point feature class, multi-point data is not allowed.
3. The algorithm that creates the polyline to source is very different to the algorithm that creates the source table so it's possible, for networks that contain loops and a route to source has to follow one side of the loop, that the lengths of the site to source in the source table differ ever so slightly to the length of the polyline. Again there is typically no field in a river network indicating main stem priority so RivEX visits polylines in the order that were written to the table. These differences are likely to be trivial when considering the wider catchment.

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:\Scratch\ORN\data.gdb\ORN"

    # Input search sites Feature Class
    fcSites = r"C:\Scratch\ORN\RivEX_Workspace\Outputs\fGDB_Sampling.gdb\fcSample_10K_spaced"

    # Run RivEX tool, find source of site, do not build route feature class or index output
    # WARNING This tool will fail if river data is a layer with a selection! If you need to pass in selections use tool directly from toolbox    
    res = arcpy.scrFindSource_RivEX(fcRivers, fcSites, "SampleID", False,  "tblSources", False, False, False, False, False)

    # The sources tables, a derived output
    tblSources = res.getOutput(0)

    # The routes feature class
    fcRoutes = res.getOutput(1)    

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

    # Check if error table exists
    if arcpy.Exists(tblError):
        # Warn users errors were recorded
        print("Errors were encountered, check error log tables!")

    # Count number of sites which have a distance to source less than 2.5Km
    n = 0
    with arcpy.da.SearchCursor(tblSources, "SiteID", "Site2Src < 2500") as cursor:
        for row in cursor:
            n += 1
    print("Number of sites within 2.5Km of their source = " + str(n))
except arcpy.ExecuteError:
    print("FAILED searching!")