1r.random(1) Grass User's Manual r.random(1)
2
6 r.random - Creates a raster map layer and vector point map containing
7 randomly located sites.
8
10 raster
11
13 r.random
14 r.random help
15 r.random [-zid] input=name [cover=name] n=number[%] [raster_out‐
16 put=name] [vector_output=name] [--overwrite] [--verbose]
17 [--quiet]
18 Flags:
20 -z
21 Generate vector points for category zero also
22 -i
24 Report information about input raster and exit
25 -d
27 Generate vector points as 3D points
28 --overwrite
30 Allow output files to overwrite existing files
31 --verbose
33 Verbose module output
34 --quiet
36 Quiet module output
37 Parameters:
39 input=name
40 Name of input raster map
41 cover=name
43 Name of cover raster map
44 n=number[%]
46 The number of points to allocate
47 raster_output=name
49 Name for output raster map
50 vector_output=name
52 Name for output vector map
53
55 The program r.random allows the user to create a raster map layer and a
56 vector points map containing coordinates of points whose locations have
57 been randomly determined. The program locates these randomly generated
58 sites (vector points) within the current geographic region and mask (if
59 any), on non-zero category value data areas within a user-specified
60 raster map layer. If the user sets the -z flag, sites will be randomly
61 generated across all cells (even those with NULL values).
62 The raster_output raster map layer is created in the user's current
64 mapset. The category values and corresponding category names already
65 associated with the random vector point locations in the input map
66 layer are assigned to these sites in the raster_output map layer. If
67 the -z is specified, then a unique entry is made for the value used
68 where the input was NULL. This value is at least 1 less than the
69 smallest value in the input raster and is given a medium gray color.
70 The vector_output file created by r.random contains a listing of the
72 sites' coordinates; these coordinates are the center points of the ran‐
73 domly selected cells. A double attribute contains the cell value of
74 the input raster (or the assigned value when -z is used. The values a
75 stored in the value column in the attached attribute table.
76 If a cover map is additionally specified, a second column covervalue
77 is populated with raster values from the cover map.
78
80 The user may specify the quantity of random locations to be generated
81 either as a positive integer (e.g., 10), or as a percentage of the
82 raster map layer's cells (e.g., 10%, or 3.05%). The number of cells
83 considered for the percentage reflects whether or not the -z flag was
84 given. Options are 0-100; percentages less than one percent may be
85 stated as decimals.
86 r.random can be run interactively or non-interactively. The user may
88 provide program arguments on the command line, specifying an input
89 raster map layer name (input=name), optionally a cover raster map layer
90 name (cover=name), output raster map layer name (raster_output=name),
91 output vector points map name (vector_output=name), and the number of
92 sites to be randomly generated as a total number of sites (n=number) or
93 as a percentage of the map's size (n=number%). The user can also
94 direct that r.random run quietly (using the -q) option, and/or direct
95 r.random to also generate random vector point locations against cells
96 containing NULL values (using the -z option). The -i can be used to
97 get a count of the total cells and NULL cells given the current region
98 settings.
99 Flags:
101 -z
102 Include NULL cells in the pool from which r.random will randomly
103 generate vector point locations.
104 -i
106 Print the raster map's name and location, the total number of
107 cells under the current region settings, and the number of NULL
108 valued cells under the current region settings. Then exit with‐
109 out doing anything. Useful for deciding on the number of sites
110 to have r.random create.
111 -d
113 Generate vector points with 3D geometry instead of 2D geometry.
114 The z values correspond to the raster map values.
115 Parameters:
117 input=name
118 An existing raster map layer in the user's current mapset search
119 path. r.random will randomly generate sites on a user-specified
120 portion of the cells in this input raster map.
121 cover=name
123 An existing raster map layer in the user's current mapset search
124 path. r.random will extract raster values at the generates ran‐
125 dom sites from this cover raster map. The cover map only gener‐
126 ates output for the vector_output map.
127 n=number
129 Specify the quantity of sites to be randomly generated as either
130 a positive integer, or as a percentage value of the number of
131 cells in the input map layer. If stated as a positive integer,
132 number is the number of sites (i.e., number of cells) to appear
133 in the raster_output layer and/or vector_output file.
134 Options: Non-percentage values should be given as positive inte‐
135 ger values less than or equal to the number of cells in the
136 input map layer. Percentage values given should be within the
137 range 0.00 - 100.00 (decimal values are allowed).
138 raster_output=name
140 The new raster map layer to hold program output. This map will
141 contain the sites randomly generated by r.random. If the -z flag
142 is not set, all sites will be assigned whatever category values
143 were assigned these cell locations in the input raster map
144 layer. If the -z flag is set, all sites except those falling on
145 NULL cells in the input value will be assigned the category val‐
146 ues assigned these cells in the input layer; sites falling on
147 NULL cells in the input layer will be assigned to a newly cre‐
148 ated category in the raster_output layer with at least one inte‐
149 ger value less than the minimum value in the input layer.
150 vector_output=name
152 The new GRASS vector_output file to hold program output. If no
153 vector_output file name is given on the command line, no vec‐
154 tor_output file will be created by r.random. (See raster_output
155 parameter description, above.) Note. Although the user need not
156 request that r.random output both a raster map layer
157 (raster_output) and a vector points map (vector_output), the
158 user must specify that at least one of these outputs be pro‐
159 duced.
160
162 To create random vector point locations within some, but not all, non-
163 zero categories of the input raster map layer, the user must first cre‐
164 ate a reclassified raster map layer of the original raster map layer
165 (e.g., using the GRASS program r.reclass) that contains only the
166 desired categories, and then use the reclassed raster map layer as
167 input to r.random.
168 If a cover raster map is specified and the cover map contains NULL (no
170 data) values, these sites are suppressed in the resulting vector_output
171 map.
172
174 Random vector elevation points sampled from elevation map in the
175 Spearfish region, result stored in 2D vector map:
176 g.region rast=elevation.10m -p
177 r.random elevation.10m vector_output=elevrand n=100
178 v.db.select elevrand
179 v.univar elevrand col=value type=point
180 Random vector elevation points sampled from elevation map in the
183 Spearfish region with collocated values sampled from landuse map,
184 result stored in 3D vector map:
185 g.region rast=elevation.10m -p
186 r.random -d elevation.10m cover=landcover.30m vector_output=luserand3d
187 n=100
188 # data output (value: elevation, covervalue: landuse class):
189 v.db.select luserand3d
190 cat|value|covervalue
191 1|1151.406616|81
192 2|1172.121216|71
193 3|1183.219604|71
194
197 It's not possible to use the -i flag and not also specify the n parame‐
198 ter.
199
201 g.region
202 r.reclass
203 v.random
204
206 Dr. James Hinthorne, GIS Laboratory, Central Washington University
207 Modified for GRASS 5.0 by Eric G. Miller
209 Cover map support by Markus Neteler, 2007
211 Last changed: $Date: 2007-10-16 14:22:54 +0200 (Tue, 16 Oct 2007) $
213 Full index
215 © 2003-2008 GRASS Development Team
217GRASS 6.3.0 r.random(1)