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
[-iqz]
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
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 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 site_lists 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 (sites_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 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 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.
- 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.
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
s.random
parser
AUTHOR
Dr. James Hinthorne,
GIS Laboratory,
Central Washington University
Modified for GRASS 5.0 by Eric G. Miller