RSGISLib Zonal Stats Module¶

The zonal stats module provides functions to perform pixel-in-polygon or point-in-pixel analysis.

For undertaking a pixel-in-polygon analysis you need to consider the size of the polygons with respect to the size of the pixels being intersected.

Where the pixels are small with respect to the polygons so there is at least one pixel within the polygon then the best function to use is:

rsgislib.zonalstats.calcZonalBandStats

If the pixels are large with respect to the polygons then use the following function which intersects the polygon centroid.

rsgislib.zonalstats.calcZonalPolyPtsBandStats

If the pixel size in between and/or polygons are varied in size such that it is not certain that all polygons will contain a pixel then the following function will first attempt to intersect the polygon with the pixels and if there is not a pixel within the polygon then the centriod is used.

rsgislib.zonalstats.calcZonalBandStatsTestPolyPts

Alternatively, the other functions are slower to execute but have more options with respect to the method of intersection. The options for intersection are:

METHOD_POLYCONTAINSPIXEL = 0 # Polygon completely contains pixel
METHOD_POLYCONTAINSPIXELCENTER = 1 # Pixel center is within the polygon
METHOD_POLYOVERLAPSPIXEL = 2 # Polygon overlaps the pixel
METHOD_POLYOVERLAPSORCONTAINSPIXEL = 3 # Polygon overlaps or contains the pixel
METHOD_PIXELCONTAINSPOLY = 4 # Pixel contains the polygon
METHOD_PIXELCONTAINSPOLYCENTER = 5 # Polygon center is within pixel
METHOD_ADAPTIVE = 6 # The method is chosen based on relative areas of pixel and polygon.
METHOD_ENVELOPE = 7 # All pixels in polygon envelope chosen
METHOD_PIXELAREAINPOLY = 8 # Percent of pixel area that is within the polygon
METHOD_POLYAREAINPIXEL = 9 # Percent of polygon area that is within pixel

class rsgislib.zonalstats.ZonalAttributes(minThreshold=None, maxThreshold=None, calcCount=False, calcMin=False, calcMax=False, calcMean=False, calcStdDev=False, calcMode=False, calcSum=False)¶: Object, specifying which stats should be calculated and minimum / maximum thresholds. This is passed to the pixelStats2SHP and pixelStats2TXT functions.

class rsgislib.zonalstats.ZonalBandAttributes(band=0, basename='band', minThres=None, maxThres=None, calcCount=False, calcMin=False, calcMax=False, calcMean=False, calcStdDev=False, calcMode=False, calcMedian=False, calcSum=False)¶: Object, specifying which band, the band name and stats should be calculated and minimum / maximum thresholds. This is passed to the polyPixelStatsVecLyr function.

rsgislib.zonalstats.calcZonalBandStats(veclyr, valsimg, imgbandidx, minthres, maxthres, calcZonalBandStats, minfield=None, maxfield=None, meanfield=None, stddevfield=None, sumfield=None, countfield=None, modefield=None, medianfield=None)¶

A function which calculates zonal statistics for a particular image band. If you know that the pixels in the values image are small with respect to the polygons then use this function.

Parameters

veclyr – OGR vector layer object containing the geometries being processed and to which the stats will be written.
valsimg – the values image
imgbandidx – the index (starting at 1) of the image band for which the stats will be calculated. If defined the no data value of the band will be ignored.
minthres – a lower threshold for values which will be included in the stats calculation.
maxthres – a upper threshold for values which will be included in the stats calculation.
out_no_data_val – output no data value if no valid pixels are within the polygon.
minfield – the name of the field for the min value (None or not specified to be ignored).
maxfield – the name of the field for the max value (None or not specified to be ignored).
meanfield – the name of the field for the mean value (None or not specified to be ignored).
stddevfield – the name of the field for the standard deviation value (None or not specified to be ignored).
sumfield – the name of the field for the sum value (None or not specified to be ignored).
countfield – the name of the field for the count (of number of pixels) value (None or not specified to be ignored).
modefield – the name of the field for the mode value (None or not specified to be ignored).
medianfield – the name of the field for the median value (None or not specified to be ignored).

rsgislib.zonalstats.calcZonalBandStatsFile(vecfile, veclyrname, valsimg, imgbandidx, minthres, maxthres, out_no_data_val, minfield=None, maxfield=None, meanfield=None, stddevfield=None, sumfield=None, countfield=None, modefield=None, medianfield=None)¶

