GRASS logo

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