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


Name

Help

Data type

River Network

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

Feature Layer

Sites

A point layer for which you want to transfer network data to. 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

A numeric (integer) field that uniquely identifying the sites.


Text, Object ID or FID fields are not accepted.

Field

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.


Boolean

Fields

The fields from the river network you wish to transfer to the site layer. Only standard numeric and text fields are available to transfer.

List [of strings]

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.

Boolean

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.

Boolean

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.

WarningWarnings

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


Return to top of page