Summarize network metrics for reach/link polylines

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

Summary

Summarize values encoded in the river network where a reach/link polyline overlaps (traces along) network polylines. Your reach polyline, for example, may represent a survey reach along a river and you wish to summarize data that is encoded in the network layer and optionally group the results by another field. What is encoded into the river network could be one or more attributes such as: water quality, a species count, amount of sediment, terrain metrics such as slope, assets such as weirs/culverts to name but a few.

Please review the worked example that demonstrates the extraction of water quality metrics from a network to better understand the tools' inputs and outputs.

Usage

This tool takes a polyline dataset representing a reach/link/nearby network and uses it to summarize attributes encoded into the river network.

The reach dataset must be in the same coordinate system as the river network and intersect along the river network path. Polylines crossing a river are invalid, they need to "trace along the river". RivEX provides tools for creating reach polylines, but you can provide your own, as along as they trace along the river network.



These reaches trace along the river network, they share a path with the river. Such reaches are valid inputs for this tool as long as they have a unique numeric ID field (not the ObjectID field) and they are in the same coordinate system as the projected river network.	This polyline is not a reach polyline, it crosses the river but does not trace along it. This is an invalid input for this tool.	This polyline initially traces along the network but then 1 or more vertices are offset from the line, then returns to tracing along the river. This is in an invalid input for this tool as the whole reach must intersect the network.

You can choose to process a subset of your reach data if a selection exists and you have ticked on Use only selected polylines.

If a selection exists on the river network this is cleared. You can summarize attributes is a variety of ways: count, minimum, maximum, sum, mean, standard deviation, median, mode, range and concatenate. Optionally you can choose an extra field to group the results by.

RivEX will search for NULL values and warn you if any are found as they are skipped during processing.

If the field Shape_Length is selected as a field to generate metrics (e.g. sum) then it is the length of the lines created by the intersection process that are summed and not the original network polyline lengths. In the image below green points are nodes, river polylines are labelled with their length in blue and the pink reach polyline intersects two river polylines. The sum of length is the sum of the intersectional polylines, not the original length encoded in the network. The dashed lines represent the limits of the intersections and in this case the sum of Shape_Length would report 330m, not 380m.

Computing intersection length

Parameters

Name	Help	Data type
River Network	The river network encoded with information that you wish to summarize using the intersection of overlapping link/reach/nearby network polylines. Any existing selection on the network will be cleared before processing. A network layer in WGS84 or with joins will be rejected by this tool. It is strongly recommended you use a version of your river network stored in a file geodatabase.	Feature Layer
Reach/Link Layer	A polyline layer containing the reaches you wish to use to summarize attributes in the underlying river network. This tool will accept reaches, link lines and nearby networks created by RivEX but you can provide your own polyline dataset. This dataset must be in the same projected coordinate system as the river network and the geometry traces along the river network, i.e. the lines must intersect along the network path. See help for further details.	Feature Layer
Reach/Link ID	A numeric field uniquely identifying the reach/link/nearby network feature. This field must contain unique numbers and cannot be the ObjectID field.	Field
Use only selected polylines	Controls if selections are honoured or cleared. If CHECKED and you have a subset of reach/link features selected only these will be processed. If CHECKED and you have no reach/link features selected then all features will be processed. If NOT CHECKED then RivEX will clear any existing selection on the reach/link feature layer.	Boolean
Network variables to summarize	Select one or more variables and the metrics you wish to compute. RivEX will check these variables and warn you if it discovers any fields containing NULL values. You can select the same variable more than once The variables come from the river network..	Value Table
Group by Field	Optional, select a field from the river network that you wish to group the variables by. For example this might be riparian habitat or river quality.	Field
Output table name	The output table name for your summarized data. You do not have control over the location where this table is created, RivEX controls that, but you can decide its name. The table name must be a geodatabase compliant name, so must not have spaces, other unusual characters or start with a number. Output will be stored in fGDB_Sampling.gdb in the RivEX Workspace Output folder.	String

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

The number of fields in the output table will match your chosen variables that you wish to summarize. Each field name will be tagged with the metric to be calculated. For example if you had selected mean of slope, maximum Strahler order and group by habitat then the output table would contain the following fields: SiteID, Habitat_GroupBy, Slope_Mean and Strahler_Max.

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

The reach/link layer cannot be a in-memory layer.
Reach/link layer must be in the same coordinate system as the river network.
The river network layer will be rejected if there is a join on the layer.

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

# Allow overwrite
arcpy.env.overwriteOutput = True

try:
# Input river Feature Class
fcRivers = r"C:\Scratch\ORN\data.gdb\ORN"

# Reach/link Feature Class
fcReaches = r"C:\Scratch\ORN\RivEX_Workspace\Outputs\fGDB_Sites.gdb\links"

# Run RivEX tool, Summarize network metrics for reach/link polylines.
res = arcpy.scrSummaryStatsByReach_RivEX(fcRivers, fcReaches, "lineID", False, "Strahler_1 Maximum;Pb_Conc Minimum;Pb_Conc Maximum;Pb_Conc Mean", None, "tblResults")

# The summary statistics table, a derived output
tblOutput = res.getOutput(0)

# Return the reach with the largest mean PB concentration
pb = 0
id = -1
with arcpy.da.SearchCursor(tblOutput, ["lineID", "Pb_Conc_Mean"]) as cursor:
for row in cursor:
LID = row[0] # Reach ID
conc = row[1] # Mean Pb concentration for reach
if conc > pb:
pb = conc
id = LID
print("Reach ID " + str(id) + " had the highest mean Pb concentration of " + str(pb) + "mg/L")

except arcpy.ExecuteError:
print("FAILED to extract summary stats!")