r.category(1grass) GRASS GIS User's Manual r.category(1grass)
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,...]] [val-
ues=float[,float,...]] [separator=character] [raster=name]
[rules=name] [format=string] [coefficients=mult1,offset1,mult2,off-
set2] [--help] [--verbose] [--quiet] [--ui]
Flags:
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
map=name [required]
Name of raster map
cats=range[,range,...]
Category values
Example: 1,3,7-9,13
values=float[,float,...]
Comma separated value list
Example: 1.4,3.8,13
separator=character
Field separator
Special characters: pipe, comma, space, tab, newline
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 cate-
gories (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.de-
scribe, 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
separator=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
separator parameter), then the label for the category.
NOTES
Any ASCII TAB characters which may be in the label are replaced by spa-
ces.
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 (without header). The label can refer to a single cate-
gory, range of categories, floating point value, or a range of floating
point values. The format is given as follows (when separator is set to
colon; no white space must be used after the separator):
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 co-
efficients)
• $2 refers to the value num*5.0+1005 (ie, using the last 2 coef-
ficients)
$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 follow-
ing 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 coefficient 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 un-
wanted shell substitution.
EXAMPLES
North Carolina sample dataset:
Printing categories
r.category map=landclass96
1 developed
2 agriculture
3 herbaceous
4 shrubland
5 forest
6 water
7 sediment
prints the values and labels associated with all of the categories in
the landclass96 raster map layer.
r.category map=landclass96 cats=2,5-7
2 agriculture
5 forest
6 water
7 sediment
prints only the category values and labels for landclass96 map layer
categories 2 and 5 through 7.
r.category map=landclass96 cats=3,4 separator=comma
3,herbaceous
4,shrubland
prints the values and labels for landclass96 map layer categories 3 and
4, but uses "," (instead of a tab) as the character separating the cat-
egory values from the category values in the output.
Adding categories
Example for defining new category labels, using a colon as separator:
r.category diseasemap separator=":" rules=- << EOF
1:potential absence
2:potential presence
EOF
This sets the categoy values 1 and 2 to respective text labels. Alter-
natively, the rules can be stored in an ASCII text file and loaded via
the rules parameter.
SEE ALSO
UNIX Manual entries for awk and sort
d.what.rast, r.coin, r.describe, r.support
AUTHORS
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
Hamish Bowman, University of Otago, New Zealand (label creation op-
tions)
SOURCE CODE
Available at: r.category source code (history)
Accessed: unknown
Main index | Raster index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 r.category(1grass)
Generated by dwww version 1.14 on Sun Dec 29 18:56:42 CET 2024.