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 [-rcnpl] 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
- -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
- --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, 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.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.
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.
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
... ... ... ... ...
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.
r.stats.zonal,
r.univar,
v.rast.stats,
i.segment.stats (Addon),
Tais GRIPPA - Universite Libre de Bruxelles. ANAGEO Lab.
SOURCE CODE
Available at:
r.zonal.classes source code
(history)
Latest change: Tuesday Mar 26 20:41:36 2024 in commit: 3b09b1d78f6e96ffebacac6e36f0afd91ad0c091
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
© 2003-2024
GRASS Development Team,
GRASS GIS 8.4.1dev Reference Manual