A function which calculates zonal statistics for a particular image band. If you know that the pixels in the values image are small with respect to the polygons then use this function.

Parameters

vecfile – input vector file
veclyrname – input vector layer within the input file which specifies the features and where the output stats will be written.
valsimg – the values image
imgbandidx – the index (starting at 1) of the image band for which the stats will be calculated. If defined the no data value of the band will be ignored.
minthres – a lower threshold for values which will be included in the stats calculation.
maxthres – a upper threshold for values which will be included in the stats calculation.
out_no_data_val – output no data value if no valid pixels are within the polygon.
minfield – the name of the field for the min value (None or not specified to be ignored).
maxfield – the name of the field for the max value (None or not specified to be ignored).
meanfield – the name of the field for the mean value (None or not specified to be ignored).
stddevfield – the name of the field for the standard deviation value (None or not specified to be ignored).
sumfield – the name of the field for the sum value (None or not specified to be ignored).
countfield – the name of the field for the count (of number of pixels) value (None or not specified to be ignored).
modefield – the name of the field for the mode value (None or not specified to be ignored).
medianfield – the name of the field for the median value (None or not specified to be ignored).

rsgislib.zonalstats.calcZonalBandStatsTestPolyPts(veclyr, valsimg, imgbandidx, minthres, maxthres, out_no_data_val, minfield=None, maxfield=None, meanfield=None, stddevfield=None, sumfield=None, countfield=None, modefield=None, medianfield=None)¶

A function which calculates zonal statistics for a particular image band. If unsure then use this function. This function tests whether 1 or more pixels has been found within the polygon and if not then the centroid use used to find a value for the polygon.

If you are unsure as to whether the pixels are small enough to be contained within all the polygons then use this function.

Parameters

veclyr – OGR vector layer object containing the geometries being processed and to which the stats will be written.
valsimg – the values image
imgbandidx – the index (starting at 1) of the image band for which the stats will be calculated. If defined the no data value of the band will be ignored.
minthres – a lower threshold for values which will be included in the stats calculation.
maxthres – a upper threshold for values which will be included in the stats calculation.
out_no_data_val – output no data value if no valid pixels are within the polygon.
minfield – the name of the field for the min value (None or not specified to be ignored).
maxfield – the name of the field for the max value (None or not specified to be ignored).
meanfield – the name of the field for the mean value (None or not specified to be ignored).
stddevfield – the name of the field for the standard deviation value (None or not specified to be ignored).
sumfield – the name of the field for the sum value (None or not specified to be ignored).
countfield – the name of the field for the count (of number of pixels) value (None or not specified to be ignored).
modefield – the name of the field for the mode value (None or not specified to be ignored).
medianfield – the name of the field for the median value (None or not specified to be ignored).

rsgislib.zonalstats.calcZonalBandStatsTestPolyPtsFile(vecfile, veclyrname, valsimg, imgbandidx, minthres, maxthres, out_no_data_val, minfield=None, maxfield=None, meanfield=None, stddevfield=None, sumfield=None, countfield=None, modefield=None, medianfield=None)¶

A function which calculates zonal statistics for a particular image band. If unsure then use this function. This function tests whether 1 or more pixels has been found within the polygon and if not then the centroid use used to find a value for the polygon.

If you are unsure as to whether the pixels are small enough to be contained within all the polygons then use this function.

Parameters

vecfile – input vector file
veclyrname – input vector layer within the input file which specifies the features and where the output stats will be written.
valsimg – the values image
imgbandidx – the index (starting at 1) of the image band for which the stats will be calculated. If defined the no data value of the band will be ignored.
minthres – a lower threshold for values which will be included in the stats calculation.
maxthres – a upper threshold for values which will be included in the stats calculation.
out_no_data_val – output no data value if no valid pixels are within the polygon.
minfield – the name of the field for the min value (None or not specified to be ignored).
maxfield – the name of the field for the max value (None or not specified to be ignored).
meanfield – the name of the field for the mean value (None or not specified to be ignored).
stddevfield – the name of the field for the standard deviation value (None or not specified to be ignored).
sumfield – the name of the field for the sum value (None or not specified to be ignored).
countfield – the name of the field for the count (of number of pixels) value (None or not specified to be ignored).
modefield – the name of the field for the mode value (None or not specified to be ignored).
medianfield – the name of the field for the median value (None or not specified to be ignored).

