.TH r.random 1grass "" "GRASS 8.3.1" "GRASS GIS User's Manual"
.SH NAME
\fI\fBr.random\fR\fR  \- Creates randomly placed raster cells or vector points
.br
Creates a raster map and vector point map containing randomly located cells and points.
.SH KEYWORDS
raster, sampling, vector, random, level1
.SH SYNOPSIS
\fBr.random\fR
.br
\fBr.random \-\-help\fR
.br
\fBr.random\fR [\-\fBsnzb\fR] \fBinput\fR=\fIname\fR  [\fBcover\fR=\fIname\fR]  \fBnpoints\fR=\fInumber[%]\fR  [\fBraster\fR=\fIname\fR]   [\fBvector\fR=\fIname\fR]   [\fBseed\fR=\fIinteger\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-s\fR" 4m
.br
Generate random seed (result is non\-deterministic)
.IP "\fB\-n\fR" 4m
.br
Generate points also for NULL cells
.IP "\fB\-z\fR" 4m
.br
Generate vector points as 3D points
.br
Input raster values will be used for Z coordinates
.IP "\fB\-b\fR" 4m
.br
Do not build topology
.br
Do not build topology for vector points
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBinput\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of input raster map
.IP "\fBcover\fR=\fIname\fR" 4m
.br
Name of cover raster map
.IP "\fBnpoints\fR=\fInumber[%]\fR \fB[required]\fR" 4m
.br
The number of points (or cells) to generate
.br
The number of vector points or raster cells to generate, possibly as a percentage of number of cells
.IP "\fBraster\fR=\fIname\fR" 4m
.br
Name for output raster map
.IP "\fBvector\fR=\fIname\fR" 4m
.br
Name for output vector map
.IP "\fBseed\fR=\fIinteger\fR" 4m
.br
Seed for rand() function
.SH DESCRIPTION
.PP
The module \fIr.random\fR creates a raster map with values in random places.
Alternatively, it creates random vector points at these places.
Number of random cells or points can be a fixed number or a percentage of cells
from the input.
By default, generated cells or points will be subset of non\-NULL cells of the input.
Resulting raster map consists of original cell values at the selected
random locations and NULL (no data) values elsewhere.
.SS Placement of cells and points
.PP
The module allows the user to create a
raster map and/or a vector points map containing
coordinates of points whose locations have been randomly
determined. The module places these randomly generated
vector points within the current computational region and raster mask (if
any), on non\-NULL raster cells in a
user\-specified raster map. If the user sets the
\fB\-n\fR flag, points will be randomly generated across all
cells (even those with NULL values).
Cells in the resulting raster overlap with the cells of the input raster
based on the current computational region.
Points in the resulting vector map are placed in cell centers of these cells.
.SS Number of cells and points
.PP
The user may specify the quantity of random locations to be
generated either as a \fIpositive integer\fR (e.g., 10),
or as a \fIpercentage of the raster map\(cqs cells\fR
(e.g., 10%, or 3.05%).  The number of cells considered for
the percentage reflects whether or not the \fB\-n\fR flag
was given. Options are 0\-100; fractions of percent may be
stated as decimals (e.g., 66.67%, or 0.05%).
.SS Values
.PP
The cell values and
corresponding category names (if present) associated with the
random point locations in the \fIinput\fR map are
assigned to the newly generated cells in the \fIraster\fR map.
If the \fB\-n\fR is specified, then a unique entry
is made for the value used where the \fIinput\fR was NULL.
This value is at least 1 less than the smallest value in the
\fIinput\fR raster and is given a medium gray color.
.PP
If a \fIcover\fR raster map is specified, values are taken
from the \fIcover\fR raster map instead of the \fIinput\fR raster map.
If a \fIcover\fR raster map is specified and the \fIcover\fR map
contains NULL (no data) values, these points are suppressed in the
resulting \fIvector\fR or \fIraster\fR map.
.SS Vector output
.PP
The \fIvector\fR file created by \fIr.random\fR
contains vector points that represent the \fIcenter points\fR of the
randomly generated cells.  A \fIvalue\fR attribute contains the cell value
of the \fIinput\fR raster (or the assigned value
when \fB\-n\fR is used).
If a \fIcover\fR map is additionally specified, a second
column  \fIcovervalue\fR is populated with raster values from
the \fIcover\fR map.
.PP
If the user sets the \fB\-b\fR flag, vector points are written without
topology to minimize the required resources. This is suitable input
to \fIv.surf.rst\fR and other vector modules.
.SH NOTES
To decide on the number
of points \fIr.random\fR will create,
use \fIr.univar\fR,
\fIg.region\fR, or
\fIr.report\fR.
\fIr.univar\fR is the fastest way to obtain number of
non\-NULL cells and NULL cells in a raster map
given the current computational region and raster mask:
.br
.nf
\fC
r.univar map=inputmap
\fR
.fi
The text output contains total number of null and non\-null cells
(called \fCcells\fR in the machine\-readable shell script style output),
total null cells (\fCnull_cells\fR),
and number of non\-null cells (\fCn\fR).
Alternatively, you can use the following to examine the computational
region and the raster map:
.br
.nf
\fC
g.region \-p
r.report map=inputmap units=c null=\(dq*\(dq nsteps=1
\fR
.fi
.PP
To create random vector point locations within some, but not all,
categories of a integer input raster map (aka CELL raster map),
the user must first create a reclassified raster map
of the original raster map (e.g., using the GRASS
module \fIr.reclass\fR)
that contains only the desired categories,
and then use the reclassed raster map as input to \fIr.random\fR.
.SH EXAMPLES
.SS Random 2D vector elevation points
Random vector elevation points sampled from elevation map in the
North Carolina sample dataset region, result stored in 2D vector map:
.br
.nf
\fC
g.region raster=elevation \-p
r.random elevation vector=elevrand n=100
v.db.select elevrand
v.univar elevrand col=value type=point
\fR
.fi
.SS Random 3D vector elevation points
Random vector elevation points sampled from elevation map in the
North Carolina sample dataset region with collocated values sampled from
landuse map, result stored in 3D vector map:
.br
.nf
\fC
g.region raster=elevation \-p
r.random \-z elevation cover=landclass96 vector=luserand3d n=100
# data output (value: elevation, covervalue: landuse class):
v.db.select luserand3d
cat|value|covervalue
1|111.229591|5
2|71.093758|1
3|122.51075|5
4|146.17395|4
\&...
\fR
.fi
.SH SEE ALSO
.RS 4n
.IP \(bu 4n
\fIg.region\fR
for setting the computational region and examining the total number of cells,
.IP \(bu 4n
\fIr.reclass\fR
for working only with subset of values in the raster map,
.IP \(bu 4n
\fIv.random\fR
for generating vector points without any involvement of raster data,
.IP \(bu 4n
\fIr.random.cells\fR
for generating random cells with with spatial dependence (minimal distance),
.IP \(bu 4n
\fIr.surf.random\fR
as an option for generating random cell values,
.IP \(bu 4n
\fIv.surf.rst\fR
as an option for creating a surface from sampled points.
.RE
.SH AUTHORS
Dr. James Hinthorne,
GIS Laboratory,
Central Washington University
.PP
Modified for GRASS 5.0 by Eric G. Miller
.PP
Cover map support by Markus Neteler, 2007
.SH SOURCE CODE
.PP
Available at:
r.random source code
(history)
.PP
Accessed: Sunday Dec 17 17:21:56 2023
.PP
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2023
GRASS Development Team,
GRASS GIS 8.3.1 Reference Manual