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, 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.

  • 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, 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.

  • 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, 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.

  • 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, 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.

  • 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)