1r.random.surface(1)         GRASS GIS 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, 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 er‐
84       ror 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  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
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 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
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

EXAMPLE

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
176       With the histogram tool the cell values versus count can be shown.
177
178       Figure: Histogram of random surface example (min: 10; max: 100)
179

REFERENCES

181       Random Field Software for GRASS by Chuck Ehlschlaeger
182
183       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
188           •   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
193           •   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
198           •   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
204           •   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

SEE ALSO

209        r.random, r.random.cells, r.mapcalc, r.surf.random
210

AUTHORS

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

SOURCE CODE

217       Available at: r.random.surface source code (history)
218
219       Accessed: Saturday Oct 28 18:17:53 2023
220
221       Main index | Raster index | Topics index | Keywords index  |  Graphical
222       index | Full index
223
224       © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
225
226
227
228GRASS 8.3.1                                                r.random.surface(1)
Impressum