man r.random () - Creates a raster map layer and vector point map containing randomly located sites.

NAME

r.random - Creates a raster map layer and vector point map containing randomly located sites.

SYNOPSIS

r.random

r.random help

r.random [-qzi] input=string n=number[%] [raster_output=string] [vector_output=string]

Flags:

"-q
Run quietly
"-z
Generate sites for category zero also
"-i
Report information about input raster and exit

Parameters:

"input=string
Name of existing raster map
"n=number[%]
The number of points to allocate
"raster_output=string
Name of the output raster map
"vector_output=string
Name of the output vector points map

DESCRIPTION

The program r.random 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 (vector points) 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 with NULL values).

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. If the -z is specified, then a unique entry is made for the value used where the input was NULL. This value is at least 1 less than the smallest value in the input raster and is given a medium gray color.

The vector_output file created by r.random contains a listing of the sites' coordinates; these coordinates are the center points of the randomly selected cells. A double attribute contains the cell value of the input raster (or the assigned value when -z is used.

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 cells (e.g., 10%, or 3.05%). The number of cells considered for the percentage reflects whether or not the -z flag was given. Options are 0-100; percentages less than one percent may be stated as decimals.

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 (vector_output=name), and 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 NULL values (using the -z option). The -i 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 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 NULL cells in the pool from which r.random will randomly generate site locations.
"-i
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 without doing anything. Useful for deciding on the number of sites to have r.random create.

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
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 vector_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 NULL cells in the input value will be assigned the category values assigned these cells in the input layer; sites falling on NULL cells in the input layer will be assigned to a newly created category in the raster_output layer with at least one integer value less than the minimum value in the input layer.
"vector_output=name
The new GRASS vector_output file to hold program output. If no vector_output file name is given on the command line, no vector_output 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 (vector_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.

BUGS

It's not possible to use the -i flag and not also specify the nsites parameter.

SEE ALSO

g.region

r.mask

r.reclass

v.random

AUTHOR

Dr. James Hinthorne, GIS Laboratory, Central Washington University

Modified for GRASS 5.0 by Eric G. Miller

Last changed: $Date: 2003/10/29 16:11:23 $

Help Index