NAME
r.random - Creates a raster map layer and vector point map containing randomly located sites.
KEYWORDS
raster
SYNOPSIS
r.random
r.random help
r.random [-zid] input=name [cover=name] n=number[%] [raster_output=name] [vector_output=name] [--overwrite] [--verbose] [--quiet]
Flags:
- -z
- Generate vector points for category zero also
- -i
- Report information about input raster and exit
- -d
- Generate vector points as 3D points
- --overwrite
- Allow output files to overwrite existing files
- --verbose
- Verbose module output
- --quiet
- Quiet module output
Parameters:
- input=name
- Name of input raster map
- cover=name
- Name of cover raster map
- n=number[%]
- The number of points to allocate
- raster_output=name
- Name for output raster map
- vector_output=name
- Name for output vector map
DESCRIPTION
The program r.random allows the user to create a
raster map layer and a vector points map 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 vector point 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. The values a stored in the value
column in the attached attribute table.
If a cover map is additionally specified, a second
column covervalue is populated with raster values from
the cover map.
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 raster map layer name
(input=name), optionally a cover raster map layer name
(cover=name), output raster map layer name
(raster_output=name), output vector points map
name (vector_output=name), and
the number of sites to be randomly generated as a
total number of sites (n=number) or as
a percentage of the map's size
(n=number%). The user can also
direct that r.random run quietly (using the
-q) option, and/or direct r.random to
also generate random vector point 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.
Flags:
- -z
- Include NULL cells in the pool
from which r.random will randomly generate vector point 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.
- -d
- Generate vector points with 3D geometry instead of 2D geometry.
The z values correspond to the raster map values.
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.
- cover=name
- An existing raster map layer in the user's current mapset search path.
r.random will extract raster values at the generates random sites
from this cover raster map. The cover map only generates output
for the vector_output map.
- n=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 vector points map (vector_output), the user must
specify that at least one of these outputs be produced.
NOTES
To create random vector point 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.
If a cover raster map is specified and the cover map
contains NULL (no data) values, these sites are suppressed in the
resulting vector_output map.
EXAMPLES
Random vector elevation points sampled from elevation map in the
Spearfish region, result stored in 2D vector map:
g.region rast=elevation.10m -p
r.random elevation.10m vector_output=elevrand n=100
v.db.select elevrand
v.univar elevrand col=value type=point
Random vector elevation points sampled from elevation map in the
Spearfish region with collocated values sampled from landuse map,
result stored in 3D vector map:
g.region rast=elevation.10m -p
r.random -d elevation.10m cover=landcover.30m vector_output=luserand3d n=100
# data output (value: elevation, covervalue: landuse class):
v.db.select luserand3d
cat|value|covervalue
1|1151.406616|81
2|1172.121216|71
3|1183.219604|71
...
BUGS
It's not possible to use the -i flag and not also specify the n
parameter.
SEE ALSO
g.region
r.reclass
v.random
AUTHOR
Dr. James Hinthorne,
GIS Laboratory,
Central Washington University
Modified for GRASS 5.0 by Eric G. Miller
Cover map support by Markus Neteler, 2007
Last changed: $Date: 2007-10-16 05:22:54 -0700 (Tue, 16 Oct 2007) $
Main index - raster index - Full index
© 2003-2008 GRASS Development Team