1r.category(1) GRASS GIS User's Manual r.category(1)
2
6 r.category - Manages category values and labels associated with
7 user-specified raster map layers.
8
10 raster, category
11
13 r.category
14 r.category --help
15 r.category map=name [cats=range[,range,...]] [val‐
16 ues=float[,float,...]] [separator=character] [raster=name]
17 [rules=name] [format=string] [coefficients=mult1,offset1,mult2,off‐
18 set2] [--help] [--verbose] [--quiet] [--ui]
19 Flags:
21 --help
22 Print usage summary
23 --verbose
25 Verbose module output
26 --quiet
28 Quiet module output
29 --ui
31 Force launching GUI dialog
32 Parameters:
34 map=name [required]
35 Name of raster map
36 cats=range[,range,...]
38 Category values
39 Example: 1,3,7-9,13
40 values=float[,float,...]
42 Comma separated value list
43 Example: 1.4,3.8,13
44 separator=character
46 Field separator
47 Special characters: pipe, comma, space, tab, newline
48 Default: tab
49 raster=name
51 Raster map from which to copy category table
52 rules=name
54 File containing category label rules (or "-" to read from stdin)
55 format=string
57 Default label or format string for dynamic labeling
58 Used when no explicit label exists for the category
59 coefficients=mult1,offset1,mult2,offset2
61 Dynamic label coefficients
62 Two pairs of category multiplier and offsets, for $1 and $2
63
65 r.category prints the category values and labels for the raster map
66 layer specified by map=name to standard output. You can also use it to
67 set category labels for a raster map.
68 The user can specify all needed parameters on the command line, and run
70 the program non-interactively. If the user does not specify any cate‐
71 gories (e.g., using the optional cats=range[,range,...] argument),
72 then all the category values and labels for the named raster map layer
73 that occur in the map are printed. The entire map is read using r.de‐
74 scribe, to determine which categories occur in the map. If a listing of
75 categories is specified, then the labels for those categories only are
76 printed. The cats may be specified as single category values, or as
77 ranges of values. The user may also (optionally) specify that a field
78 separator other than a space or tab be used to separate the category
79 value from its corresponding category label in the output, by using the
80 separator=character|space|tab option (see example below). If no field
81 separator is specified by the user, a tab is used to separate these
82 fields in the output, by default.
83 The output is sent to standard output in the form of one category per
85 line, with the category value first on the line, then an ASCII TAB
86 character (or whatever single character or space is specified using the
87 separator parameter), then the label for the category.
88
90 Any ASCII TAB characters which may be in the label are replaced by spa‐
91 ces.
92 The output from r.category can be redirected into a file, or piped into
94 another program.
95 Input from a file
97 The rules option allows the user to assign category labels from values
98 found in a file (without header). The label can refer to a single cate‐
99 gory, range of categories, floating point value, or a range of floating
100 point values. The format is given as follows (when separator is set to
101 colon; no white space must be used after the separator):
102 cat:Label
103 val1:val2:Label
104 If the filename is given as "-", the category labels are read from
105 stdin
106 Default and dynamic category labels
108 Default and dynamic category labels can be created for categories that
109 are not explicitly labeled. The coefficient line can be followed by
110 explicit category labels which override the format label generation.
111 0:no data
112 2: .
113 5: . ## explicit category labels
114 7: .
115 explicit labels can be also of the form:
116 5.5:5:9 label description
117 or
118 15:30 label description
119 In the format line
121 • $1 refers to the value num*5.0+1000 (ie, using the first 2 co‐
123 efficients)
124 • $2 refers to the value num*5.0+1005 (ie, using the last 2 coef‐
126 ficients)
127 $1.2 will print $1 with 2 decimal places.
128 Also, the form $?xxx$yyy$ translates into yyy if the category is 1, xxx
130 otherwise. The $yyy$ is optional. Thus
131 $1 meter$?s
133 will become:
135 1 meter (for category 1)
136 2 meters (for category 2), etc.
137 format=’Elevation: $1.2 to $2.2 feet’ ## Format Statement
139 coefficients="5.0,1000,5.0,1005" ## Coefficients
140 The format and coefficients above would be used to generate the follow‐
142 ing statement in creation of the format appropriate category string for
143 category "num":
144 sprintf(buff,"Elevation: %.2f to %.2f feet", num*5.0+1000,
146 num*5.0*1005)
147 Note: while both the format and coefficient lines must be present a
149 blank line for the format string will effectively suppress automatic
150 label generation.
151 To use a "$" in the label without triggering the plural test, put "$$"
153 in the format string.
154 Use ’single quotes’ when using a "$" on the command line to avoid un‐
156 wanted shell substitution.
157
159 North Carolina sample dataset:
160 Printing categories
162 r.category map=landclass96
163 1 developed
164 2 agriculture
165 3 herbaceous
166 4 shrubland
167 5 forest
168 6 water
169 7 sediment
170 prints the values and labels associated with all of the categories in
171 the landclass96 raster map layer.
172 r.category map=landclass96 cats=2,5-7
174 2 agriculture
175 5 forest
176 6 water
177 7 sediment
178 prints only the category values and labels for landclass96 map layer
179 categories 2 and 5 through 7.
180 r.category map=landclass96 cats=3,4 separator=comma
182 3,herbaceous
183 4,shrubland
184 prints the values and labels for landclass96 map layer categories 3 and
185 4, but uses "," (instead of a tab) as the character separating the cat‐
186 egory values from the category values in the output.
187 Adding categories
189 Example for defining new category labels, using a colon as separator:
190 r.category diseasemap separator=":" rules=- << EOF
191 1:potential absence
192 2:potential presence
193 EOF
194 This sets the categoy values 1 and 2 to respective text labels. Alter‐
195 natively, the rules can be stored in an ASCII text file and loaded via
196 the rules parameter.
197
199 UNIX Manual entries for awk and sort
200 d.what.rast, r.coin, r.describe, r.support
202
204 Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
205 Hamish Bowman, University of Otago, New Zealand (label creation op‐
206 tions)
207
209 Available at: r.category source code (history)
210 Accessed: Saturday Jan 21 20:38:19 2023
212 Main index | Raster index | Topics index | Keywords index | Graphical
214 index | Full index
215 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
217GRASS 8.2.1 r.category(1)