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 spatial 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_)]	[eexxppoo--
       nneenntt_=_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 representing the deviation from
       the mean of the initial random values driving the algorithm.  The  ini-
       tial 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 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 float-
       ing point values that each cell value represents.


       _r_._r_a_n_d_o_m_._s_u_r_f_a_c_e_'_s original goal is to generate random fields for  spa-
       tial  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 information to stan-
	      dard output.

       --uu     This  flag will make the output map's cell values have a uniform
	      distribution instead of a normal distribution. Uniform distribu-
	      tions  are useful in situations where the user wants random val-
	      ues 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 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 &quot;average&quot; mean value of generated _o_u_t_-
	      _p_u_t  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.

       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 values have no rela-
	      tionship to each other). As the distance value increases,  adja-
	      cent  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.

       eexxppoonneenntt
	      Input value(s) [default 1.0]: 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 expo-
	      nent 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  fil-
	      ters  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 ran-
	      dom  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  sur-
	      face'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  dis-
	      cretization errors.

       sseeeedd   Input  value(s)  [default random]: Specifies the random 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 sur-
       face, this algorithm always generates a surface. Thus, its use of  ran-
       dom 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 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_._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. Good-
       child. Submitted  to  Computers	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, Nether-
       lands, August 1996.


       "Dealing with Uncertainty in Categorical Coverage Maps: Defining, Visu-
       alizing, 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.


       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 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:

       "Visualizing Spatial Data Uncertainty Using Animation  (final  draft),"
       by Charles R.  Ehlschlaeger, Ashton M. Shortridge, and Michael F. Good-
       child. Submitted  to  Computers	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, Nether-
       lands, August 1996.

       "Dealing with Uncertainty in Categorical Coverage Maps: Defining, Visu-
       alizing, 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.

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

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_3_/_0_2_/_0_9 _1_2_:_0_7_:_2_3 _$



GRASS 5.0						   r.random.surface(1)
