RivEX

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

Summary

This tool builds links between pairs of sites. A link is a single path connecting the two sites. You can use these to visualise the path taken by a species or ask further spatial questions such as what riparian habitat was passed? Sites could represent in-channel barriers, pollution inputs, invertebrate or fish surveys. Whilst knowing the distance is an important metric the true value of these links is having a geometry (polyline) which you can visualise or use to buffer/select/query other spatial datasets.  Take note of the warning if you are using large number of sites.

Usage

Requirement for using this tool:

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

• Catchment ID

This tool takes two point layers and builds links between pairs of sites. A link is a single path connecting the two sites.  The output is a polyline Feature Class recording the link as a polyline along with site ID's. As an optional processing task, RivEX can join all fields from the site layers to the link layer.

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 a text field or the Object ID field). You can choose to process a subset of FROM sites if they have been selected and you have ticked on Use only selected sites in from layer. If this is left unchecked and you have a selection in the FROM layer this will be cleared.

Your search FROM and TO layer can be the same layer and if this situation occurs then you can alter how RivEX loops over the sites by changing the parameter Input site layers are the same layer, compute sites, the default is Combinations. Review the examples in the table below to understand the various scenarios which lead to different outputs.

RivEX will first identify which catchment a site falls within. If sites are found which are not snapped to the river network these are rejected and logged in the error log table. The remaining sites are sorted into their respective catchment ID's and only sites in the same catchment ID are linked. This avoids RivEX attempting to build links between pairs of sites that would never link.

Four FROM sites (green) in two catchments linking to 6 TO sites (orange).

In the example image above if all of the 4 FROM sites (green) were in the same catchment as the 6 TO sites (orange) then RivEX would build 24 links. In this example we see the 4 green sites are actually distributed over two catchments each with 2 FROM sites and 3 TO sites. RivEX only links pairs of sites within a catchment so in this case the total number of links would be12; the attribute table of the output Feature Class is shown below.

The links attribute table from the example data above, each FROM site

has linked to the 3 TO sites generating 12 links in total.

You can alter the behaviour of RivEX and generate links between pairs of sites with matching ID's, for example upstream and downstream site limits. This scenario is only valid when:

• The FROM and TO layers are different datasets
• The FROM and TO site ID's share a common ID, typically a survey reach ID.
• You have ticked on optional processing parameter Build link only when From and To site ID's match.

With the option "Build link only when From and To site ID's match" checked on and  both layers are different datasets 

then link polylines are built between paired site ID's. 1 links to 1, 2 links 2, 3 to 3 and so forth. Green From sites 6, 7 & 8

are in a different catchment and thus unable to link to their respective To red sites.

If sites are stacked (points with the same XY coordinates) RivEX warns you and continues to process them.  If the FROM and TO pair of sites are the same coordinates then RivEX returns in the output Feature Class a NULL polyline.  This can be easily identified as it has a zero length.

Depending upon why you are linking specific sites you may want to flip the direction of the link polyline as that provides a more meaningful direction for your analysis. To flip polylines ensure the appropriate checkbox under the optional processing group is ticked on.

If a simple loop where both edges have the same from and to-node ID's is encountered then RivEX will always follow the edge with the shortest length.

Parameters

Outputs

The output Feature Class can be given a name but you have no control over where it is stored, this would be in the file geodatabase ..\RivEX_Workspace\Outputs\fGDB_Sites.gdb

Length of links (the Shape_Length field) are in the units of the river network. 

The output table contains the following fields:

If errors were generated then this tool will create two stand alone tables named tblLinkSiteErrorsFrom or tblLinkSiteErrorsTo.  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

Be aware large number of sites will create very large combinations of paired sites which RivEX will attempt to create links between. For example a FROM dataset with 100 sites is linked to a TO dataset with 100 sites, all sites within the same catchment. This will generate 10,000 combinations! Even larger number of sites can quickly lead into millions of combinations and will take many hours to process. When RivEX identifies number of combinations greater than 1,000 it will warn you and track progress in 10% steps. You may decide to abort processing if the choice is numerically large.

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. Sites must be a simple point feature class, multi-point data is not allowed.
2. Site layers with table joins are rejected, solution is to remove join before using tool.
3. Site ID fields must contain unique ID's.

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"
    
    # FROM and TO site Feature Class
    fc_FROM_Sites = r"C:\Scratch\ORN\RivEX_Workspace\Outputs\fGDB_Sampling.gdb\fcSalmonSurveySites"
    fc_TO_Sites = r"C:\Scratch\ORN\RivEX_Workspace\Outputs\fGDB_Sampling.gdb\fcBarriers"

    # Run RivEX tool, link salmon with barrier sites, join site data to 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.scrLinkSites_RivEX(fcRivers, fc_FROM_Sites, "SalmonID", False, fc_TO_Sites, "BarrierID", "fcLinks", False, False, True, "Combinations", False, False)

    # The links feature class
    fcLinks = res.getOutput(0)

    # The error table
    tblError = res.getOutput(1)
    
    # Return the longest link, note FromSiteID, ToSiteID are default field names in output FeatureClass
    with arcpy.da.SearchCursor(fcLinks, ["Shape_Length", "FromSiteID", "ToSiteID"], sql_clause=(None, "ORDER BY Shape_Length DESC")) as cursor:
        for row in cursor: # Get first row, this will be the longest
            print("FROM " + str(row[1]) + " - TO " + str(row[2]) + " = " + str(row[0]))
            break
except arcpy.ExecuteError:
    print("FAILED to link sites!")