r.categorize

DESCRIPTION

It is often 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.categorize 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 categorized 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 uncategorized 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.categorize input=mymap output=cleanmap mode=clean max=10

To create a categorized elevation map with 10 m steps and lowest value rounded:

	r.categorize input=height output=height10 mode=rwidth,10

To just report on a map's category structure including counts of uncategorized and NULL data cells:

	r.categorize input=mymap -cnu

You can also use this module to prepare a GRASS floating point raster map for export to a bitmap. E.g., to create an integer map from an FP map that preserves category structure and color table, you can run ...

	r.categorize input=fpmap output=bitmap -i

... and convert the result to, e.g. a geotiff bitmap file using r.out.tiff:

	r.out.tiff input=bitmap output=tiffmap compression=deflate -t

Notes

This program was originally developed as part of the GRASS 5 DST Predictive Modelling Toolkit.

AUTHOR

Benjamin Ducke,
University of Kiel, Germany
Last changed: 2005/07/31