RSGISLib Zonal Stats Module

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

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.

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:

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

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

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

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

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

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

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:

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