rsgislib.zonalstats.calcZonalPolyPtsBandStats(veclyr, valsimg, imgbandidx, outfield)¶

A funtion which extracts zonal stats for a polygon using the polygon centroid. This is useful when you are intesecting a low resolution image with respect to the polygon resolution.

Parameters

veclyr – OGR vector layer object containing the geometries being processed and to which the stats will be written.
valsimg – the values image
imgbandidx – the index (starting at 1) of the image band for which the stats will be calculated. If defined the no data value of the band will be ignored.
outfield – output field name within the vector layer.

rsgislib.zonalstats.calcZonalPolyPtsBandStatsFile(vecfile, veclyrname, valsimg, imgbandidx, outfield)¶

A funtion which extracts zonal stats for a polygon using the polygon centroid. This is useful when you are intesecting a low resolution image with respect to the polygon resolution.

Parameters

vecfile – input vector file
veclyrname – input vector layer within the input file which specifies the features and where the output stats will be written.
valsimg – the values image
imgbandidx – the index (starting at 1) of the image band for which the stats will be calculated. If defined the no data value of the band will be ignored.
outfield – output field name within the vector layer.

Points¶

These functions take a shapefile with point geomoetry and extract the value of the pixel the point falls within.

rsgislib.zonalstats.pointValue2SHP(inputimage, inputvector, outputvector, force, useBandNames=True)¶

Extract pixel value for each point in a shape file and output as a shapefile.

Where:

Parameters

inputimage – is a string containing the name of the input image
inputvector – is a string containing the name of the input vector
outputvector – is a string containing the name of the output vector
force – is a bool, specifying whether to force removal of the output vector if it exists
useBandNames – is a bool, specifying whether to use the band names of the input dataset in the output file (if not uses b1, b2, etc.)

Example:

from rsgislib import zonalstats
inputimage = './Rasters/injune_p142_casi_sub_utm.kea'
inputvector = './Vectors/injune_p142_stem_locations.shp'
outputvector = './TestOutputs/injune_p142_stem_locations_stats.shp'
removeExistingVector = True
useBandNames = True
zonalstats.pointValue2SHP(inputimage, inputvector, outputvector, removeExistingVector, useBandNames)

rsgislib.zonalstats.pointValue2TXT(inputimage, inputvector, outputtxt, useBandNames=True, shortenBandNames=True)¶

Extract pixel value for each point in a shape file and output as a CSV.

Where:

Parameters

inputimage – is a string containing the name of the input image
inputvector – is a string containing the name of the input vector
outputtxt – is a string containing the name of the output text file
useBandNames – is a bool, specifying whether to use the band names of the input dataset in the output file (if not uses b1, b2, etc.)

Example:

from rsgislib import zonalstats
inputimage = './Rasters/injune_p142_casi_sub_utm.kea'
inputvector = './Vectors/injune_p142_stem_locations.shp'
outputtxt = './TestOutputs/injune_p142_stem_locations_stats.csv'
useBandNames = True
zonalstats.pointValue2TXT(inputimage, inputvector, outputtxt, useBandNames)

Polygons¶

These functions take a polygons as input and either calculate statistics from pixels falling within the polygon or save out all pixel values.

rsgislib.zonalstats.pixelVals2TXT(inputimage, inputvector, outputtxtBase, attribute, noProjWarning=False, pixelInPolyMethod=METHOD_POLYCONTAINSPIXELCENTER)¶

Extract pixel value for all pixels within a polygon and save a seperate CSV for each polygon in the shapefile.

Where:

Parameters

inputimage – is a string containing the name of the input image.
inputvector – is a string containing the name of the input vector.
outputtxtBase – is a string containing the base name for output text files.
attribute – is a string specifying an identifier for each polygon to be used for the name of each output text file.
noProjWarning – is a bool, specifying whether to skip printing a warning if the vector and image have a different projections.
pixelInPolyMethod – is the method for determining if a pixel is included with a polygon of type rsgislib.zonalstats.METHOD_*.

Example:

