Sample with grid

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

Summary

Generate a set number of points within each grid cell.

Usage

RivEX can generate a grid over your network and sample a fixed number of points per grid cell. This is stratified sampling. Such output could feed into further river analysis or compliment a survey strategy.

Stratified sampling using a generated grid

A portion of a network sampled using a grid cell size of 10Km with each cell sampled 3 times

The generated grid is based upon the extent of the river network layer. The maximum X and Y values of the grid extent are rounded up to fit the user specified cell size. This ensures all parts of the network intersect the grid. If your network is in units of feet then cell size and exclusion zone which are entered as metres will be converted into feet.

The tool will attempt to create the specified number of sampling points within each grid cell. It is possible that RivEX fails to achieve the desired sampling number, this is especially true if an exclusion zone was applied during sampling.

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.

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.

Grid Sampling

Parameters

Name	Help	Data type
River Network	The river network. For best results the network should be within a File GeoDatabase	Feature Layer
Cell size (m)	The cell size of the grid to be created. Units are in metres and need to be a positive integer value. Entering a value such as 10,000 will create cells that are 10km by 10 km in size. The grid will be built out from the lower left corner of the network extent.	Double
Keep grid after sampling	A check box to indicate if the grid is kept after the tool has finished running: CHECKED (default) - The grid layer will be kept and stored in the sampling file geodatabase along with the sampling points. The Feature class name is constructed using the naming logic of riv_cellsize_XXXm where riv is the name of your river network and XXX was your chosen cell size. NOT CHECKED - The grid layer will be deleted at the end of the tool run.	Boolean
Number of sampling points to create	The number of sampling points to be created in each grid cell. This needs to be a positive integer value.	Long
Output feature class name	The output Feature class name for your sampling point dataset. You do not have control over the location where this dataset is created, RivEX controls that, but you can decide its name. The Feature Class name must be a geodatabase compliant name, so must not have spaces, other unusual characters or start with a number.	String
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 grid cell that the sampling point was created within.

If you have chosen to keep the sampling grid then this layer will contain the following fields to help you quality control and understand bias in the data:

Field	Description
CellID	A unique numeric ID number given to the grid cell
Centroid_X	The centroid X coordinate of the grid cell
Centroid_Y	The centroid Y coordinate of the grid cell
Count	Number of sampling points in the grid cell. This may be less that the specified number due to RivEX being unable to place a point on the network
SumNetLength	The total length of river network within the grid cell. Units will be in the same units as the network, typically in metres or feet.

The grid layer will be stored in the sampling file geodatabase along with the sampling points. The Feature class name is constructed using the naming logic of riv_cellsize_XXXm where riv is the name of your river network and XXX was your chosen cell size.

If you have selected the optional processing task, add attribute index, then the SampleID and CellID fields in the output datasets 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.

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 you are using an exclusion zone, the exclusion test occurs within the grid cell. Samplings points are guaranteed to be at least the distance you specify within the cell but can be within the exclusion distance to points in adjacent cells.

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"

# Run RivEX tool, create a 100km x 100km grid and sample 5 times in each cell, keep grid.
res = arcpy.scrSamplingByGrid_RivEX(fcRivers, 100000, True, 5, "fcSample_100km_5", False, True, "#", False)

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

# The grid, a derived output
fcGrid = res.getOutput(1)

# Count how many grid cells attained 5 sampling points
arcpy.MakeFeatureLayer_management(fcGrid, "LYRGRID")
arcpy.SelectLayerByAttribute_management("LYRGRID", "NEW_SELECTION", "Count = 5")
res = arcpy.GetCount_management("LYRGRID")
n = int(res.getOutput(0))
print(str(n) + " grid cells achieved sampling density of 5")

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