Provided by: grass-doc_6.4.3-3_all 
NAME
r.category - Manages category values and labels associated with user-specified raster map layers.
KEYWORDS
raster, category
SYNOPSIS
r.category
r.category help
r.category map=name [cats=range[,range,...]] [vals=float[,float,...]] [fs=character|space|tab]
[raster=name] [rules=name] [format=string] [coefficients=mult1,offset1,mult2,offset2] [--verbose]
[--quiet]
Parameters:
map=name
Name of input raster map
cats=range[,range,...]
Category values
Example: 1,3,7-9,13
vals=float[,float,...]
Comma separated value list
Example: 1.4,3.8,13
fs=character|space|tab
Field separator
Output field separator
Default: tab
raster=name
Raster map from which to copy category table
rules=name
File containing category label rules (or "-" to read from stdin)
format=string
Default label or format string for dynamic labeling
Used when no explicit label exists for the category
coefficients=mult1,offset1,mult2,offset2
Dynamic label coefficients
Two pairs of category multiplier and offsets, for $1 and $2
DESCRIPTION
r.category prints the category values and labels for the raster map layer specified by map=name to
standard output. You can also use it to set category labels for a raster map.
The user can specify all needed parameters on the command line, and run the program non-interactively. If
the user does not specify any categories (e.g., using the optional cats=range[,range,...] argument),
then all the category values and labels for the named raster map layer that occur in the map are printed.
The entire map is read using r.describe, to determine which categories occur in the map. If a listing of
categories is specified, then the labels for those categories only are printed. The cats may be specified
as single category values, or as ranges of values. The user may also (optionally) specify that a field
separator other than a space or tab be used to separate the category value from its corresponding
category label in the output, by using the fs=character|space|tab option (see example below). If no field
separator is specified by the user, a tab is used to separate these fields in the output, by default.
The output is sent to standard output in the form of one category per line, with the category value first
on the line, then an ASCII TAB character (or whatever single character or space is specified using the fs
parameter), then the label for the category.
NOTES
Any ASCII TAB characters which may be in the label are replaced by spaces.
The output from r.category can be redirected into a file, or piped into another program.
Input from a file
The rules option allows the user to assign category labels from values found in a file. The label can
refer to a single category, range of categories, floating point value, or a range of floating point
values. The format is given as follows.
cat:Label
val1:val2:Label
If the filename is given as "-", the category labels are read from stdin
Default and dynamic category labels
Default and dynamic category labels can be created for categories that are not explicitly labeled. The
coefficient line can be followed by explicit category labels which override the format label generation.
0:no data
2: .
5: . ## explicit category labels
7: .
explicit labels can be also of the form:
5.5:5:9 label description
or
15:30 label description
In the format line
$1 refers to the value num*5.0+1000 (ie, using the first 2 coefficients)
$2 refers to the value num*5.0+1005 (ie, using the last 2 coefficients)
$1.2 will print $1 with 2 decimal places.
Also, the form $?xxx$yyy$ translates into yyy if the category is 1, xxx otherwise. The $yyy$ is optional.
Thus
$1 meter$?s
will become: 1 meter (for category 1)
2 meters (for category 2), etc.
format='Elevation: $1.2 to $2.2 feet' ## Format Statement coefficients="5.0,1000,5.0,1005" ##
Coefficients
The format and coefficients above would be used to generate the following statement in creation of the
format appropriate category string for category "num":
sprintf(buff,"Elevation: %.2f to %.2f feet", num*5.0+1000, num*5.0*1005)
Note: while both the format and coefficent lines must be present a blank line for the format string will
effectively suppress automatic label generation.
To use a "$" in the label without triggering the plural test, put "$$" in the format string.
Use 'single quotes' when using a "$" on the command line to avoid unwanted shell substitution.
EXAMPLES
r.category map=soils
prints the values and labels associated with all of the categories in the soils raster map layer;
r.category map=soils cats=10,12,15-20
prints only the category values and labels for soils map layer categories 10, 12, and 15 through 20; and
r.category map=soils cats=10,20 fs=':'
prints the values and labels for soils map layer categories 10 and 20, but uses ":" (instead of a tab)
as the character separating the category values from the category values in the output.
Example output:
10:Dumps, mine, Cc
20:Kyle clay, KaA
Example defining category labels:
r.category diseasemap rules=- << EOF
1:potential absence
2:potential presence
EOF
sets the categoy values 1 and 2 to respective text labels.
TODO
Respect the fs= field separator setting for input rules.
SEE ALSO
UNIX Manual entries for awk and sort
r.coin, r.describe, d.what.rast, r.support
AUTHORS
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
Hamish Bowman, University of Otago, New Zealand (label creation options)
Last changed: $Date: 2009-02-26 18:58:59 -0800 (Thu, 26 Feb 2009) $
Full index
© 2003-2013 GRASS Development Team
GRASS 6.4.3 r.category(1grass)