from rsgislib import zonalstats
inputimage = './Rasters/injune_p142_casi_sub_utm.kea'
inputvector = './Vectors/injune_p142_crowns_utm.shp'
outputtxtbase = './TestOutputs/ZonalTXT/injune_p142_casi_sub_utm_txt'
zonalstats.pixelVals2TXT(inputimage, inputvector, outputtxtBase, 'FID', True, zonalstats.METHOD_POLYCONTAINSPIXELCENTER)

rsgislib.zonalstats.pixelStats2SHP(inputimage, inputvector, outputvector, zonalattributes, force, useBandNames, noProjWarning=False, pixelInPolyMethod=METHOD_POLYCONTAINSPIXELCENTER)¶

Calculate statistics for pixels falling within each polygon in a shapefile output as a shapefile.

Where:

Parameters

inputimage – is a string containing the name of the input image
inputvector – is a string containing the name of the input vector
outputvector – is a string containing the name of the output vector
ZonalAttributes – is an rsgislib.zonalstats.zonalattributes object that has attributes in line with rsgis::cmds::RSGISBandAttZStatsCmds * minThreshold, a float providing the minimum pixel value to include when calculating statistics. * maxThreshold, a float providing the maximum pixel value to include when calculating statistics. * calcCount, a bool specifying whether to report a count of pixels between thresholds. * calcMin, a bool specifying whether to report the minimum of pixels between thresholds. * calcMax, a bool specifying whether to report the maximum of pixels between thresholds. * calcMean, a bool specifying whether to report the mean of pixels between thresholds. * calcStdDev, a bool specifying whether to report the standard deviation of pixels between thresholds. * calcMode, a bool specifying whether to report the mode of pixels between thresholds (for integer datasets only). * calcSum, a bool specifying whether to report the sum of pixels between thresholds.
force – is a bool, specifying whether to force removal of the output vector if it exists
noProjWarning – is a bool, specifying whether to skip printing a warning if the vector and image have a different projections.
useBandNames – is a bool, specifying whether to use the band names of the input dataset in the output file (if not uses b1, b2, etc.)
pixelInPolyMethod – is the method for determining if a pixel is included with a polygon of type rsgislib.zonalstats.METHOD_*.

Example:

from rsgislib import zonalstats
inputimage = './Rasters/injune_p142_casi_sub_utm.kea'
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
inputVector = './Vectors/injune_p142_crowns_utm.shp'
outputVector = './TestOutputs/injune_p142_casi_sub_utm_stats.shp'
zonalattributes = zonalstats.ZonalAttributes(minThreshold=0, maxThreshold=10000, calcCount=True, calcMin=True, calcMax=True, calcMean=True, calcStdDev=True, calcMode=False, calcSum=True)
zonalstats.pixelStats2SHP(inputImage, inputVector, outputVector, zonalattributes, True, True, True, zonalstats.METHOD_POLYCONTAINSPIXELCENTER)

rsgislib.zonalstats.pixelStats2TXT(inputimage, inputvector, outputtxt, zonalattributes, useBandNames, noProjWarning=False, pixelInPolyMethod=METHOD_POLYCONTAINSPIXELCENTER, shortenBandNames=True)¶

Calculate statistics for pixels falling within each polygon in a shapefile output as a CSV.

Where:

Parameters

inputimage – is a string containing the name of the input image
inputvector – is a string containing the name of the input vector
outputtxt – is a string containing the name of the output text file
ZonalAttributes – is an rsgislib.rastergis.zonalattributes object that has attributes in line with rsgis::cmds::RSGISBandAttZStatsCmds * minThreshold, a float providing the minimum pixel value to include when calculating statistics. * maxThreshold, a float providing the maximum pixel value to include when calculating statistics. * calcCount, a bool specifying whether to report a count of pixels between thresholds. * calcMin, a bool specifying whether to report the minimum of pixels between thresholds. * calcMax, a bool specifying whether to report the maximum of pixels between thresholds. * calcMean, a bool specifying whether to report the mean of pixels between thresholds. * calcStdDev, a bool specifying whether to report the standard deviation of pixels between thresholds. * calcMode, a bool specifying whether to report the mode of pixels between thresholds (for integer datasets only). * calcSum, a bool specifying whether to report the sum of pixels between thresholds.
useBandNames – is a bool, specifying whether to use the band names of the input dataset in the output file (if not uses b1, b2, etc.)
noProjWarning – is a bool, specifying whether to skip printing a warning if the vector and image have a different projections.
pixelInPolyMethod – is the method for determining if a pixel is included with a polygon of type rsgislib.zonalstats.METHOD_*.
shortenBandNames – is a bool to specify whether the band names should be shorted (as with a shapefile) in creating the column name.

