.TH r.random
.SH NAME
\fIr.random\fR \- Creates a raster map layer and site list file
containing randomly located sites.
.br
\fI(GRASS Raster Program)\fR
.SH SYNOPSIS
.B r.random
.br
\fBr.random help\fR
.br
\fBr.random [\fB-qz\fR] \fBinput\*=\fIname \fBnsites\*=\fInumber\fR[\fB%\fR] \
[\fBraster_output\*=\fIname\fR] [\fBsites_output\*=\fIname\fR]
.SH DESCRIPTION
The program \fIr.random\fR allows the user to create a raster map layer
and a site list file containing geographic 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 -z flag, sites will be randomly generated across all cells
(even those assigned category value 0).

The \fIraster_output\fR 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 \fIinput\fR map layer are assigned
to these sites in the \fIraster_output\fR map layer.
.\" A color table, designed to contrast with that assigned
.\" to the \fIinput\fR, is generated for the \fIraster_output\fR.

The \fIsite_lists\fR file created by \fIr.random\fR contains a listing of
the sites' geographic coordinates;  these coordinates
are the \fIcenter points\fR of the randomly selected cells.
.SH OPTIONS
The user may specify the quantity of random locations to be generated
either as a \fIpositive integer\fR (e.g., 10), or as a
\fIpercentage of the raster map layer's total area\fR (e.g., 10%, or 3.05%).
If unspecified, the number of sites is set to '0' by default.
If stated as a percentage of the raster map's total size, the number
of random locations generated will be set equal to the number of cells contained
within the stated percentage of the raster map layer.
Options are 0-100;  percentages less than one percent may be stated as decimals.
The default percentage value used, if unspecified by the user, is '0'.
(Note that choosing 1% of a raster map's cells frequently produces an abundance
of random locations.)

\fIr.random\fR can be run interactively or non-interactively.
The user may provide program arguments on the command line, specifying
an input map layer name (input\*=\fIname\fR),
output raster map layer name (raster_output\*=\fIname\fR),
output site list file name (sites_output\*=\fIname\fR), 
and (optionally) give the number of sites to be randomly generated as
a total number of sites (nsites\*=\fInumber\fR)
or as a percentage of the map's size (nsites\*=\fInumber\fR%).
The user can also direct that \fIr.random\fR run quietly
(using the \fI-q\fR) option, and/or direct \fIr.random\fR to
also generate random site locations against cells containing category zero
(using the \fI-z\fR option).

Alternately, the user can simply type \fBr.random\fR 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 user interface
described in the manual entry for \fIparser\fR.
.LP
\fBFlags:\fR
.IP \fB-q\fR 18
Run quietly.  \fIr.random\fR will normally print output messages
to standard output as it runs. The -q option will suppress the printing of
these messages.
.IP \fB-z\fR 18
Include areas assigned a category value of zero within the pool of areas
within which \fIr.random\fR will randomly generate site locations.
If the -z option is specified, sites that fall in areas assigned
a category value of zero in the input map layer
will be assigned to a newly-created category in the output raster map layer.
If the -z flag is not set, cells having category value 0 in the output layer
will represent the areas at which randomly-located sites were not placed.
.LP
\fBParameters:\fR
.IP \fBinput\*=\fIname\fR 18
An existing raster map layer in the user's current mapset search path.
\fIr.random\fR will randomly generate sites on a user-specified portion
of the cells in this \fIinput\fR raster map.
.IP "\fBnsites\*=\fInumber\fR  or  \fBnsites\*=\fInumber\fB%\fR" 18
Allows the user to specify the quantity of sites to be randomly generated as
either a \fIpositive integer\fR, or
as a \fIpercentage value\fR of the number of cells in the \fIinput\fR map layer.
If stated as a positive integer, \fInumber\fR is
the number of sites (i.e., number of cells) to appear
in the \fIraster_output\fR layer and/or \fIsites_output\fR file.
.br
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).
.IP \fBraster_output\*=\fIname\fR 18
The new raster map layer to hold program output.  This map will contain
the sites randomly generated by \fIr.random\fR.  If the -z flag is not set,
all sites will be assigned whatever category values were assigned these
cell locations in the \fIinput\fR raster map layer.
If the -z flag is set, all sites except those falling on cells assigned
category value 0 in the \fIinput\fR value will be assigned the category values
assigned these cells in the input layer;  sites falling on cells assigned
category value 0 in the \fIinput\fR layer will be assigned to a newly created
category in the \fIraster_output\fR layer.
.IP \fBsites_output\*=\fIname\fR 18
The new GRASS \fIsite_lists\fR file to hold program output.
If no \fIsites_output\fR file name is given on the command line,
no \fIsite_lists\fR file will be created by \fIr.random\fR.
(See \fIraster_output\fR parameter description, above.)

Note.  Although the user need not request that \fIr.random\fR output
both a raster map layer (\fIraster_output\fR)
and a site list file (\fIsites_output\fR), the user must
specify that at least one of these outputs be produced.
.SH NOTES
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
program \fIr.reclass\fR) that contains only the desired categories,
and then use the reclassed raster map layer as input to \fIr.random\fR.
.SH SEE ALSO
.I g.region,
.I r.mask,
.I r.reclass,
and
.I parser
.SH "AUTHOR"
Dr. James Hinthorne, GIS Laboratory, Central Washington University