RivEX

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

Summary

Builds reaches centred on input site with optional settings such an extract end points, clipping downstream search to source ID and flipping the direction of the final polyline.

Usage

Requirement for using this tool:

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

• Source ID

This tool builds reaches (polylines) from the input site layer in an upstream and downstream direction, with the site being at the centre of the reach. Such reaches could represent the limits of survey sites for which you want to compute slope

5 sites and their centred reaches.

Optional end points have also been extracted

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 reach length can be a constant value or a value taken from a numeric field.  Your site layer could potentially have a different downstream reach length for every site, or scaled in some manner (e.g. reach length scaled by Strahler order).  Reach length values must be greater than zero and in metre units. If your network is in units of feet then RivEX will convert the metres value into feet.

It is possible for the desired reach length is not reached and the reach is flagged as Truncated. This happens if the site is close to a network mouth or source or you have ticked on clip by source ID.

If you have ticked on Clip downstream reach to Source ID. RivEX will honour the source ID encoded into the river network, with this option enabled RivEX will stop traversing in a downstream direction when it detects a change in source ID, this will likely truncate the reach.  Further information on the influence of this parameter is found here.

Ticking on Extract reach end points will cause RivEX to extract out the end points (nodes) of the reaches into a separate dataset, this would be useful if you were intending to compute slope of the reach.

If you have ticked on Flip reach direction RivEX will flip the direction of the reach polyline once it has created it, tick this on if you require the reach polyline to flow in a sea to source direction.

An attribute generated for each reach is sinuosity, computed as reach length divided by straight line path, an example is shown below.

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 or they intersect a network junction, these are skipped and require you to make a decision on which tributary they lie on and you need to move them.

Parameters

Outputs

The main output of this tool is the reach feature class, if the tool successfully runs and reaches 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 + "_USDSReaches".  The optional reach nodes datasets is written to the same file geodatabase but uses the output name site name + "_USDS_Reach_Nodes".  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 tblFailedSitesForUSDSReach.  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 reach feature class contains the following fields:

The optional output nodes 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

The network needs to be in units of metres or feet.  Data in decimal degrees will yield invalid output.

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. This tool requires your network to be attributed with Source ID.
5. The site layer must be in the same coordinate system as the river network.
6. 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:\Scratch\ORN\data.gdb\ORN"

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

    # Run RivEX tool, create a reach 1km upstream and downstream of site, clip to source ID, do not flip, extract end points or 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.scrCentredReaches_RivEX(fcRivers, fcSites, "SampleID", False, "A constant value", 1000, "#", True, False, False, False, False, False)

    # The reach Feature Class, a derived output
    fcReach = res.getOutput(0)

    # The end point Feature Class, a derived output
    fcEndPoints = res.getOutput(1)    

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

    # 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!")
        res = arcpy.GetCount_management(fcReach)
        n = int(res.getOutput(0))
        print("Number of reaches created = " + str(n))
        
except arcpy.ExecuteError:
    print("FAILED to build reaches!")