Example:

from rsgislib import zonalstats
inputimage = './Rasters/injune_p142_casi_sub_utm.kea'
inputImage = './Rasters/injune_p142_casi_sub_utm.kea'
inputVector = './Vectors/injune_p142_crowns_utm.shp'
outputtxt = './TestOutputs/injune_p142_casi_sub_utm_stats.txt'
zonalattributes = zonalstats.ZonalAttributes(minThreshold=0, maxThreshold=10000, calcCount=True, calcMin=True, calcMax=True, calcMean=True, calcStdDev=True, calcMode=False, calcSum=True)
zonalstats.pixelStats2SHP(inputImage, inputVector, outputtxt, zonalattributes, True, True, zonalstats.METHOD_POLYCONTAINSPIXELCENTER, False)

rsgislib.zonalstats.imageZoneToHDF(inputimage, inputvector, outputHDF, noProjWarning=False, pixelInPolyMethod=METHOD_POLYCONTAINSPIXELCENTER)¶

Extract the all the pixel values for regions to a HDF5 file (1 column for each image band).

Where:

Parameters

inputimage – is a string containing the name of the input image.
inputvector – is a string containing the name of the input vector.
outputHDF – is a string containing name of the output HDF file.
noProjWarning – is a bool, specifying whether to skip printing a warning if the vector and image have a different projections.
pixelInPolyMethod – is the method for determining if a pixel is included with a polygon of type rsgislib.zonalstats.METHOD_*.

Example:

from rsgislib import zonalstats
inputimage = './Rasters/injune_p142_casi_sub_utm.kea'
inputvector = './Vectors/injune_p142_crowns_utm.shp'
outputHDF = './TestOutputs/InjuneP142.hdf'
zonalstats.imageZoneToHDF(inputimage, inputvector, outputHDF, True, zonalstats.METHOD_POLYCONTAINSPIXELCENTER)

rsgislib.zonalstats.polyPixelStatsVecLyr(inputimg=string, vecfile=string, veclyr=string, bandatts=list, pixpolymeth=rsgislib.zonalstats.METHOD_*, noprojwarn=boolean)¶

Calculate statistics for pixels that intersect (defined using the specified method) with a feature in the vector layer.

Where:

Parameters

inputimg – is a string containing the name of the input image
vecfile – is a string containing the name of the input vector
veclyr – is a string containing the name of the input vector layer
bandatts – is a list of rsgislib.zonalstats.ZonalBandAttributes objects.
pixpolymeth – is the method for determining if a pixel is included with a polygon of type rsgislib.zonalstats.METHOD_*.
noprojwarn – is a bool, specifying whether to skip printing a warning if the vector and image have a different projections.

Endmember Analysis¶

These functions define extract a set of endmembers from an image file to be used for linear spectral unmixing (see imagecalc module).

rsgislib.zonalstats.extractAvgEndMembers(inputimage, inputvector, outputMatrixFile, pixelInPolyMethod=METHOD_POLYCONTAINSPIXELCENTER)¶

Extract the average endmembers per class which are saved as an appropriate matrix file to be used within the linear spectral unmixing commands. Each polygon defined is another endmember in the outputted matric file.

Where:

Parameters

inputimage – is a string containing the name of the input image.
inputvector – is a string containing the name of the input vector.
outputMatrixFile – is a string containing name of the output matrix file.
pixelInPolyMethod – is the method for determining if a pixel is included with a polygon of type rsgislib.zonalstats.METHOD_*.

Example:

from rsgislib import zonalstats
inputimage = './Rasters/injune_p142_casi_sub_utm.kea'
inputvector = './Vectors/injune_p142_crowns_utm.shp'
outputHDF = './TestOutputs/InjuneP142.hdf'
zonalstats.imageZoneToHDF(inputimage, inputvector, outputHDF, True, zonalstats.METHOD_POLYCONTAINSPIXELCENTER)

RSGISLib Zonal Stats Module¶

Points¶

Polygons¶

Endmember Analysis¶

Table of Contents

Previous topic

This Page