1r.random.surface(1) Grass 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 (SEED_MIN >= value >= SEED_MAX), 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
84 error modeling is given in the NOTES section.
85 Detailed parameter description
87 output
88 Random surface(s). The cell values are a random distribution
89 between 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
96 deviation 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
159 region 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 Random Field Software for GRASS by Chuck Ehlschlaeger
169 As part of my dissertation, I put together several programs that help
171 GRASS (4.1 and beyond) develop uncertainty models of spatial data. I
172 hope you find it useful and dependable. The following papers might
173 clarify their use:
174 · Ehlschlaeger, C.R., Shortridge, A.M., Goodchild, M.F., 1997.
176 Visualizing spatial data uncertainty using animation. Comput‐
177 ers & Geosciences 23, 387-395.
178 doi:10.1016/S0098-3004(97)00005-8
179 · Modeling Uncertainty in Elevation Data for Geographical Analy‐
181 sis, by Charles R. Ehlschlaeger, and Ashton M. Shortridge.
182 Proceedings of the 7th International Symposium on Spatial Data
183 Handling, Delft, Netherlands, August 1996.
184 · Dealing with Uncertainty in Categorical Coverage Maps: Defin‐
186 ing, Visualizing, and Managing Data Errors, by Charles
187 Ehlschlaeger and Michael Goodchild. Proceedings, Workshop on
188 Geographic Information Systems at the Conference on Information
189 and Knowledge Management, Gaithersburg MD, 1994.
190 · Uncertainty in Spatial Data: Defining, Visualizing, and Manag‐
192 ing Data Errors, by Charles Ehlschlaeger and Michael Goodchild.
193 Proceedings, GIS/LIS’94, pp. 246-253, Phoenix AZ, 1994.
194
196 r.random, r.random.cells, r.mapcalc, r.surf.random
197
199 Charles Ehlschlaeger, Michael Goodchild, and Chih-chang Lin; National
200 Center for Geographic Information and Analysis, University of Califor‐
201 nia, Santa Barbara.
202 Last changed: $Date: 2016-06-02 22:48:17 +0200 (Thu, 02 Jun 2016) $
204
206 Available at: r.random.surface source code (history)
207 Main index | Raster index | Topics index | Keywords index | Graphical
209 index | Full index
210 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
212GRASS 7.4.4 r.random.surface(1)