Provided by: grass-doc_6.4.3-3_all bug

NAME

       r.random.surface  - Generates random surface(s) with spatial dependence.

KEYWORDS

       raster, random, surface

SYNOPSIS

       r.random.surface
       r.random.surface help
       r.random.surface   [-uq]   output=name[,name,...]    [distance=float]     [exponent=float]
       [flat=float]   [seed=integer]   [high=integer]   [--overwrite]  [--verbose]  [--quiet]

   Flags:
       -u
           Uniformly distributed cell values

       -q
           No (quiet) description during run

       --overwrite
           Allow output files to overwrite existing files

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       output=name[,name,...]
           Name for output raster map(s)

       distance=float
           Maximum distance of spatial correlation (value >= 0.0)
           Default: 0.0

       exponent=float
           Distance decay exponent (value > 0.0)
           Default: 1.0

       flat=float
           Distance filter remains flat before beginning exponent
           Default: 0.0

       seed=integer
           Random seed (SEED_MIN >= value >= SEED_MAX) (default: random)

       high=integer
           Maximum cell value of distribution
           Default: 255

DESCRIPTION

       r.random.surface generates a spatially dependent random surface.  The  random  surface  is
       composed  of  values representing the deviation from the mean of the initial random values
       driving the algorithm. The initial random values are independent Gaussian random  deviates
       with  a  mean  of  0  and standard deviation of 1. The initial values are spread over each
       output map using filter(s) of diameter distance.  The influence of each  random  value  on
       nearby  cells  is  determined by a distance decay function based on exponent.  If multiple
       filters are passed over the output maps, each filter is given a weight based on the weight
       inputs.   The resulting random surface can have any mean and variance, but the theoretical
       mean of an infinitely large map is 0.0 and a variance of 1.0. Description of the algorithm
       is in the NOTES section.

       The  random  surface  generated  are  composed of floating point numbers, and saved in the
       category description files of the output map(s).  Cell values are  uniformly  or  normally
       distributed  between  1  and  high  values inclusive (determined by whether the -u flag is
       used). The category names indicate the average floating  point  value  and  the  range  of
       floating point values that each cell value represents.

       r.random.surface's  original goal is to generate random fields for spatial error modeling.
       A procedure to use r.random.surface in spatial  error  modeling  is  given  in  the  NOTES
       section.

   Detailed parameter description
       output
           Random  surface(s). The cell values are a random distribution between the low and high
           values inclusive.  The category values of the output map(s) are in the form #.# #.# to
           #.#  where each #.# is a floating point number. The first number is the average of the
           random values the cell value represents. The other two numbers are the range of random
           values  for  that  cell value. The average mean value of generated output map(s) is 0.
           The average variance of map(s)  generated  is  1.  The  random  values  represent  the
           standard deviation from the mean of that random surface.

       distance
           Distance  determines  the  spatial dependence of the output map(s). The distance value
           indicates the minimum distance at which two map cells have  no  relationship  to  each
           other.  A  distance  value of 0.0 indicates that there is no spatial dependence (i.e.,
           adjacent cell values have no relationship  to  each  other).  As  the  distance  value
           increases,  adjacent  cell values will have values closer to each other. But the range
           and distribution of  cell  values  over  the  output  map(s)  will  remain  the  same.
           Visually,  the clumps of lower and higher values gets larger as distance increases. If
           multiple values are given, each output map will have multiple filters,  one  for  each
           set of distance, exponent, and weight values.

       exponent
           Exponent  determines the distance decay exponent for a particular filter. The exponent
           value(s) have the property of determining the texture of the random  surface.  Texture
           will  decrease  as the exponent value(s) get closer to 1.0. Normally, exponent will be
           1.0 or less. If there are no exponent values given,  each  filter  will  be  given  an
           exponent  value  of  1.0. If there is at least one exponent value given, there must be
           one exponent value for each distance value.

       flat
           Flat determines the distance at which the filter.

       weight
           Weight determines the relative importance of each filter. For example, if  there  were
           two  filters  driving the algorithm and weight=1.0, 2.0 was given in the command line:
           The second filter would be twice as important as the first filter. If no weight values
           are  given,  each  filter  will be just as important as the other filters defining the
           random field. If weight values exist, there must be a weight value for each filter  of
           the random field.

       high
           Specifies  the high end of the range of cell values in the output map(s). Specifying a
           very large high value  will  minimize  the  errors  caused  by  the  random  surface's
           discretization.  The  word  errors  is  in quotes because errors in discretization are
           often going to cancel each other out and the spatial statistics are far more sensitive
           to the initial independent random deviates than any potential discretization errors.

       seed
           Specifies  the  random  seed(s),  one  for each map, that r.random.surface will use to
           generate the initial set of random values that the resulting map is based on.  If  the
           random seed is not given, r.random.surface will get a seed from the process ID number.

NOTES

       While most literature uses the term random field instead of random surface, this algorithm
       always generates a surface. Thus, its use of random surface.

       r.random.surface builds the random surface using a filter algorithm  smoothing  a  map  of
       independent  random deviates. The size of the filter is determined by the largest distance
       of spatial dependence. The shape of  the  filter  is  determined  by  the  distance  decay
       exponent(s), and the various weights if different sets of spatial parameters are used. The
       map of independent random deviates will be as large as the current region PLUS the  extent
       of  the  filter.  This  will  eliminate edge effects caused by the reduction of degrees of
       freedom. The map of independent random deviates will ignore the current mask for the  same
       reason.

       One of the most important uses for r.random.surface is to determine how the error inherent
       in raster maps might effect the analyses done with those maps.

REFERENCES

       Random Field Software for GRASS by Chuck Ehlschlaeger

       As part of my dissertation, I put together several  programs  that  help  GRASS  (4.1  and
       beyond)  develop  uncertainty  models  of  spatial  data.  I  hope  you find it useful and
       dependable. The following papers might clarify their use:

                      Ehlschlaeger, C.R., Shortridge, A.M., Goodchild, M.F.,  1997.   Visualizing
                     spatial  data  uncertainty  using  animation.   Computers  & Geosciences 23,
                     387-395. doi:10.1016/S0098-3004(97)00005-8

                     Modeling Uncertainty in Elevation Data for Geographical Analysis, by Charles
                     R.   Ehlschlaeger,  and  Ashton  M.   Shortridge.  Proceedings  of  the  7th
                     International Symposium on Spatial Data Handling, Delft, Netherlands, August
                     1996.

                     Dealing   with   Uncertainty   in   Categorical   Coverage  Maps:  Defining,
                     Visualizing, and Managing Data Errors, by Charles Ehlschlaeger  and  Michael
                     Goodchild.   Proceedings,  Workshop on Geographic Information Systems at the
                     Conference on Information and Knowledge Management, Gaithersburg MD, 1994.

                     Uncertainty in  Spatial  Data:  Defining,  Visualizing,  and  Managing  Data
                     Errors,   by   Charles  Ehlschlaeger  and  Michael  Goodchild.  Proceedings,
                     GIS/LIS'94, pp. 246-253, Phoenix AZ, 1994.

SEE ALSO

        r.random, r.random.cell, r.mapcalc

AUTHORS

       Charles  Ehlschlaeger,  Michael  Goodchild,  and  Chih-chang  Lin;  National  Center   for
       Geographic Information and Analysis, University of California, Santa Barbara.

       Last changed: $Date: 2011-10-07 12:53:04 -0700 (Fri, 07 Oct 2011) $

       Full index

       © 2003-2013 GRASS Development Team