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


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.


Requirement for using this tool:

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

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.

Line Colour




The distance from site to the first downstream tributary junction

300 m


The distance from site to the first upstream tributary junction

500 m


The distance the site is from its source

1500 m


The distance from site to the tributary junction where a change in source ID occurs

1100 m


The distance the site is from network mouth

2050 m


The distance the sites source is from network mouth

3550 m

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




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 find positional information about the point. 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.

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.


Output Table Name

The table name, this must be a valid file geodatabase table name, so cannot have spaces, unusual characters or start with a number.

You have no control over its location, it will be stored in the output folder in ..\RivEX_Workspace\Outputs\fGDB_Sites.gdb


Add an attribute index to output

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

  • CHECKED - RivEX will attempt to add an index to the site ID field in the output table.

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

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 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:




The ID of the site to be processed


The catchment ID the site is in


The source ID of the site


The polyline ID the site is snapped to


Percentage along the polyline


The distance the source is from network mouth


The distance the site is from network mouth


The distance the site is from its source


The relative position the site is within the network


The distance to the first upstream tributary junction


The distance to the first downstream tributary junction


The distance to the downstream junction where a change in source ID occurs

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.


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.


  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

    # 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")
        print("No error table created!")
except arcpy.ExecuteError:
    print("FAILED to extract positional data")

Return to top of page