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



NNAAMMEE
       rr..rraannddoomm   - Creates a raster map layer and site list file
       containing randomly located sites.
       _(_G_R_A_S_S Raster Program)

SSYYNNOOPPSSIISS
       rr..rraannddoomm
       rr..rraannddoomm hheellpp
       rr..rraannddoomm [--iiqqzz] iinnppuutt==_n_a_m_e  nnssiitteess==_n_u_m_b_e_r[%%]  [rraasstteerr__oouutt--
       ppuutt==_n_a_m_e] [ssiitteess__oouuttppuutt==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       The  program  _r_._r_a_n_d_o_m  allows the user to create a raster
       map layer and a site list file containing  coordinates  of
       points whose locations have been randomly determined.  The
       program locates these randomly generated sites within  the
       current	geographic  region and mask (if any), on non-zero
       category value data areas within a  user-specified  raster
       map  layer.   If  the user sets the --zz flag, sites will be
       randomly generated across all cells (even those with  NULL
       values).


       The  _r_a_s_t_e_r___o_u_t_p_u_t  raster  map	layer  is  created in the
       user's current mapset.  The  category  values  and  corre-
       sponding category names already associated with the random
       site locations in the _i_n_p_u_t  map  layer	are  assigned  to
       these  sites  in the _r_a_s_t_e_r___o_u_t_p_u_t map layer. If the --zz is
       specified, then a unique entry is made for the value  used
       where  the  _i_n_p_u_t was NULL.  This value is at least 1 less
       than the smallest value in the _i_n_p_u_t raster and is given a
       medium gray color.


       The _s_i_t_e___l_i_s_t_s file created by _r_._r_a_n_d_o_m contains a listing
       of the sites' coordinates; these coordinates are the  _c_e_n_-
       _t_e_r  _p_o_i_n_t_s  of	the  randomly  selected  cells.  A double
       attribute contains the cell value of the _i_n_p_u_t raster  (or
       the assigned value when --zz is used.

OOPPTTIIOONNSS
       The  user  may specify the quantity of random locations to
       be generated either as a _p_o_s_i_t_i_v_e _i_n_t_e_g_e_r (e.g.,  10),  or
       as  a  _p_e_r_c_e_n_t_a_g_e  _o_f  _t_h_e _r_a_s_t_e_r _m_a_p _l_a_y_e_r_'_s _c_e_l_l_s (e.g.,
       10%, or 3.05%).	The number of cells  considered  for  the
       percentage  reflects whether or not the --zz flag was given.
       Options are 0-100; percentages less than one  percent  may
       be stated as decimals.


       _r_._r_a_n_d_o_m  can  be  run interactively or non-interactively.
       The user may provide  program  arguments  on  the  command
       line,  specifying  an  input  map layer name (iinnppuutt==_n_a_m_e),
       output raster map layer name (rraasstteerr__oouuttppuutt==_n_a_m_e),  output
       site list file name (ssiitteess__oouuttppuutt==_n_a_m_e), and the number of
       sites to be randomly generated as a total number of  sites
       (nnssiitteess==_n_u_m_b_e_r)	or  as	a  percentage  of  the map's size
       (nnssiitteess==_n_u_m_b_e_r%%).  The user can also direct that  _r_._r_a_n_d_o_m
       run  quietly (using the --qq) option, and/or direct _r_._r_a_n_d_o_m
       to also generate random site locations against cells  con-
       taining	NULL values (using the --zz option).  The --ii can be
       used to get a count of the  total  cells  and  NULL  cells
       given the current region settings.


       Alternately, the user can simply type rr..rraannddoomm on the com-
       mand line without program arguments.  In  this  case,  the
       user will be prompted for needed inputs and option choices
       using the standard GRASS _p_a_r_s_e_r interface.



   FFllaaggss::
       --qq     Run quietly. _r_._r_a_n_d_o_m will  normally  print  output
	      messages	to  standard  output  as  it runs. The --qq
	      option will suppress the	printing  of  these  mes-
	      sages.

       --zz     Include  NULL cells in the pool from which _r_._r_a_n_d_o_m
	      will randomly generate site locations.

       --ii     Print the raster map's name and location, the total
	      number  of cells under the current region settings,
	      and the number of NULL valued cells under the  cur-
	      rent region settings.  Then exit without doing any-
	      thing.  Useful for deciding on the number of  sites
	      to have _r_._r_a_n_d_o_m create.




   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      An  existing raster map layer in the user's current
	      mapset search path.  _r_._r_a_n_d_o_m will randomly  gener-
	      ate  sites on a user-specified portion of the cells
	      in this _i_n_p_u_t raster map.

       nnssiitteess==_n_u_m_b_e_r
	      Specify the quantity of sites to be randomly gener-
	      ated as either a _p_o_s_i_t_i_v_e integer, or as a _p_e_r_c_e_n_t_-
	      _a_g_e value of the number of cells in the  _i_n_p_u_t  map
	      layer.   If stated as a positive integer, _n_u_m_b_e_r is
	      the number of sites  (i.e.,  number  of  cells)  to
	      appear in the _r_a_s_t_e_r___o_u_t_p_u_t layer and/or _s_i_t_e_s___o_u_t_-
	      _p_u_t file.
	      Options: Non-percentage values should be	given  as
	      positive	integer  values less than or equal to the
	      number of cells in the input map layer.  Percentage
	      values  given  should  be  within  the range 0.00 -
	      100.00 (decimal values are allowed).

       rraasstteerr__oouuttppuutt==_n_a_m_e
	      The new raster map layer to  hold  program  output.
	      This  map will contain the sites randomly generated
	      by _r_._r_a_n_d_o_m. If the -z flag is not set,  all  sites
	      will  be	assigned  whatever  category  values were
	      assigned these cell locations in the  _i_n_p_u_t  raster
	      map layer.  If the -z flag is set, all sites except
	      those falling on NULL cells in the _i_n_p_u_t value will
	      be  assigned  the  category  values  assigned these
	      cells in the input layer;  sites	falling  on  NULL
	      cells  in  the  _i_n_p_u_t  layer  will be assigned to a
	      newly created category in the  _r_a_s_t_e_r___o_u_t_p_u_t  layer
	      with at least one integer value less than the mini-
	      mum value in the _i_n_p_u_t layer.

       ssiitteess__oouuttppuutt==_n_a_m_e
	      The new GRASS _s_i_t_e___l_i_s_t_s file to hold program  out-
	      put.   If no _s_i_t_e_s___o_u_t_p_u_t file name is given on the
	      command line, no _s_i_t_e___l_i_s_t_s file will be created by
	      _r_._r_a_n_d_o_m.   (See	_r_a_s_t_e_r___o_u_t_p_u_t  parameter descrip-
	      tion, above.)  Note. Although  the  user	need  not
	      request  that  _r_._r_a_n_d_o_m  output  both  a raster map
	      layer  (_r_a_s_t_e_r___o_u_t_p_u_t)  and  a   site   list   file
	      (_s_i_t_e_s___o_u_t_p_u_t), the user must specify that at least
	      one of these outputs be produced.


NNOOTTEESS
       To create random site locations within some, but not  all,
       non-zero  categories  of  the  input raster map layer, the
       user must first create a reclassified raster map layer  of
       the  original raster map layer (e.g., using the GRASS pro-
       gram _r_._r_e_c_l_a_s_s) that contains only the desired categories,
       and  then  use  the reclassed raster map layer as input to
       _r_._r_a_n_d_o_m.

BBUUGGSS
       It's not possible to use the --ii flag and not also  specify
       the nnssiitteess parameter.

SSEEEE AALLSSOO
       _g_._r_e_g_i_o_n

       _r_._m_a_s_k

       _r_._r_e_c_l_a_s_s

       _s_._r_a_n_d_o_m

       _p_a_r_s_e_r

AAUUTTHHOORR
       Dr.  James  Hinthorne,  GIS Laboratory, Central Washington
       University


       Modified for GRASS 5.0 by Eric G. Miller

       _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(1)
