Sample with polygons

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

Summary

Generate a constant\variable number of points within each polygon.

Usage

RivEX can stratify sampling based upon a user supplied polygon layer. This tool is ideal for generating a layer of random points across a network grouped by polygon or a sub-set identified by an existing selection on the polygon layer. Such output could feed into further river analysis or compliment a survey strategy based upon catchment or administrative boundaries.

Stratified sampling using an exist polygon layer

3 sampling points per polygon. The points are labelled with the polygon ID

The tool will attempt to create the specified number of sampling points within each polygon. The sampling points are constructed from the section of river network that intersects the polygon, so it is possible for a small fragment of the network to fall within a polygon and under this scenario RivEX can fail to achieve the desired sampling number, this is especially true if an exclusion zone was applied during sampling. If your network is in units of feet and you have set the exclusion zone distance, then RivEX will convert the metres value into feet.

You have a variety of options that can influence (bias) the selection process and it is important that you understand these. Click here to review these options. Avoid sampling nodes is ticked on as default.

The number of sampling points created per polygon can be a fixed number or a count derived from a numeric field in the polygon dataset. The polygon layer must have a numeric (integer) ID field (which can't be the ObjectID) that uniquely identifies each polygon. The user can choose to process only a subset of selected polygons if they wish.

If the tool was run from within ArcPro the output Feature Class, if successfully created, will be added to the map symbolized as small black circles.

Sampling with polygons

Parameters

Name	Help	Data type
River Network	The river network. For best results the network should be within a File GeoDatabase	Feature Layer
Polygon layer	The polygon layer used to sample the network, could be administrative or catchment area polygons.	Feature Layer
Polygon ID field	A numeric field uniquely identifying the polygon. This field must contain unique numbers and cannot be the ObjectID field.	Field
Use only selected polygons	The number of sampling points to be created in each grid cell. This needs to be a positive integer value.	Boolean
Sample count come from	You must choose where the sampling number per polygon will come from. You have two choices: Fixed number Field in polygon layer	String
Fixed number	If the parameter Sample Count Come From is set to Fixed number then this parameter enables. You must enter an integer value greater than zero. RivEX will attempt to sample each polygon this number of times.	Long
Field	If the parameter Sample Count Come From is set to Field in polygon layer then this parameter enables. You must choose the numeric field that holds the count that will define how many times the polygon will be sampled by RivEX. Values must be greater than zero.	Field
Output feature class name	Controls if selections are honoured or cleared: If CHECKED and you have a subset of polygon selected only these will be sampled. If CHECKED and you have no polygons selected then all polygons will be sampled. If NOT CHECKED then RivEX will clear any existing selection on the polygon layer.	String
Write count and length back to polygon layer	Controls if RivEX is allowed to create fields in the input polygon layer recording useful statistics. If CHECKED RivEX will add a Count and SumNetLength field to the polygon layer which records the actual number of sampling points created and the total length of network within the polygon. If NOT CHECKED RivEX will not add these fields to the polygon layer.	Boolean
Avoid sampling same location on polyline	Controls if RANDOM sampling is allowed to create points at the same location: If CHECKED, RivEX will not generate stacked points, each point will be a unique location along the length of the polyline, this is default. If NOT CHECKED, RivEX may (by chance) randomly sample the same location along the length of the polyline and this will lead to stacked sampling points.	Boolean
Avoid nodes	Controls if RivEX is allowed to to sample at the ends (nodes) of the polyline: If CHECKED RivEX will avoid creating points at the ends of the polylines. This is Default. If NOT CHECKED then RivEX could potentially create, by chance, points at the ends of the polylines. It is recommended that you CHECK this option as it avoids sampling points being created a tributary junctions which themselves cause subsequent issues.	Boolean
Apply exclusion zone (m)	If a value greater than zero is entered, then this applies an exclusion zone around the point as it is generated. If other existing sampling points are found within the zone then the sampling point is rejected and RivEX attempts to create another. This process is repeated up to 200 times before RivEX bails out. Be aware creating large exclusion zones on small networks will quickly exhaust sampling space and RivEX will fail to create the required number of points.	Double
Add an attribute index to output	Indicates if RivEX will create an attribute index for the sample ID field in the output layers CHECKED - RivEX will attempt to add an index to the sample 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

Outputs

The output is written to a File GeoDatabase called fGDB_Sampling.gdb which is stored in the Outputs folder in the RivEX Workspace. You can control the name of the Feature Class but not its location. The output name must be a valid file geodatabase name. The output point dataset will contain the following fields:

Field	Description
SampleID	A unique numeric ID number given to the sampling point.
PolylineID	The Polyline ID number the sampling point was generated upon.
X_Coord	The X coordinate of the sampling point.
Y_Coord	The Y coordinate of the sampling point.
LineLength	The length of the polyline being sampled. Units will be in the same as the network, typically in metres or feet.
Per_Along	The percentage length along the line the sampling point is. Measured from the FROM end of the polyline.
Dist_Along	The distance along the line the sampling point is. Measured from the FROM end of the polyline.
PolygonID	The ID of the polygon that the sampling point was created within.

If Write count and length back to polygon layer is ticked on then RivEX will add a Count and SumNetLength field to the polygon layer which records the actual number of sampling points created and the total length of network within the polygon. You can uses these statistics to quality control and understand any bias introduced into the sampling.

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

Warnings

RivEX will attempt to locate a random point but if it fails it will try up to 200 times. If after the 200th attempt it is still unsuccessful it will bail out. This scenario can occur when for example you have included an exclusion zone around each point, but this was set so large that no other points could be placed on the same network.

A limitation of this tool run in a script is that it only accepts feature classes for the polygon 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

This tool will reject river networks that do not have linear units. Networks in latitude/longitude will be rejected.
Any selection on the network is cleared prior to sampling.
If the network has a join (spatial or attribute) then this tool aborts and you must remove the joins.
Polygon layer must be in the same coordinate system as the river network.
If you are using an exclusion zone, the exclusion test occurs within the polygon. Samplings points are guaranteed to be at least the distance you specify within the polygon but can be within the exclusion distance to points in adjacent polygons.

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 catchment polygon layer
fcCatchments = r"C:\Scratch\ORN\data.gdb\catchments"

# Run RivEX tool, sample 10 times per polygon applying a 250m exclusion zone around each point as it is placed.
# The exclusion might cause the polygon to fail to achieve the desired sample of 10.

# WARNING This tool will fail if polygon data is a layer with a selection! If you need to pass in selections use tool directly from toolbox
res = arcpy.scrSamplingByPolygon_RivEX(fcRivers, fcCatchments, "PID", False, "Fixed number", 10, "#", "fcSample_5_byPolygon", False, False, True, 250, False)

# The sampling point Feature Class, a derived output
fcSample = res.getOutput(0)

# Count how many sampling points were created
res = arcpy.GetCount_management(fcSample)
n = int(res.getOutput(0))
print(str(n) + " sampling points were created in total")

except arcpy.ExecuteError:
print("FAILED to sample network!")