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