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__oouuttppuutt==_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 corresponding 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 ran-
       domly  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__oouutt--
       ppuutt==_n_a_m_e), output site list file name (ssiitteess__oouuttppuutt==_n_a_m_e), and the num-
       ber  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 containing NULL values (using the --zz option).  The --ii can
       be used to get a count of the total cells and NULL cells given the cur-
       rent region settings.


       Alternately,  the  user	can  simply  type rr..rraannddoomm on the command 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 inter-
       face.



   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 messages.

       --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 current region settings.  Then exit with-
	      out doing anything.  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 generate 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 generated 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 inte-
	      ger 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 val-
	      ues 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 cre-
	      ated category in the _r_a_s_t_e_r___o_u_t_p_u_t layer with at least one inte-
	      ger value less than the minimum 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 output.  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 description, 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 cat-
       egories 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 program _r_._r_e_c_l_a_s_s) that contains only the desired cate-
       gories,	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)
