Snap sites to network
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
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 snap to the network. This layer must conform to these specifications:
|
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 |
Search distance (m) |
The snapping distance in metres. This is the distance that the site will use to search for candidate polylines in the river network. The larger the value, the more candidate polylines identified. |
Double |
Avoid nodes |
Indicates if a potential snap should avoid snapping to the end points of a polyline, this is default behaviour and it is recommended you keep it enabled. If this is ticked on and RivEX identifies a snap to the end of the polyline then it moves the result 1% along the length of the line, this ensures the snapped point is not located on a tributary junction. |
Boolean |
Name matching |
The name matching algorithm to use to quality control a snapped point, the options are:
Exact name matching offers the highest quality snap of site to the correct river, but relies of both site and network data having exactly the same naming conventions. |
String |
Name field in site layer |
The text field in the site layer that holds the river name that the site was surveyed at. This parameter is only required if you are using similar or exact name matching. |
Field |
Name field in river network |
The text field in the river network layer that holds the river name. This parameter is only required if you are using similar or exact name matching. |
Field |
Output Feature Class name |
The output Feature Class name. RivEX auto-populates this field using the input site layer name and attaches "_Snapped" to the end of it. You may need to edit it if the site layer name is not file geodatabase compliant. You can of cause completely change if desired. What you cannot change is the location the dataset where it will be saved, this is always ..\RivEX_Workspace\Outputs\fGDB_Sites.gdb |
String |
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.
Field name |
Description of field |
Snapped |
A "Yes" or "No" indicating if the site was snapped or not. |
SnapDist |
The straight line distance that the site was moved to locate it upon the network. If the site fails to snap then this is set to -1. |
ForcedMove |
A "Yes" or "No" field indicating if the site was forced to move the 1% of the polyline length away from the end points of a polyline. |
SnapQual |
A string field containing a line of text indicating what was done. Messages can be:
|
SrchName |
The reduced text extracted from the site layer and used by RivEX to search against the river name field of the network layer. If name matching is not used then default value is "n/a". |
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:
Site name |
River name |
Snap success |
River exe |
River Exe |
|
River Ouze |
River Ouse |
|
R Rother |
rother river |
|
r nidd |
r nidd |
- 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:
Before reduction |
After reduction |
River Amazon |
Amazon |
Rio Janella |
Janella |
Swale R |
Swale |
Master drain |
Master |
R. Orinoco |
Orinoco |
R. Thames (near stone bridge) |
Thames near stone bridge |
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
- 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.
- The site dataset cannot be a in-memory layer.
- The site layer cannot have a join, you either need to remove the join or make it permanent.
- 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.
- 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!")