RivEX

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

Summary

Transfers fields encoded into the river network to the point layer. Specific RivEX fields are corrected for the sites location along the polyline.

Usage

This tool transfers data encoded into the river network to the site layer. Only sites that intersect the river network are processed, failed sites are listed in the error log table (tblFailedSites_NetworkTransfer) which can be optionally loaded into the map for convenience.

Input sites must be snapped to the network and have a unique numeric ID (RivEX does not accept the Object ID field as input). You can choose to process a subset of sites if they have been selected and you have ticked on the appropriate parameter.  Sites must be a simple point feature class, multi-point data is not allowed.

You can think of this tool as doing a spatial join without the need of creating a new dataset.

Sites that failed to intersect the network are given a "-1" value for all the user chosen fields, except in the case where the field to transfer is a text field of 1 character long, in that case it is simply set to "-" as "-1" would be two characters and 2 is larger than 1!

If the user chosen fields include the RivEX fields Distance to network mouth or Total upstream length then these are adjusted based upon the sites location along the polyline.

If you are transferring a field from the river network and a field already exists in the site layer with the same name then the transferred field name has a numeric suffix added, e.g. SourceID would become SourceID_1.

Parameters

Outputs

An update point layer with all the fields selected by the user transferred to the site layer. The RivEX fields distance to network mouth and upstream length are adjusted to the correct value by the sites location along the intersecting polyline.

If errors were generated then this tool creates a stand alone table named tblFailedSites_NetworkTransfer.  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

For error free processing it is strongly recommended that your river network and site layer are File GeoDatabase Feature Classes to avoid any field schema issues.

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. If a selection exists on the river network this is cleared before processing continues.
3. The site dataset cannot be a in-memory layer.
4. The site layer must be in the same coordinate system as the river network.
5. The site layer cannot have a join, you either need to remove the join or make it permanent.
6. Site layer must not be a MULTIPOINT geometry.
7. Site layer must not be a compressed dataset.

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
    fcRiver = r"C:\Temp\ORN\ORN.gdb\ORN"

    # Input site Feature Class
    fcSites = r"C:\Temp\ORN\ORN.gdb\ORN_Sampled_100m"

    # Run RivEX tool, transferring 3 network attributes to sites
    # 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.scrTransferNetworkMetrics_RivEX(fcRiver, fcSites, "SampleID", False, "CatchID;Strahler;Shreve", False, False)

    # The rivers Feature Class, a derived output
    fcSites = 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")
    else:
        print("Data transfered without error.")
except arcpy.ExecuteError:
    print("FAILED to transfer data from network to sites")