NAME

r.categorise - Creates fully categorised floating point or integer raster maps.
(GRASS Raster Program)

SYNOPSIS

r.categorise [-cnuzq] input=name [output=name] [mode=name[,value]] [type=[float|int]] [min=value] [max=value] [logfile=name] [precision=value]

This program cannot be used interactively.

DESCRIPTION

It is often useful or even necessary to summarise a raster map's range of values using categories. E.g. a floating point height map with values in the range 0.00 to 300.00 metres could be represented using 5 categories and descriptive labels:

	Cat.	Range		Label
	0	0-50		Very low
	1	50-100		Low
	2	150-200		Medium
	3	200-250		High
	4	250-300		Very High

Integer map categories do not have a range. They are simply numbered from 0 to N with N being the highest category:

	Cat.	Label
	0	Sand
	1	Clay
	2	Peat Soil
	3	Bedrock
	4	Debris

GRASS offers category support for both floating point and integer maps. The r.support program allows the user to define and label categories interactively. The r.categorise program allows the user to automatically define and label categories using one of several categorisation modes. It is possible to create categories by specifying category width or number and to 'clean' maps that already contain category specifications by converting all cells to NULL that do not match any category. Floating point maps can also be turned into categorised integer maps by rounding or truncating the cell values. In any case, the output map will be fully classified, meaning that each cell either matches a category or is NULL. Category labels are written automatically. Information about the quantification mode is stored in the output map's metadata and can later be retrieved using r.info.

Flags

-c
Only check and report input map categories. Do not create any output.
-n
Also report NULL cells (in conjunction with -c).
-u
Also report uncategorised cells (in conjunction with -c).>
-z
Also report zero count cells (in conjunction with -c).>
-q
Quiet operation: do not display progress on screen.>

Parameters

input=name
Name of input raster map.
output=name
Name of output raster map.
mode=name,value
Name of categorisation mode. Some modes require an additional value. See below for details.
type=[float|int]
Type of output map (float or int). Defaults to type of input map.
min=value
Lower limit of cutting range.
max=value
Upper limit of cutting rang. All values in the input map outside the cutting range will be converted to NULL in the output map.
logfile=name
If a logfile is specified, additional information will be written to that file.
precision=value
Number of decimal places to print in the logfile.

Categorisation Modes

The following modes can be used with floating point input maps:
clean
Keeps categories already defined in input map and convert all cells that do not match a category range to NULL.
num,n
Creates n categories of equal width for which the ranges are determined automatically.
width,n
Creates categories of width n. The number of categories is determined automatically. The highest category can have a different width.
rwidth,n
Same as width, except that the lowest category boundary is rounded to the nearest integer. Especially nice for creating height map categories.
round
Creates categories by rounding all cell values to nearest integer value.
trunc
Creates categories by truncating all cell values.
The following modes are for use with integer input maps:
clean
Keeps categories already defined in input map and convert all cells that do not match a category range to NULL.
num,n
Creates n categories of equal width for which the ranges are determined automatically. The highest category can have a different width.
width,n
Creates categories of width n. The number of categories is determined automatically. The highest category can have a different width.
rescale
Scale range of values in input map to the range 0 to N.

Examples

To clean an input floating point map of all cells whose value does not fall into any category range or whose value is > 10:
	r.categorise input=mymap output=cleanmap mode=clean max=10
To create a categorised elevation map with 10 m steps and lowest value rounded:
	r.categorise input=height output=height10 mode=rwidth,10
To just report on a map's category structure including counts of uncategorised and NULL data cells:
	r.categorise input=mymap -cnu

Notes

This program was originally developed as part of the GRASS 5 DST Predictive Modelling Toolkit and can be used to prepare evidence raster maps for BPA calculation using r.dst.bpa. If you want to analyse the distribution of sites over raster categories, you can use s.report.

SEE ALSO

r.cats r.reclass r.support r.info r.dst.bpa s.report

AUTHOR

Benjamin Ducke,

University of Bamberg, Germany

Heritage Management Brandenburg, Germany

Last changed: $Date: 2004/07/20 15:44:01 $