NAME

r.random - Creates a raster map layer and site list file containing randomly located sites.
(GRASS Raster Program)

SYNOPSIS

r.random
r.random help
r.random [-qz] input=name nsites=number[%] [raster_output=name] [sites_output=name]

DESCRIPTION

The program r.random 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 raster_output 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 input map layer are assigned to these sites in the raster_output map layer.

The site_lists file created by r.random contains a listing of the sites' geographic coordinates; these coordinates are the center points of the randomly selected cells.

OPTIONS

The user may specify the quantity of random locations to be generated either as a positive integer (e.g., 10), or as a percentage of the raster map layer's total area (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.)

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

Alternately, the user can simply type r.random 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 parser interface.

Flags:

-q
Run quietly. r.random will normally print output messages to standard output as it runs. The -q option will suppress the printing of these messages.
-z
Include areas assigned a category value of zero within the pool of areas within which r.random will randomly generate site locations. If the -z flag 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.

Parameters:

input=name
An existing raster map layer in the user's current mapset search path. r.random will randomly generate sites on a user-specified portion of the cells in this input raster map.
nsites=number
Allows the user to specify the quantity of sites to be randomly generated as either a positive integer, or as a percentage value of the number of cells in the input map layer. If stated as a positive integer, number is the number of sites (i.e., number of cells) to appear in the raster_output layer and/or sites_output 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).
raster_output=name
The new raster map layer to hold program output. This map will contain the sites randomly generated by r.random. If the -z flag is not set, all sites will be assigned whatever category values were assigned these cell locations in the input raster map layer. If the -z flag is set, all sites except those falling on cells assigned category value 0 in the input value will be assigned the category values assigned these cells in the input layer; sites falling on cells assigned category value 0 in the input layer will be assigned to a newly created category in the raster_output layer.
sites_output=name
The new GRASS site_lists file to hold program output. If no sites_output file name is given on the command line, no site_lists file will be created by r.random. (See raster_output parameter description, above.) Note. Although the user need not request that r.random output both a raster map layer (raster_output) and a site list file (sites_output), the user must specify that at least one of these outputs be produced.

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 r.reclass) that contains only the desired categories, and then use the reclassed raster map layer as input to r.random.

SEE ALSO

g.region
r.mask
r.reclass
parser

AUTHOR

Dr. James Hinthorne, GIS Laboratory, Central Washington University