Accumulate network attribute

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

Summary

Assigns to each polyline within the network the total upstream accumulation of an attribute encoded in the river network. Such a value could be a hydrological value, number of structures, species diversity, a score to fish migration, in fact any numeric value that makes sense when accumulated.

Usage

This tool creates a new stand alone table recording for each polyline the upstream accumulation of a user chosen numeric attribute encoded in the river network. If a selection exists on the river network this is cleared. If the chosen attribute contains NULL values these are interpreted as zero.

Initial network values

Accumulated network values

A network encoded with a value you wish to accumulate. Note this dataset has zero values and NULL data.

The network showing its accumulated values. Null values

have been converted to zero.

If the river network is single threaded (contains no loops) then this tool uses an algorithm which will process the entire river network in a very fast and efficient manner. If the network contains any loops then the tool swaps to an alternative algorithm which uses a BRUTE FORCE approach to accumulating the values. This means large networks ( > 200,000 polylines) will take significantly longer to process. For example a network composed of 500,000 polylines will take approximate 2-3 hours to complete. The brute force approach is required as braided networks have multiple paths and this algorithm ensures the network is reliably encoded.

Optional Processing

If you tick on Join output table to network then RivEX will join the output table to the river network, permanently transferring the fields to the river network.

Parameters

Name	Help	Data type
River Network	The river network. For best results the network should be within a File GeoDatabase	Feature Layer
Attribute to accumulate	The field encoded into the river network you wish to accumulate across the network. Field must be numeric. Null values are interpreted as zero.	Field
Output field name	The field name you give for the accumulate value. Choose a meaningful name. The field name can not be longer than 10 characters.	String
Output table name	The 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_Network.gdb	String
Join output table to network	Join the output table to the river network. Useful if want to visualise the network with the accumulated value or do further processing. This is a permanent transfer of fields to the river network, so not an in-memory join. CHECKED - Output table is joined to the river network UNCHECKED (default) - RivEX does not join the table	Boolean

Outputs

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

The output table contains the following fields, XXX is the output field name entered by user.

Field	Description
RivID	The unique ID for the polyline.
XXX	The accumulated value, these are all the values upstream summed and includes the polyline itself.
XXX_Min	The minimum upstream value encountered.
XXX_Max	The maximum upstream value encountered.
XXX_Count	The number of polylines upstream, includes the polyline itself.
XXX_NullCount	The number of polylines upstream that had a NULL value, includes the polyline itself.
XXX_Mean	The mean upstream value computed for all upstream polylines. This is XXX / XXX_Count.
XXX_NullMean	The mean upstream value computed for all non-NULL upstream polylines. This is XXX / (XXX_Count - XXX_NullCount).

Warnings

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

River layer must not have a table join.
If the input river network contains loops (i.e. it is multi-threaded) then processing algorithm must swap to a brute force approach to ensure network is attributed correctly. Large networks will take correspondingly longer to process. If your network is composed of +500,000 polylines then expect this tool to run for at least 2 - 3 hours.
To avoid possible invalid field names, the output field name is limited to 10 characters in length.

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"

# Run RivEX tool. Accumulate field "Pb_Conc" into Accum_pb. Do not join output table to river network
res = arcpy.scrAccumulateAttribute_RivEX(fcRivers, "Pb_Conc", "Accum_Pb", "tblLeadPollution", False)

# The accumulation table, a derived output
tblAccum = res.getOutput(0)

# Get accumulation for a specific polyline of interest and print
with arcpy.da.SearchCursor(tblAccum, "Accum_Pb", "RivID = 7392") as cursor:
for row in cursor:
acc = row[0]
print("Total amount of upstream lead pollution = " + str(acc))
except arcpy.ExecuteError:
print("FAILED accumulating!")