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

Summary


Builds reaches centred on input site with optional settings such an extract end points, clipping downstream search to source ID and flipping the direction of the final polyline.

Usage


Requirement for using this tool:


To use this tool you must have attributed the network with:



This tool builds reaches (polylines) from the input site layer in an upstream and downstream direction, with the site being at the centre of the reach. Such reaches could represent the limits of survey sites for which you want to compute slope


Site Centred Reach

5 sites and their centred reaches.

Optional end points have also been extracted


The tool can process all sites or just a subset if a selection exists and you have ticked the Process only selected sites checkbox.  The reach length can be a constant value or a value taken from a numeric field.  Your site layer could potentially have a different downstream reach length for every site, or scaled in some manner (e.g. reach length scaled by Strahler order).  Reach length values must be greater than zero and in metre units. If your network is in units of feet then RivEX will convert the metres value into feet.


It is possible for the desired reach length is not reached and the reach is flagged as Truncated. This happens if the site is close to a network mouth or source or you have ticked on clip by source ID.


If you have ticked on Clip downstream reach to Source ID. RivEX will honour the source ID encoded into the river network, with this option enabled RivEX will stop traversing in a downstream direction when it detects a change in source ID, this will likely truncate the reach.  Further information on the influence of this parameter is found here.


Ticking on Extract reach end points will cause RivEX to extract out the end points (nodes) of the reaches into a separate dataset, this would be useful if you were intending to compute slope of the reach.


If you have ticked on Flip reach direction RivEX will flip the direction of the reach polyline once it has created it, tick this on if you require the reach polyline to flow in a sea to source direction.


An attribute generated for each reach is sinuosity, computed as reach length divided by straight line path, an example is shown below.


Computing sinuosity


If you have chosen to add to map (default) any Error log table created you can optionally get RivEX to construct a relate between it and the site layer to help you locate and deal with any sites that failed to process.  Sites that fail to process are sites that are not intersecting the network or they intersect a network junction, these are skipped and require you to make a decision on which tributary they lie on and you need to move them.

Parameters


Name

Help

Data type

River Network

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

Feature Layer

Site layer

A point layer for which you want to construct a downstream reach. 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 field

This is 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

Reach length generated using

This parameter allows you to switch between generating reaches using a constant length or use distances encoded into a field within the site layer. The options are:


    • A constant value
    • A distance from a field in site layer

String

Distance (m)

If the Reach length parameter was set to A Constant value then this parameter allows you to enter a positive number that is the length of the downstream reach to be built for each site. Values you enter must be greater than zero and represent metres.


Warning: a site may not achieve this length if it is placed near a river network mouth.

Double

Distance field (m)

If the Reach length parameter was set to A Distance from a field in the site layer then this parameter will allow you to choose a numeric field. Values within your chosen field must be greater than zero and represent metres.


Warning: a site may not achieve this length if it is placed near a river network mouth.

Field

Clip downstream reach to source ID

Indicates if RivEX honours the source ID as it travels downstream building the reach:


  • CHECKED - The reach will terminate at a tributary junction if a change in source ID is detected.  This will yield a reach shorter than the desired input value.
  • UNCHECKED (default) - The source ID is ignored and a reach will be built to it's full length if it can be achieved.

Boolean

Extract reach end points

Indicates if RivEX will extract the nodes of the reach:


  • CHECKED - The reach nodes will be written to a separate Feature Class.
  • UNCHECKED (default) - No nodes will be created.


If reach nodes are created then the Feature class will contain the following fields: "SiteID", "WhichEnd", "ReachLngth"

Boolean

Flip reach direction

Indicates if RivEX will reverse of "flip" the reach polyline direction:


  • CHECKED - The reach will be flipped, the polyline will flow in a sea to source direction
  • UNCHECKED (default) - Polyline remains in the direction of flow it was created, this is a source to sea direction

Boolean

Add an attribute index to output

Indicates if RivEX will create an attribute index for the site ID field in the output layers


  • CHECKED - RivEX will attempt to add an index to the site ID field in the output layer(s).
  • UNCHECKED (default) - No index will be added to any output layer(s).


If you plan to join or relate data then it is STRONGLY recommended you create attribute indices for the outputs; an index can significantly speed up query operations.

Boolean

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


The main output of this tool is the reach feature class, if the tool successfully runs and reaches are generated these are added to the active map. You do not have control over the location or name of this dataset. It is written to the file geodatabase fGDB_Sites.gdb which is in the RivEX workspace folder ..\RivEX_Workspace\Outputs\ and the Feature Class takes on the name of site name + "_USDSReaches".  The optional reach nodes datasets is written to the same file geodatabase but uses the output name site name + "_USDS_Reach_Nodes".  If either of these names exist then RivEX adds a numeric suffix to the Feature Class name.


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


The output reach feature class contains the following fields:

Field

Description

SiteID

The Site ID the reach was built from

Direction

The direction the Reach was generated, this is always set to "BOTH" 

Truncated

A Y/N flag to indicate if the reach was truncated

PolylineID

The polyline ID the site was intersecting

Sinuosity

The sinuosity of the reach, this is computed as reach length divided by straight line distance between its end points.


The optional output nodes feature class contains the following fields:


Field

Description

SiteID

The Site ID the reach was built from

WhichEnd

Which end of the reach the node is, this is always either "US" or "DS"

ReachLength

The length of the reach.  This could potentially be shorter than the desired length due to truncation


If you have selected the optional processing task, add attribute index, then the SiteID field in both output datasets will be indexed. An index can significantly speed up query operations such as joins or relates.

WarningWarnings

The network needs to be in units of metres or feet.  Data in decimal degrees will yield invalid output.

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. The site data cannot be a in-memory layer.
  3. Sites must be a simple point feature class, multi-point data is not allowed.
  4. This tool requires your network to be attributed with Source ID.
  5. The site layer must be in the same coordinate system as the river network.
  6. The site layer cannot have a join, you either need to remove the join or make it permanent.


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"

    # Input sites Feature Class
    fcSites = r"C:\Scratch\ORN\RivEX_Workspace\Outputs\fGDB_Sampling.gdb\fcSample_10K_spaced"

    # Run RivEX tool, create a reach 1km upstream and downstream of site, clip to source ID, do not flip, extract end points or build an attribute index
    # WARNING This tool will fail if river data is a layer with a selection! If you need to pass in selections use tool directly from toolbox    
    res = arcpy.scrCentredReaches_RivEX(fcRivers, fcSites, "SampleID", False, "A constant value", 1000, "#", True, False, False, False, False, False)

    # The reach Feature Class, a derived output
    fcReach = res.getOutput(0)

    # The end point Feature Class, a derived output
    fcEndPoints = res.getOutput(1)    

    # The error table
    tblError = res.getOutput(2)

    # 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("No error table created!")
        res = arcpy.GetCount_management(fcReach)
        n = int(res.getOutput(0))
        print("Number of reaches created = " + str(n))
        
except arcpy.ExecuteError:
    print("FAILED to build reaches!")

Return to top of page