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 [-qzid] input=name n=number[%] [raster_output=name] [vec‐
16 tor_output=name] [--overwrite]
17 Flags:
19 -q Run quietly
20 -z Generate vector points for category zero also
22 -i Report information about input raster and exit
24 -d Generate vector points as 3D points
26 --overwrite
28 Parameters:
30 input=name
31 Name of existing raster map
32 n=number[%]
34 The number of points to allocate
35 raster_output=name
37 Name for output raster map
38 vector_output=name
40 Name for output vector map
41
43 The program r.random allows the user to create a raster map layer and a
44 vector points map containing coordinates of points whose locations have
45 been randomly determined. The program locates these randomly generated
46 sites (vector points) within the current geographic region and mask (if
47 any), on non-zero category value data areas within a user-specified
48 raster map layer. If the user sets the -z flag, sites will be randomly
49 generated across all cells (even those with NULL values).
50 The raster_output raster map layer is created in the user's current
52 mapset. The category values and corresponding category names already
53 associated with the random vector point locations in the input map
54 layer are assigned to these sites in the raster_output map layer. If
55 the -z is specified, then a unique entry is made for the value used
56 where the input was NULL. This value is at least 1 less than the
57 smallest value in the input raster and is given a medium gray color.
58 The vector_output file created by r.random contains a listing of the
60 sites' coordinates; these coordinates are the center points of the ran‐
61 domly selected cells. A double attribute contains the cell value of
62 the input raster (or the assigned value when -z is used.
63
65 The user may specify the quantity of random locations to be generated
66 either as a positive integer (e.g., 10), or as a percentage of the
67 raster map layer's cells (e.g., 10%, or 3.05%). The number of cells
68 considered for the percentage reflects whether or not the -z flag was
69 given. Options are 0-100; percentages less than one percent may be
70 stated as decimals.
71 r.random can be run interactively or non-interactively. The user may
73 provide program arguments on the command line, specifying an input map
74 layer name (input=name), output raster map layer name (raster_out‐
75 put=name), output vector points map name (vector_output=name), and the
76 number of sites to be randomly generated as a total number of sites
77 (n=number) or as a percentage of the map's size (n=number%). The user
78 can also direct that r.random run quietly (using the -q) option, and/or
79 direct r.random to also generate random vector point locations against
80 cells containing NULL values (using the -z option). The -i can be used
81 to get a count of the total cells and NULL cells given the current
82 region settings.
83 Alternately, the user can simply type r.random on the command line
85 without program arguments. In this case, the user will be prompted for
86 needed inputs and option choices using the standard GRASS parser inter‐
87 face.
88 Flags:
90 -q Run quietly. r.random will normally print output messages to
91 standard output as it runs. The -q option will suppress the
92 printing of these messages.
93 -z Include NULL cells in the pool from which r.random will randomly
95 generate vector point locations.
96 -i Print the raster map's name and location, the total number of
98 cells under the current region settings, and the number of NULL
99 valued cells under the current region settings. Then exit with‐
100 out doing anything. Useful for deciding on the number of sites
101 to have r.random create.
102 -d Generate vector points with 3D geometry instead of 2D geometry.
104 The z values correspond to the raster map values.
105 Parameters:
107 input=name
108 An existing raster map layer in the user's current mapset search
109 path. r.random will randomly generate sites on a user-specified
110 portion of the cells in this input raster map.
111 n=number
113 Specify the quantity of sites to be randomly generated as either
114 a positive integer, or as a percentage value of the number of
115 cells in the input map layer. If stated as a positive integer,
116 number is the number of sites (i.e., number of cells) to appear
117 in the raster_output layer and/or vector_output file.
118 Options: Non-percentage values should be given as positive inte‐
119 ger values less than or equal to the number of cells in the
120 input map layer. Percentage values given should be within the
121 range 0.00 - 100.00 (decimal values are allowed).
122 raster_output=name
124 The new raster map layer to hold program output. This map will
125 contain the sites randomly generated by r.random. If the -z flag
126 is not set, all sites will be assigned whatever category values
127 were assigned these cell locations in the input raster map
128 layer. If the -z flag is set, all sites except those falling on
129 NULL cells in the input value will be assigned the category val‐
130 ues assigned these cells in the input layer; sites falling on
131 NULL cells in the input layer will be assigned to a newly cre‐
132 ated category in the raster_output layer with at least one inte‐
133 ger value less than the minimum value in the input layer.
134 vector_output=name
136 The new GRASS vector_output file to hold program output. If no
137 vector_output file name is given on the command line, no vec‐
138 tor_output file will be created by r.random. (See raster_output
139 parameter description, above.) Note. Although the user need not
140 request that r.random output both a raster map layer
141 (raster_output) and a vector points map (vector_output), the
142 user must specify that at least one of these outputs be pro‐
143 duced.
144
146 To create random vector point locations within some, but not all, non-
147 zero categories of the input raster map layer, the user must first cre‐
148 ate a reclassified raster map layer of the original raster map layer
149 (e.g., using the GRASS program r.reclass) that contains only the
150 desired categories, and then use the reclassed raster map layer as
151 input to r.random.
152
154 Random vector elevation points sampled from elevation map in the
155 Spearfish region:
156 r.random elevation.10m vector_output=elevrand n=100
157 v.db.select elevrand
158 v.univar elevrand col=value type=point
159
162 It's not possible to use the -i flag and not also specify the n parame‐
163 ter.
164
166 g.region
167 r.reclass
168 v.random
169
171 Dr. James Hinthorne, GIS Laboratory, Central Washington University
172 Modified for GRASS 5.0 by Eric G. Miller
174 Last changed: $Date: 2007/06/01 07:34:06 $
176 Full index
178GRASS 6.2.2 r.random(1)