1r.random.surface(1)           Grass User's Manual          r.random.surface(1)
2
3
4

NAME

6       r.random.surface   -  Generates  random  surface(s) with spatial depen‐
7       dence.
8

KEYWORDS

10       raster, surface, random
11

SYNOPSIS

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
19   Flags:
20       -u
21           Uniformly distributed cell values
22
23       --overwrite
24           Allow output files to overwrite existing files
25
26       --help
27           Print usage summary
28
29       --verbose
30           Verbose module output
31
32       --quiet
33           Quiet module output
34
35       --ui
36           Force launching GUI dialog
37
38   Parameters:
39       output=string[,string,...] [required]
40           Name for output raster map(s)
41
42       distance=float
43           Maximum distance of spatial correlation (value >= 0.0)
44           Default: 0.0
45
46       exponent=float
47           Distance decay exponent (value > 0.0)
48           Default: 1.0
49
50       flat=float
51           Distance filter remains flat before beginning exponent
52           Default: 0.0
53
54       seed=integer
55           Random seed (SEED_MIN >= value >= SEED_MAX), default [random]
56
57       high=integer
58           Maximum cell value of distribution
59           Default: 255
60

DESCRIPTION

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
75       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
82       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
86   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
98       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
111       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
121       flat
122           Flat determines the distance at which the filter.
123
124       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
133       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
142       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

NOTES

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
153       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
163       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

REFERENCES

168       Random Field Software for GRASS by Chuck Ehlschlaeger
169
170       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
175           ·   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
180           ·   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
185           ·   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
191           ·   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

SEE ALSO

196        r.random, r.random.cells, r.mapcalc, r.surf.random
197

AUTHORS

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
203       Last changed: $Date: 2016-06-02 22:48:17 +0200 (Thu, 02 Jun 2016) $
204

SOURCE CODE

206       Available at: r.random.surface source code (history)
207
208       Main  index  | Raster index | Topics index | Keywords index | Graphical
209       index | Full index
210
211       © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
212
213
214
215GRASS 7.4.4                                                r.random.surface(1)
Impressum