RivEX

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

Summary

Snaps sites to network, either as a simple proximity or using a more intelligent name matching approach.

Usage

This tool snaps sites to the river network, either as a simple proximity or using a more intelligent name matching approach. Sites derived from GPS or manually entered typically do not align exactly to a river network, the point is not on the line, so it needs to be snapped to the line. Many tools\workflows require the point to be snapped and this tools helps you to achieve this. 

The river network and site data must be in a projected coordinated system as snapping uses linear units for the snap distance.  Data in WGS84 coordinates will be rejected by this tool.  The default mode of this tool is to snap the point to the nearest line in the network. Without any quality control a snap could potentially be quite erroneous. Examples of poor quality snapping could be:

• A GPS locating a survey site nearer to a stream at a tributary junction instead of the actual surveyed site on the main river.
• A user manually entering site data flips digits by mistake and this shifts a site 100Km North onto a river in a an entirely different catchment.

A poorly snapped site could have profound impact on further analyses, for example you are surveying the main stem of a large river but a snap moves the site onto a tiny tributary, in this case the location of the site now has a much smaller catchment area.

RivEX offers the ability to quality control the snap by comparing the site name with the river name. To be able to use this functionality your river network MUST have a text field that holds the river name, the site layer MUST have a text field which holds the name of the river it was meant for. RivEX can do either an exact name match or a similar name match by reducing the sites name down to a shortened string which it then uses to search for in the river name.  A reduced name is a river name with synonyms removed. Thus "Green Creek" is reduced to "Green" and the "R. Amazon" is reduced to "Amazon".

If name matching has been chosen RivEX will skip sites that have empty fields, these are some times referred to as NULL strings. Note a field that appears to be empty may actually contain only space characters, this can happen when manipulating data in other applications (e.g. Excel or Minitab). Under this scenario RivEX will interpret these as names and try to match them (and fail). So always make sure you either have a river name or an empty field when you are snapping with site names.

When using similar name matching you may want to add synonyms specific to your language. You can add/remove synonyms that RivEX attempts to remove through the Admin tool Update River Synonyms. Any updates (additions or removals) to this list are stored in the RivEX_Settings file.

The Site ID field must be a numeric field containing unique ID values.  The FID and Object ID fields are not allowed.  If your point dataset does not contain a unique numeric field then have a look at this web page for how to achieve this with some basic python scripting.

A snap will fail regardless of the name match if the site falls outside the search distance, this is set to a default 100m but can be changed. Increasing this value would mean that more candidate polylines are selected which would need resolving. 

By default RivEX will avoid nodes of the network when snapping, it is recommended that you keep this enabled. If a snap places the site at either end of the polyline it then moves it 1% along the length of the line. This ensures that the site is intersecting one and only one polyline. It is recommended that you keep this checked on.

The output of this tool is a copy of the input site layer with sites either snapped (moved to a polyline) or un-snapped (point remains in original location). A further 5 quality control fields are added to the dataset.

Parameters

Outputs

A site that fails a snap is left as it's original point. The quality control fields will be populated with why it failed. 5 quality control fields are appended to the output point feature class and are described below. 

Output is written to ..\RivEX_Workspace\Outputs\fGDB_Sites.gdb.

To help you understand why RivEX might reject a snap when name matching is used, consider these cases:

• Exact matching will convert all text to lower case before attempting to match and will fail a site if they don't match exactly.  Be aware that spelling mistakes and local variations in the name will fail a site.  Whilst this is a less forgiving method it does ensure the highest quality snap.  A site that has no name (a null string) will not be considered an exact match with a river polyline that has no name.  Examples are:

• Similar name matching attempts to reduce the site's river name to a simplified version.  If this simplified version is found within the river name text encoded into your network layer then this is considered a good quality snap.  If it is not found then the site is rejected.  Be aware site names that include some other descriptive information will be reduce to a string that is very unlikely to be a sub-string within the river name encoded into your network and thus will be rejected.  Examples of name reduction are:

Warnings

The technique used by RivEX is not perfect and can accept/reject sites when the site name is radically different or the name attached to the site contains a synonym within a word used to name the river.

• It could be possible for RivEX to reject a genuine site due to inconsistent naming.  For example a site labelled "R. Lune (near farm)" will be reduced to "Lune near farm" which is not a sub-string of the text "River Lune" encoded into the river network.  The quality control check field SrchName will help you identify this situation.

• Another issue with the sub-string search technique used by RivEX are words that include synonyms themselves.  Thus a site on "Rock River" would be reduced to "Rock" and is a sub-string within a word such as "Brock Lake".  The quality control check field SrchName will help you identify this situation.

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.

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 dataset cannot be a in-memory layer.
3. The site layer cannot have a join, you either need to remove the join or make it permanent.
4. Site data in MULTIPOINT format will be rejected by RivEX. You will need to convert it to the single part form using the Geo-Processing tool Multipart to Singlepart.
5. 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
    fcRivers = r"C:\Scratch\ORN\data.gdb\ORN"

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

    # Run RivEX tool, snap sites to network with 100m, do not use name matching.
    res = arcpy.scrSnapSites_RivEX(fcRivers, fcSites, "SampleID", 100, True, "None", "#", "#", "fcSnapped")

    # The snapped sites, a derived output
    fcSnapped = res.getOutput(0)

    # Count number of sites that did not snap
    n = 0
    with arcpy.da.SearchCursor(fcSnapped, "OBJECTID", "Snapped = 'N'") as cursor:
        for row in cursor:
            n += 1
    print("Number of sites that failed snapping = " + str(n))
except arcpy.ExecuteError:
    print("FAILED searching!")