GRASS logo

NAME

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

KEYWORDS

raster, statistics, zonal statistics

SYNOPSIS

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

Flags:

-r
Adjust region to input map
-n
Consider null values in the calculations
-p
Proportions as percentages instead of zone's area ratio
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

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

Table of contents

DESCRIPTION

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

This function is similar to what r.stats.zonal performs, but is intended to be used on integer values raster (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 (vectormap) and/or in the form of a CSV text file (csvfile).

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.

By default the function provides the ratio of classes (total = 1) but the -p flag allow to provide percentages (total = 100). The number of decimals is set to 5 by default and can be changed using the decimals parameter.

By default, 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 computational region based on the "base layer" for the processing.

By default, the function ignore NULL values. This behaviour can be reverted using the -n flag.

By default, the output contains only columns 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 statistic tables at the end, because some classes could be present under some computational regions and absent on others. For this reason, the classes_list parameter allows to force the output to provide statistics also for classes no present under the current computation region. In this case, the proportion values added for this class are set to zero. 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.

EXAMPLE

On North Carolina sample dataset:
# Define region 
g.region raster=zipcodes

# Get majority class and classes 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 prefix=lu

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

cat	lu_mode		lu_prop_0	lu_prop_2	...	lu_prop_21
27518	15		0		0.0156		...	0
27607	15		0		0.23124		...	0.00307
27529	15		0		0.26308		...	0
27511	18		0.0001		0.08367		...	0
27539	11		0		0.00996		...	0
27608	2		0		0.65863		...	0
27513	15		0		0.10406		...	0

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.

SEE ALSO

r.stats.zonal, r.univar, v.rast.stats, i.segment.stats (Addon),

AUTHOR

Tais GRIPPA - Universite Libre de Bruxelles. ANAGEO Lab.

SOURCE CODE

Available at: r.zonal.classes source code (history)


Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2020 GRASS Development Team, GRASS GIS 7.8.3dev Reference Manual