Functions
	sgspy.sample.clhs.clhs.clhs (SpatialRaster rast, int num_samples, int iterations=10000, Optional[SpatialVector] access=None, Optional[str] layer_name=None, Optional[int\|float] buff_inner=None, Optional[int\|float] buff_outer=None, Optional[SpatialVector] existing=None, int replace=None, bool plot=False, str filename='')
	This function conducts Conditioned Latin Hypercube Sampling, see the following article for an in depth description of the method itself:

Detailed Description

Function Documentation

◆ clhs()

sgspy.sample.clhs.clhs.clhs	(	SpatialRaster	rast,
		int	num_samples,
		int	iterations = 10000,
		Optional[SpatialVector]	access = None,
		Optional[str]	layer_name = None,
		Optional[int \| float]	buff_inner = None,
		Optional[int \| float]	buff_outer = None,
		Optional[SpatialVector]	existing = None,
		int	replace = None,
		bool	plot = False,
		str	filename = '' )

This function conducts Conditioned Latin Hypercube Sampling, see the following article for an in depth description of the method itself:

Minasny, B. and McBratney, A.B. 2006. A conditioned Latin hypercube method for sampling in the presence of ancillary information. Computers and Geosciences, 32:1378-1388.

The number of output samples is decided by the 'num_samples' parameter. The 'iterations' parameter indicates the number of iterations the simulated annealing portion of the clhs algorithm will undertake in the case where a perfect latin hypercube is not found. A higher number of iterations may result in a more representative sample, although the standard value recommended by Misany and McBratney is 10000.

The access parameter may be given to restrict the areas where sampling may occur. The algorithm will still attempt to find a latin hypercube representative across the entire feature space, not just the accessible pixels. The access vector may contain geometries of type LineString or MultiLineString. buff_outer specifies the buffer distance around the geometry which is allowed to be included in the sampling. buff_inner specifies the buffer distance around the geometry which is not allwoed to be included in the sampling. buff_outer must be larger than buff_inner. For a multi layer vector, layer_name must be specified.

The 'existing' parameter may be given in order to specify an existing sample plot network. All points of the whole existing plot network will be added first, then remaining points will be added as defined by the CLHS algorithm. The 'replace' parameter may also be set to a positive number, if so the worst samples in the existing sample network will be removed (up to 'replace' number of them) before moving on to adding remaining points as defined by the CLHS algorithm. The worst samples are those which are in the most over-represented areas of the sample space. There may be less than 'replace' number of samples replaced, if each point in the remaining existing samples is not over-represented at all.

The output is an object of type sgspy.SpatialVector which contains the chosen sample points.

Examples

rast = sgspy.SpatialRaster("raster.tif")
samples = sgspy.sample.clhs(rast, num_samples=250)

rast = sgspy.SpatialRaster("raster.tif")
samples = sgspy.sample.clhs(rast, num_samples=250, plot=True, filename="clhs_samples.shp")

rast = sgspy.SpatialRaster("raster.tif")
access = sgspy.SpatialVector("access_network.shp")
samples = sgspy.sample.clhs(rast, num_samples=200, access=access, buff_outer=300)

rast = sgspy.SpatialRaster("raster.tif")
access = sgspy.SpatialVector("access_network.shp")
samples = sgspy.sample.clhs(rast, num_samples=200, access=access, buff_inner=50, buff_outer=300)

rast = sgspy.SpatialRaster("raster.tif")
existing = sgspy.SpatialVector("existing_network.shp")
samples = sgspy.sample.clhs(rast, num_samples=250, existing=existing)

rast = sgspy.SpatialRaster("raster.tif")
existing = sgspy.SpatialVector("existing_network.shp")
samples = sgspy.sample.clhs(rast, num_samples=250, existing=existing, replace=100)

Parameters

rast : SpatialRaster
raster data structure containing input raster bands

num_samples : int
the target number of samples

iterations : int
the number of iterations in the clhs algorithms

access : SpatialVector
a vector specifying an access network

layer_name : str
the layer within the access network which will be used for sampling

buff_inner : int | float
buffer boundary specifying distance from access geometries which CANNOT be sampled

buff_outer : int | float
buffer boundary specifying distance from access geometries which CAN be sampled

existing : SpatialVector
a vector specifying an existing sample network

replace : int
the number of existing sample plots which it is okay to remove and replace

plot : bool
whether to plot the output samples or not

filename : str
the filename to write to, or '' if file should not be written

Returns

a SpatialVector object containing point geometries of sample locations