1r.category(1)               GRASS GIS User's Manual              r.category(1)
2
3
4

NAME

6       r.category   -  Manages  category  values  and  labels  associated with
7       user-specified raster map layers.
8

KEYWORDS

10       raster, category
11

SYNOPSIS

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
20   Flags:
21       --help
22           Print usage summary
23
24       --verbose
25           Verbose module output
26
27       --quiet
28           Quiet module output
29
30       --ui
31           Force launching GUI dialog
32
33   Parameters:
34       map=name [required]
35           Name of raster map
36
37       cats=range[,range,...]
38           Category values
39           Example: 1,3,7-9,13
40
41       values=float[,float,...]
42           Comma separated value list
43           Example: 1.4,3.8,13
44
45       separator=character
46           Field separator
47           Special characters: pipe, comma, space, tab, newline
48           Default: tab
49
50       raster=name
51           Raster map from which to copy category table
52
53       rules=name
54           File containing category label rules (or "-" to read from stdin)
55
56       format=string
57           Default label or format string for dynamic labeling
58           Used when no explicit label exists for the category
59
60       coefficients=mult1,offset1,mult2,offset2
61           Dynamic label coefficients
62           Two pairs of category multiplier and offsets, for $1 and $2
63

DESCRIPTION

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
69       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
84       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

NOTES

90       Any ASCII TAB characters which may be in the label are replaced by spa‐
91       ces.
92
93       The output from r.category can be redirected into a file, or piped into
94       another program.
95
96   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
107   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
120       In the format line
121
122           •   $1 refers to the value num*5.0+1000 (ie, using the first 2  co‐
123               efficients)
124
125           •   $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
129       Also, the form $?xxx$yyy$ translates into yyy if the category is 1, xxx
130       otherwise. The $yyy$ is optional. Thus
131
132       $1 meter$?s
133
134       will become:
135       1 meter (for category 1)
136       2 meters (for category 2), etc.
137
138       format=’Elevation: $1.2 to $2.2 feet’   ## Format Statement
139       coefficients="5.0,1000,5.0,1005"   ## Coefficients
140
141       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
145       sprintf(buff,"Elevation:    %.2f    to    %.2f   feet",   num*5.0+1000,
146       num*5.0*1005)
147
148       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
152       To use a "$" in the label without triggering the plural test, put  "$$"
153       in the format string.
154
155       Use  ’single  quotes’ when using a "$" on the command line to avoid un‐
156       wanted shell substitution.
157

EXAMPLES

159       North Carolina sample dataset:
160
161   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
173       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
181       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
188   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

SEE ALSO

199       UNIX Manual entries for awk and sort
200
201        d.what.rast, r.coin, r.describe, r.support
202

AUTHORS

204       Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
205       Hamish Bowman, University of Otago, New  Zealand  (label  creation  op‐
206       tions)
207

SOURCE CODE

209       Available at: r.category source code (history)
210
211       Accessed: Saturday Jan 21 20:38:19 2023
212
213       Main  index  | Raster index | Topics index | Keywords index | Graphical
214       index | Full index
215
216       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
217
218
219
220GRASS 8.2.1                                                      r.category(1)
Impressum