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


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


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

Whats calculated

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

Mouths in network issue

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.




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 the source of each 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


Build route to source

This is an optional task that will create a polyline feature class containing the routes to source. The name of the dataset is built from your mandatory source table name. 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


Flip direction of route

Valid only if build routes has been selected:

  • CHECKED - The route will be flipped such that the direction of the polyline is from site to source.
  • UNCHECKED (default) - The route will have the direction of the polyline as it is created which is source to site.


Add an attribute index to output

Indicates if RivEX will create an attribute index for the site ID fields in the output tables.

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

  • 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.

The output table contains the following fields:




The ID of the site that was searched


The catchment ID the site is in


The source ID of the site


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 polyline ID the site is snapped to

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:




The ID of the site that the route was created for


The source ID of the site

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.


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.


  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

    # 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!")

Return to top of page