Functions
	sgspy.stratify.map.map.map (*tuple[SpatialRaster, int\|str\|list[int]\|list[str], Optional[int\|list[int]]] args, str filename='', int thread_count=8, dict driver_options=None)
	This function conducts mapping on existing stratifications.

Detailed Description

Function Documentation

◆ map()

sgspy.stratify.map.map.map	(	*tuple[SpatialRaster, int\|str\|list[int]\|list[str], Optional[int\|list[int]]]	args,
		str	filename = '',
		int	thread_count = 8,
		dict	driver_options = None )

This function conducts mapping on existing stratifications.

The pre-existing stratifications are passed in the form of a raster, band. The bands argument specifies which bands within the raster should be used. If the bands argument is omitted, all of the bands in the raster are mapped.

IMPORTANT If the strat raster IS NOT the return value of one of the other sgspy stratification functions, an additional argument MUST be passed: the number of strata. The bands argument MUST be passed as well if this is the case, even if you wish to have every band be mapped. The reason the number of strata must be passed is because this value is necessary for calculation (it is not required if the strat raster IS the return value of an sgspy stratification function because during calculation this number is automatically stored). The num_strata argument, if required, should be set to the value of the largest strata + 1. For example if the strata are [0, 1, 2, 3, 4] then num_strata should be 5. If the strata are [1, 2, 4] then num_strata should still be 5. If the strata are [0, 1, 2, 3] then num_strata should be 4.

the arguments are passed in the form of a tuple, and there can be any number of tuples passed. For example, the following are valid:

map(srast1) #if all bands in srast1 should be mapped
map(srast1, srast2) #if all bands in srast2 should be mapped
map((srast1, bands1))
map((srast1, bands1), (rast1, bands2))
map((srast1, bands1, num_strata1)) #if rast1 is NOT the return value of an sgspy stratification function.
map((srast1, bands1, num_strata1), (srast2, bands2, num_strata2)) #if rast1 and rast2 are NOT the return values of sgspy stratification functions.

the raster within the tuple MUST be of type sgs.utils.SpatialRaster. The bands argument MUST be:

an int, specifying a single band in the strat raster.
a str, specifying a single band in the strat raster.
a list of ints or strs, each specifying a band in the strat raster.

The num_strata argument, if required, MUST be:

an int, if bands argument is an int or string, specifiying the max strata value in a specific band.
a list of ints, if bands argument is a list, each entry specifying the max strata value in that band.

the filename parameter specifies an output file name. Right now the only file format accepted is GTiff (.tiff).

The thread_count parameter specifies the number of threads which this function will utilize in the case where the raster is large an may not fit in memory. If the full raster can fit in memory and does not need to be processed in blocks, this argument will be ignored. The default is 8 threads, although the optimal number will depend significantly on the hardware being used and may be more or less than 8.

the driver_options parameter is used to specifiy creation options for the output raster, such as compression. See options fro GTiff driver here: https://gdal.org/en/stable/drivers/raster/gtiff.html#creation-options The keys in the driver_options dict must be strings, the values are converted to string. THe options must be valid for the driver corresponding to the filename, and if filename is not given they must be valid for the GTiff format, as that is the format used to store temporary raster files. Note that if this parameter is given, but filename is not and the raster fits entirely in memory, the driver_options parameter will be ignored.

Examples

rast = sgspy.SpatialRaster("rast.tif")
breaks = sgspy.stratify.breaks(rast, breaks={'zq90': [3, 5, 11, 18], 'pzabove2': [20, 40, 60, 80], 'zsd':[1, 2, 3]})
quantiles = sgspy.stratify.quantiles(rast, quantiles={'zsd': 25})
srast = sgspy.stratify.map((breaks, ['strat_zq90', 'strat_pzabove2']), quantiles) #only using 2 bands of the breaks raster

rast = sgspy.SpatialRaster("rast.tif")
breaks = sgspy.stratify.breaks(rast, breaks={'zq90': [3, 5, 11, 18], 'pzabove2': 20, 40, 60, 80})
quantiles = sgspy.stratify.quantiles(rast, quantiles = {'zsd': 25})
srast = sgspy.stratify.map(breaks, quantiles) #using all bands in each raster

rast = sgspy.SpatialRaster("rast.tif")
inventory = sgspy.SpatialVector("inventory_polygons.shp")
breaks = sgspy.stratify.breaks(rast, breaks={'zq90': [3, 5, 11, 18], 'pzabove2]: [20, 40, 60, 80]})
poly = sgspy.stratify.poly(rast, inventory, attribute="NUTRIENTS", layer_name="inventory_polygons", features=['poor', 'medium', 'rich'])
srast = sgspy.stratify.map((breaks, [0, 1]), (poly, 0), filename="mapped_srast.tif", driver_options={"COMPRESS", "LZW"})

#Some pre-existing strat raster(s)
breaks = sgspy.SpatialRaster("breaks.tif")
quantiles = sgspy.SpatialRaster("quantiles.tif")
#give an extra argument, the number of strata, for each strat raster, because sgspy does not know from previously creating that sraster.
mapped = sgspy.stratify.map((breaks, ['strat_zq90', 'strat_pzabove2'], [5, 5]), (quantiles, 'strat_zsd', 25))

#Another example with pre-existing strat raster(s) rast = sgspy.SpatialRaster("rast.tif")
breaks = sgspy.SpatialRaster("breaks.tif")
poly = sgspy.SpatialRaster("poly.tif")
#give an extra argument, the number of strata, for each strat raster, because sgspy does not know from previously creating that sraster.
srast = sgspy.stratify.map((breaks, [0, 1], [5, 5]), (poly, 0, 3))

Parameters

*args : tuple[SpatialRaster, int|list[int]|list[str], Optional[int|list[int]]]
tuples specifying raster bands and their number of stratifications

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

thread_count : int
the number of threads to use when multithreading large images

driver_options : dict[str]
the creation options as defined by GDAL which will be passed when creating output files

Returns

a SpatialRaster object containing a band of mapped stratifications from the input raster(s).