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


Builds upstream reaches for sites with optional settings such an extract end points and flipping polyline direction.


Requirement for using this tool:

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

This tool builds reaches (polylines) from the input site layer in a upstream direction. Such reaches could represent zones of upstream impact from structures in the channel (e.g. weirs) or the upstream limits of survey sites. 

Upstream reaches

4 sites and their upstream reaches

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 upstream 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 upstream reach length to not be reached and the reach is flagged as Truncated. This happens if the site is close to a network source.

As RivEX traverses in an upstream direction it follows the source ID that the site was on.

Ticking on Flip reach direction will cause RivEX to reverse the direction of the upstream reach polyline.  You would flip the polyline direction if you intend to do further analysis which requires a downstream flowing polyline

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.

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

Computing sinuosity

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.




Data type

River Network

The river network. For best results the network should be within a File GeoDatabase

Feature Layer

Site layer

A point layer for which you want to construct a upstream reach. This layer must conform to these specifications:

    • Points are snapped to the network, if not, you can use the RivEX snap site tool.
    • Layer must be in the same coordinate system as the river network.
    • Layer must not have a table join.
    • Contain a numeric (integer) field, uniquely identifying the sites.
    • Geometry is a simple point, Multipoint geometry is not allowed.

Feature Layer

Site ID field

This is a numeric (integer) field that uniquely identifying the sites.

Text, Object ID or FID fields are not accepted.


Process only selected sites

Indicates if only selected sites are to be processed:

    • CHECKED - Only sites that are selected will be processed.

    • UNCHECKED (default) - All sites will be processed, any existing selection will be cleared before processing.


Reach length generated using

This parameter allows you to switch between generating reaches using a constant length or use distances encoded into a field within the site layer. The options are:

    • A constant value

    • A distance from a field in site layer


Distance (m)

If the Reach length parameter was set to A Constant value then this parameter allows you to enter a positive number that is the length of the downstream reach to be built for each site. Values you enter must be greater than zero and represent metres.

Warning: a site may not achieve this length if it is placed near a river network mouth.


Distance field (m)

If the Reach length parameter was set to A Distance from a field in the site layer then this parameter will allow you to choose a numeric field. Values within your chosen field must be greater than zero and represent metres.

Warning: a site may not achieve this length if it is placed near a river network mouth.


Flip reach direction

Indicates if RivEX will reverse of "flip" the reach polyline direction:

  • CHECKED - The reach polyline will be flipped.

  • UNCHECKED (default) - Polyline remains in the direction of flow it was created as.


Extract reach end points

Indicates if RivEX will extract the nodes of the reach:

  • CHECKED - The reach nodes will be written to a separate Feature Class.

  • UNCHECKED (default) - No nodes will be created.

If reach nodes are created then the Feature class will contain the following fields: "SiteID", "WhichEnd", "ReachLngth"


Add an attribute index to output

Indicates if RivEX will create an attribute index for the site ID field in the output layers

  • CHECKED - RivEX will attempt to add an index to the site ID field in the output layer(s).

  • UNCHECKED (default) - No index will be added to any output layer(s).

If you plan to join or relate data then it is STRONGLY recommended you create attribute indices for the outputs; an index can significantly speed up query operations.


Add Error Log Table to Map

If this is ticked (default) the error log table will be added to the map for your convenience if any errors were found.


Build a Relate for Error Log

If this tick box is checked then the error log table must be loaded into the map and RivEX builds a standard relate between the Error Log table and the river network layer. You can use the relate to help you jump to and review the error.



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 + "_USReaches".  The optional reach nodes datasets is written to the same file geodatabase but uses the output name site name + "_US_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 tblFailedSitesForUSReach.  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 Site ID the reach was built from


The direction the reach was generated, this is always "US" for upstream


A Y/N flag to indicate if the reach was truncated


The polyline ID the site was intersecting


The sinuosity of the reach, this is computed as reach length divided by straight line distance between its end points.

The optional output nodes feature class contains the following fields:




The Site ID the reach was built from


Which end of the reach the node is, this is always either "US" or "DS"


The length of the reach.  This could potentially be shorter than the desired length due to truncation

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.


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.


  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

    # 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 1Km upstream reaches, 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.scrUpStreamReaches_RivEX(fcRivers, fcSites, "SampleID", False, "A constant value", 1000, "#", 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")
        print("No error table created!")

except arcpy.ExecuteError:
    print("FAILED to build reaches!")

Return to top of page