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



NNAAMMEE
       _r_._r_a_n_d_o_m_._s_u_r_f_a_c_e  -  generates random surface(s) with spa-
       tial dependence.

       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..rraannddoomm..ssuurrffaaccee

       rr..rraannddoomm..ssuurrffaaccee hheellpp

       rr..rraannddoomm..ssuurrffaaccee [[--uuqq]] oouuttppuutt_=_n_a_m_e_(_s_)  [ddiissttaannccee_=_v_a_l_u_e_(_s_)]
       [eexxppoonneenntt_=_v_a_l_u_e_(_s_)]    [ffllaatt_=_v_a_l_u_e_(_s_)]	[wweeiigghhtt_=_v_a_l_u_e_(_s_)]
       [sseeeedd_=_v_a_l_u_e] [hhiigghh_=_v_a_l_u_e]

DDEESSCCRRIIPPTTIIOONN
       _r_._r_a_n_d_o_m_._s_u_r_f_a_c_e generates a  spatially	dependent  random
       surface.   The random surface is composed of values repre-
       senting 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 NNOOTTEESS 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  nor-
       mally  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 repre-
       sents.


       _r_._r_a_n_d_o_m_._s_u_r_f_a_c_e_'_s  original  goal  is  to generate random
       fields for spatial error  modeling.  A  procedure  to  use
       _r_._r_a_n_d_o_m_._s_u_r_f_a_c_e in spatial error modeling is given in the
       NNOOTTEESS section.

OOPPTTIIOONNSS
   FFllaaggss::
       --qq     This flag prevents the program from sending  infor-
	      mation to standard output.

       --uu     This  flag  will	make the output map's cell values
	      have a uniform distribution  instead  of	a  normal
	      distribution.  Uniform  distributions are useful in
	      situations where the user wants random values for a
	      range  of  integer  values.  The user then uses the
	      cell values instead of the  random  values  in  the
	      category description file. The uniform flag is also
	      useful when the random values  near  the	mean  are
	      more meaningful to the user. The flag on will cause
	      the cell values from low to high to have	an  equal
	      chance  of  being used. Thus, not using the flag is
	      useful in situations where  you  want  to  use  the
	      floating	point numbers in the category description
	      in your analysis. Keeping this flag off will  allow
	      the  outliers of the random distribution to be more
	      accurately represented. See the NNOOTTEESS  section  for
	      example use of this flag.


   PPaarraammeetteerrss::
       oouuttppuutt Output  map(s):  Random surface(s). The cell values
	      are a random distribution between the low and  high
	      values  inclusive.  The category values of the out-
	      put map(s) are in the form "#.# #.# to  #.#"  where
	      each #.# is a floating point number. The first num-
	      ber 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
	      &quot;average&quot;  mean value of generated _o_u_t_p_u_t
	      map(s) is 0. The "average" variance of map(s)  gen-
	      erated  is 1. The random values represent the stan-
	      dard deviation from the mean of  that  random  sur-
	      face.

       ddiissttaannccee
	      Input  value(s)  [default 0.0]: 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  val-
	      ues  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 out-
	      put map will have multiple filters,  one	for  each
	      set of distance, exponent, and weight values.

       eexxppoonneenntt
	      Input  value(s)  [default 1.0]: exponent determines
	      the distance decay exponent for a  particular  fil-
	      ter.  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.

       ffllaatt   Input  value(s)  [default 0.0]: flat determines the
	      distance at which the filter

       wweeiigghhtt Input value(s) [default 1.0]: 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  fil-
	      ters  defining  the  random field. If weight values
	      exist, there must be a weight value for each filter
	      of the random field.

       hhiigghh   Input  value  [default 255]: 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  dis-
	      cretization.  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.

       sseeeedd   Input value(s) [default random]: Specifies the ran-
	      dom  seed(s),  one for each map, that _r_._r_a_n_d_o_m_._s_u_r_-
	      _f_a_c_e 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_._r_a_n_d_o_m_._s_u_r_f_a_c_e will get
	      a seed from the process ID number.


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


       _r_._r_a_n_d_o_m_._s_u_r_f_a_c_e  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 dis-
       tance of spatial dependence. The shape of  the  filter  is
       determined by the distance decay exponent(s), and the var-
       ious 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 devi-
       ates will ignore the current mask for the same reason.


       One  of the most important uses for _r_._r_a_n_d_o_m_._s_u_r_f_a_c_e is to
       determine how the error	inherent  in  raster  maps  might
       effect the analyses done with those maps. If you wanted to
       check to see how sensitive your analysis is to the  errors
       in the DEMs in your study area, see:

       "Visualizing  Spatial  Data  Uncertainty  Using	Animation
       (final draft)," by  Charles  R.	Ehlschlaeger,  Ashton  M.
       Shortridge, and Michael F. Goodchild. Submitted to Comput-
       ers in GeoSciences in September, 1996,  accepted  October,
       1996 for publication in June, 1997.


       "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  Confer-
       ence 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.


       If  you	are interested in creating potential realizations
       of categorical coverage maps, see _r_._r_a_n_d_o_m_._m_o_d_e_l.

SSEEEE AALLSSOO
       _r_._r_a_n_d_o_m_, _r_._m_a_p_c_a_l_c_, _r_._m_a_s_k_, _s_._r_a_n_d_o_m


RREEFFEERREENNCCEESS
       Random Field Software for GRASS by Chuck Ehlschlaeger



       As part of my dissertation, I put  together  several  pro-
       grams 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:

       "Visualizing  Spatial  Data  Uncertainty  Using	Animation
       (final draft)," by Charles  R.	Ehlschlaeger,  Ashton  M.
       Shortridge, and Michael F. Goodchild. Submitted to Comput-
       ers in GeoSciences in September, 1996,  accepted  October,
       1996 for publication in June, 1997.

       "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  Confer-
       ence 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.

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

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0				      r.random.surface(1)
