RivEX

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

Summary

Identifies all upstream sites for each input site. Output is written to a table.

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 all sites found upstream of each input site. Upstream is defined as the network from the input site to all upstream sources within the catchment. The river network needs to be in a projected coordinated system.

Sites that have no sites upstream of themselves are coded with a -1. Therefore all sites are returned in the output as either -1 or a list of upstream IDs. During processing sites are sorted into catchments based upon the catchment ID encoded into the network. Sites are only linked within the same catchment ID, this avoids the tool reporting sites upstream of the input site that may exist in another catchment which are linked by a bifurcation.

If you tick on Constrain upstream search to source ID then you constrain the search to return only upstream sites on the same source ID as the site to search.  You can think of this as only searching for sites on the route to source, ignoring any tributaries.  This constraint can generate sites that report they have no upstream sites, thus code as -1. This can happen when none of the upstream sites are actually on the route to source (source ID).  If you use this constraint option RivEX will report in the message box the number of sites that were rejected as not having an upstream site and then list all the ID's

You can further filter data by the attributes within the upstream site layer to search.  You can build a SQL expression to filter your upstream sites.  For example you may be only interested in upstream sites that occur on Strahler order 3 or less. May be your sites represent barriers with varying passibility and you are only interested in barriers that have low passibility to fish, you would set the SQL expression to select these points only. If you set this then only sites that fulfil the selection criteria are considered when RivEX traverses the network.  To use this parameter the attributes you want to filter upstream sites by must be encoded into the upstream site layer.  You can use the RivEX tool Transfer network metrics to pass values encoded in the network into your site layer. Creating a SQL expression that does not select any sites will cause RivEX to default to processing all sites.

Before RivEX searches the sites, it checks if all sites are intersecting the river network. Only snapped sites are processed, failed sites are reported in the error log tables (tblFailedSitesFrom or tblFailedSitesTo) that can be optionally loaded into the map for convenience.

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. If the sites to search is also the upstream sites to find layer then any existing selection is cleared and all sites are processed, this is because they are the same layer.  Sites must be a simple point feature class, multi-point data is not allowed.

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:

Distance values are in the units of the river network. Any sites that have no upstream sites are assigned a -1 value for the fields USSite_ID , USSite_D2M, USSite_Dis.

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 two stand alone tables named tblFailedSitesFrom or tblFailedSitesTo.  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

If an upstream site is at exactly the same location as your input site (stacked points) then these are rejected, these are being treated as being on the same polyline but downstream of the input site.

The USSite_Dis field is not calculated using a "classic" shortest path search it is calculated by subtracting the distance from network mouth of the TO site from the distance to network mouth of the FROM site. In river networks without loops this will always yield an accurate measure. In networks where the sites are separated by network that contain loops it is possible for RivEX to over estimate the distance between sites if the upstream site distances to network mouth was calculated by traversing another route through the multi-threaded section. Such over estimates are generally trivial but if the multi-threaded sections of the network are highly sinuous this may generate an unacceptable error. More information can be found here.

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. Site layer must not have a table join.
3. 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:\Scratch\ORN\data.gdb\ORN"

    # Input search sites Feature Class
    fcSites = r"C:\Scratch\fGDB_Scratch.gdb\p3"

    # Input upstream sites to find Feature Class
    fcUSSites = r"C:\Scratch\ORN\RivEX_Workspace\Outputs\fGDB_Sampling.gdb\fcSample_10K_spaced"

    # Run RivEX tool, find upstream sites, do not constrain to source ID for filter inputs, build an attribute index.
    # 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.scrFindUSSites_RivEX(fcRivers, fcSites, "SampleID", False, fcUSSites, "SampleID", "tblUpstreamSites", False, "", True, False, False)

    # The upstream sites tables, a derived output
    tblUSSites = res.getOutput(0)

    # The error table for search sites
    tblErrorFROM = res.getOutput(1)    

    # The error table for the upstream sites
    tblErrorTO = res.getOutput(2)

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

    # Count number of catchment ID's involved in the searching
    aSet = set()
    with arcpy.da.SearchCursor(tblUSSites, "Site_Cat") as cursor:
        for row in cursor:
            aSet.add(row[0])
    print("Number of catchments = " + str(len(aSet)))
except arcpy.ExecuteError:
    print("FAILED searching!")