1r.random.surface(1) GRASS GIS User's Manual r.random.surface(1)
2
6 r.random.surface - Generates random surface(s) with spatial depen‐
7 dence.
8
10 raster, surface, random
11
13 r.random.surface
14 r.random.surface --help
15 r.random.surface [-u] output=string[,string,...] [distance=float]
16 [exponent=float] [flat=float] [seed=integer] [high=integer]
17 [--overwrite] [--help] [--verbose] [--quiet] [--ui]
18 Flags:
20 -u
21 Uniformly distributed cell values
22 --overwrite
24 Allow output files to overwrite existing files
25 --help
27 Print usage summary
28 --verbose
30 Verbose module output
31 --quiet
33 Quiet module output
34 --ui
36 Force launching GUI dialog
37 Parameters:
39 output=string[,string,...]Â [required]
40 Name for output raster map(s)
41 distance=float
43 Maximum distance of spatial correlation (value >= 0.0)
44 Default: 0.0
45 exponent=float
47 Distance decay exponent (value > 0.0)
48 Default: 1.0
49 flat=float
51 Distance filter remains flat before beginning exponent
52 Default: 0.0
53 seed=integer
55 Random seed, default [random]
56 high=integer
58 Maximum cell value of distribution
59 Default: 255
60
62 r.random.surface generates a spatially dependent random surface. The
63 random surface is composed of values representing the deviation from
64 the mean of the initial random values driving the algorithm. The ini‐
65 tial random values are independent Gaussian random deviates with a mean
66 of 0 and standard deviation of 1. The initial values are spread over
67 each output map using filter(s) of diameter distance. The influence of
68 each random value on nearby cells is determined by a distance decay
69 function based on exponent. If multiple filters are passed over the
70 output maps, each filter is given a weight based on the weight inputs.
71 The resulting random surface can have any mean and variance, but the
72 theoretical mean of an infinitely large map is 0.0 and a variance of
73 1.0. Description of the algorithm is in the NOTES section.
74 The random surface generated are composed of floating point numbers,
76 and saved in the category description files of the output map(s). Cell
77 values are uniformly or normally distributed between 1 and high values
78 inclusive (determined by whether the -u flag is used). The category
79 names indicate the average floating point value and the range of float‐
80 ing point values that each cell value represents.
81 r.random.surface’s original goal is to generate random fields for spa‐
83 tial error modeling. A procedure to use r.random.surface in spatial er‐
84 ror modeling is given in the NOTES section.
85 Detailed parameter description
87 output
88 Random surface(s). The cell values are a random distribution be‐
89 tween the low and high values inclusive. The category values of
90 the output map(s) are in the form #.# #.# to #.# where each #.# is
91 a floating point number. The first number is the average of the
92 random values the cell value represents. The other two numbers are
93 the range of random values for that cell value. The average mean
94 value of generated output map(s) is 0. The average variance of
95 map(s) generated is 1. The random values represent the standard de‐
96 viation from the mean of that random surface.
97 distance
99 Distance determines the spatial dependence of the output map(s).
100 The distance value indicates the minimum distance at which two map
101 cells have no relationship to each other. A distance value of 0.0
102 indicates that there is no spatial dependence (i.e., adjacent cell
103 values have no relationship to each other). As the distance value
104 increases, adjacent cell values will have values closer to each
105 other. But the range and distribution of cell values over the out‐
106 put map(s) will remain the same. Visually, the clumps of lower and
107 higher values gets larger as distance increases. If multiple values
108 are given, each output map will have multiple filters, one for each
109 set of distance, exponent, and weight values.
110 exponent
112 Exponent determines the distance decay exponent for a particular
113 filter. The exponent value(s) have the property of determining the
114 texture of the random surface. Texture will decrease as the expo‐
115 nent value(s) get closer to 1.0. Normally, exponent will be 1.0 or
116 less. If there are no exponent values given, each filter will be
117 given an exponent value of 1.0. If there is at least one exponent
118 value given, there must be one exponent value for each distance
119 value.
120 flat
122 Flat determines the distance at which the filter.
123 weight
125 Weight determines the relative importance of each filter. For exam‐
126 ple, if there were two filters driving the algorithm and
127 weight=1.0, 2.0 was given in the command line: The second filter
128 would be twice as important as the first filter. If no weight val‐
129 ues are given, each filter will be just as important as the other
130 filters defining the random field. If weight values exist, there
131 must be a weight value for each filter of the random field.
132 high
134 Specifies the high end of the range of cell values in the output
135 map(s). Specifying a very large high value will minimize the errors
136 caused by the random surface’s discretization. The word errors is
137 in quotes because errors in discretization are often going to can‐
138 cel each other out and the spatial statistics are far more sensi‐
139 tive to the initial independent random deviates than any potential
140 discretization errors.
141 seed
143 Specifies the random seed(s), one for each map, that r.random.sur‐
144 face will use to generate the initial set of random values that the
145 resulting map is based on. If the random seed is not given, r.ran‐
146 dom.surface will get a seed from the process ID number.
147
149 While most literature uses the term random field instead of random sur‐
150 face, this algorithm always generates a surface. Thus, its use of ran‐
151 dom surface.
152 r.random.surface builds the random surface using a filter algorithm
154 smoothing a map of independent random deviates. The size of the filter
155 is determined by the largest distance of spatial dependence. The shape
156 of the filter is determined by the distance decay exponent(s), and the
157 various weights if different sets of spatial parameters are used. The
158 map of independent random deviates will be as large as the current re‐
159 gion PLUS the extent of the filter. This will eliminate edge effects
160 caused by the reduction of degrees of freedom. The map of independent
161 random deviates will ignore the current mask for the same reason.
162 One of the most important uses for r.random.surface is to determine how
164 the error inherent in raster maps might effect the analyses done with
165 those maps.
166
168 Generate a random surface (using extent of North Carolina sample
169 dataset):
170 g.region raster=elevation res=100 -p
171 r.surf.random output=randomsurf min=10 max=100
172 # verify distribution
173 r.univar -e map=randomsurf
174 Figure: Random surface example (min: 10; max: 100)
175 With the histogram tool the cell values versus count can be shown.
177 Figure: Histogram of random surface example (min: 10; max: 100)
179
181 Random Field Software for GRASS by Chuck Ehlschlaeger
182 As part of my dissertation, I put together several programs that help
184 GRASS (4.1 and beyond) develop uncertainty models of spatial data. I
185 hope you find it useful and dependable. The following papers might
186 clarify their use:
187 • Ehlschlaeger, C.R., Shortridge, A.M., Goodchild, M.F., 1997.
189 Visualizing spatial data uncertainty using animation. Comput‐
190 ers & Geosciences 23, 387-395.
191 doi:10.1016/S0098-3004(97)00005-8
192 • Ehlschlaeger, C.R., Shortridge, A.M., 1996. Modeling Uncer‐
194 tainty in Elevation Data for Geographical Analysis. Proceedings
195 of the 7th International Symposium on Spatial Data Handling,
196 Delft, Netherlands, August 1996.
197 • Ehlschlaeger, C.R., Goodchild, M.F., 1994. Dealing with Uncer‐
199 tainty in Categorical Coverage Maps: Defining, Visualizing, and
200 Managing Data Errors. Proceedings, Workshop on Geographic In‐
201 formation Systems at the Conference on Information and Knowl‐
202 edge Management, Gaithersburg MD, 1994.
203 • Ehlschlaeger, C.R., Goodchild, M.F., 1994. Uncertainty in Spa‐
205 tial Data: Defining, Visualizing, and Managing Data Errors.
206 Proceedings, GIS/LIS’94, pp. 246-253, Phoenix AZ, 1994.
207
209 r.random, r.random.cells, r.mapcalc, r.surf.random
210
212 Charles Ehlschlaeger, Michael Goodchild, and Chih-chang Lin; National
213 Center for Geographic Information and Analysis, University of Califor‐
214 nia, Santa Barbara
215
217 Available at: r.random.surface source code (history)
218 Accessed: Saturday Oct 28 18:17:53 2023
220 Main index | Raster index | Topics index | Keywords index | Graphical
222 index | Full index
223 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
225GRASS 8.3.1 r.random.surface(1)