r.zonal.classes

Calculates zonal classes proportion describing raster areas's composition, e.g., in terms of land-cover classes.

r.zonal.classes [-rcnpl] zone_map=name raster=name statistics=string [,string,...] [prefix=string] [decimals=integer] [classes_list=string] [csvfile=name] [separator=character] [vectormap=name] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.zonal.classes zone_map=name raster=name statistics=proportion,mode csvfile=name

grass.script.run_command("r.zonal.classes", zone_map, raster, statistics="proportion,mode", prefix=None, decimals=5, classes_list=None, csvfile=None, separator="pipe", vectormap=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.zonal.classes", zone_map="name", raster="name", statistics="proportion,mode", csvfile="name")

Parameters

Command linePython (grass.script)

zone_map=name [required]
    Name for input raster map with areas
    Raster map with areas (all pixels of an area have same id), such as the output of r.clump
raster=name [required]
    Name of input categorical raster maps for statistics
statistics=string [,string,...] [required]
    Statistics to calculate for each input raster map
    Allowed values: proportion, mode
    Default: proportion,mode
prefix=string
    Prefix for statistics name
decimals=integer
    Number of decimals for proportion numbers
    Default: 5
classes_list=string
    List of classes to be considered in the calculation, e.g. '21,34,35,56'
csvfile=name
    Name for output CSV file containing statistics
separator=character
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Default: pipe
vectormap=name
    Name for optional vector output map with statistics as attributes
-r
    Adjust region to input map
-c
    Force check of input's layer type
-n
    Consider null values in the calculations
-p
    Proportions as percentages instead of zone's area ratio
-l
    Compute statistics only for the classes provided in 'classes_list' parameter
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

zone_map : str, required
    Name for input raster map with areas
    Raster map with areas (all pixels of an area have same id), such as the output of r.clump
    Used as: input, raster, name
raster : str, required
    Name of input categorical raster maps for statistics
    Used as: input, raster, name
statistics : str | list[str], required
    Statistics to calculate for each input raster map
    Allowed values: proportion, mode
    Default: proportion,mode
prefix : str, optional
    Prefix for statistics name
decimals : int, optional
    Number of decimals for proportion numbers
    Default: 5
classes_list : str, optional
    List of classes to be considered in the calculation, e.g. '21,34,35,56'
csvfile : str, optional
    Name for output CSV file containing statistics
    Used as: output, file, name
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: pipe
vectormap : str, optional
    Name for optional vector output map with statistics as attributes
    Used as: output, vector, name
flags : str, optional
    Allowed values: r, c, n, p, l
    r
        Adjust region to input map
    c
        Force check of input's layer type
    n
        Consider null values in the calculations
    p
        Proportions as percentages instead of zone's area ratio
    l
        Compute statistics only for the classes provided in 'classes_list' parameter
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.zonal.classes computes class proportions and majority class (mode) of a "cover layer" (provided via the raster parameter) - e.g. a land cover map - according to how it intersects with areas/objects in a "base layer" (provided via the zone_map parameter). Areas are defined by adjacent pixels with the same value, such as those obtained with r.clump or i.segment.

This function is similar to r.stats.zonal, but is intended to be used on a categorical raster with integer values (CELL type) instead of floating point as in r.stats.zonal.

NOTES

The user can choose between output in the form of a vector map of the areas contained in the "base layer" with the statistics of the "cover layer" stored in the attribute table (the name of the vector layer should be provided via the vectormap parameter) and/or in the form of a CSV text file (the path to the file should be provided via the csvfile parameter).

By default:

the function compute the majority class as well as class proportions for each zone in the "base layer". If only the majority class or class proportion is needed, it can be specified by using the statistics parameter.
the function provides the ratio of classes (total = 1) but the -p flag allows providing percentages (total = 100). The number of decimals is set to 5 by default and can be changed using the decimals parameter.
the name of columns for proportions follows this logic : 'prop_XX' where XX is the class of the "base layer". The user can add a prefix to proportion columns using the prefix parameter.
the function works under the current computation region. The -r flag can be used to define the computational region based on the "base layer" for the processing.
the function ignores NULL values in statistics computation. This behaviour can be reverted using the -n flag.
the function provides proportion columns only for classes that actually exist in the "base layer" under the current computational region. This can create problems when the user run the function on different computational region with the aim to merge outputs at the end, because some classes could be present under some computational regions and absent on others. The classes_list parameter and the -l flag allow to alleviate this issue. The -l flag force the output to provide statistics only for classes provided via the classes_list parameter. When the classes_list parameter is provided without the -l flag, the output will contain in addition to the classes that actually exist in the "base layer" under the current computational region (the default behaviour) columns for classes in the provided via the classes_list parameter which will be filled with zero value. This is particularly useful when the function is used in multiple processing - sequentially or in parallel - to ensure all the output will have the same number (and order) of columns. Please notice that the computation of the mode is not affected by the list of classes provided in the classes_list parameter.
there is no check for the type of input's raster which is intended to be "CELL". This behaviour can be reversed using the -c flag.

EXAMPLES

On North Carolina sample dataset:

# Define region
g.region raster=zipcodes

# Get majority class and class proportion of 'landuse96_28m'
# for each zone/object in 'zipcode' layer
r.zonal.classes zone_map=zipcodes raster=landuse96_28m csvfile=output.csv \
  vectormap=vect_output

# Display attributes table
v.db.select map=vect_output

cat mode    prop_0  prop_1   ...    prop_21
27511   18  0.00009 0.11286  ...    0.00000
27513   15  0.00000 0.06098  ...    0.00000
27518   15  0.00000 0.06455  ...    0.00000
27529   15  0.00000 0.24149  ...    0.00000
... ... ... ...  ...    ...

# Get only class proportion (not the mode), add prefix on columns and
# return proportion as percentages instead of the zone's area ratio
r.zonal.classes zone_map=zipcodes raster=landuse96_28m csvfile=output.csv \
  vectormap=vect_output prefix=lu statistics=proportion -p

# Display attributes table
v.db.select map=vect_output

cat lu_prop_0   lu_prop_1   ... lu_prop_21
27511   0.00851     11.28639    ... 0.00000
27513   0.00000     6.09839     ... 0.00000
27518   0.00000     6.45485     ... 0.00000
27529   0.00000     24.14926    ... 0.00000
... ...     ...     ...  ...

# Ensure that a column is created for class '1234' even if it doesn't exist
# under the current computational region
r.zonal.classes zone_map=zipcodes raster=landuse96_28m csvfile=output.csv \
  vectormap=vect_output prefix=lu classes_list='1234'

# Display attributes table
v.db.select map=vect_output

cat lu_mode lu_prop_0   ... lu_prop_21  lu_prop_1234
27511   18  0.00009     ... 0.00000     0.00000
27513   15  0.00000     ... 0.00000     0.00000
27518   15  0.00000     ... 0.00000     0.00000
... ... ...     ...  ...        ...

# Output only the proportion columns for classes '4,12,1234'
r.zonal.classes zone_map=zipcodes raster=landuse96_28m csvfile=output.csv \
  vectormap=vect_output classes_list='4,12,1234' -l

# Display attributes table
v.db.select map=vect_output

cat mode    prop_4      prop_12 prop_1234
27511   18  0.02310     0.00000 0.00000
27513   15  0.02888     0.00000 0.00000
27518   15  0.06291     0.00000 0.00000
27529   15  0.02579     0.00000 0.00000
... ... ...     ...  ...

Acknowledgement

This work was funded by the Belgian Federal Science Policy Office (BELSPO) (Research Program for Earth Observation STEREO III, contract SR/00/304) as part of the MAUPP project and by the department of Geomatics of the Walloon region as part of the WALOUS project.

AUTHOR

Tais GRIPPA - Universite Libre de Bruxelles. ANAGEO Lab.

SOURCE CODE

Available at: r.zonal.classes source code (history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3