<h2>DESCRIPTION</h2>

<em>v.random</em> randomly generates vector points within the
current region using the selected random number generator.

<p><em>v.random</em> can generate also 3D vector points or write
random value to the attribute table. Point height range or attribute value
range is controlled by specifying <b>zmin</b> and <b>zmax</b> options.
Both z values are included in range (<em>zmin &lt;= z &lt;=
zmax</em>). Generated random attribute value type can be controlled
by <b>column_type</b>. Use <i>integer</i> column type for integers and
<i>double precision</i> for floating point numbers. Integer values are
calculated by rounding random floating point number.

<p>To produce repeatable results a random seed can be set using the
option <b>seed</b>.

<h3>Restriction to vector areas</h3>

If an <b>restrict</b> vector map with areas is specified, the location
of random points is restricted to the selected areas. By default, the
requested number of points are distributed across all areas.

<p>
If the <b>-a</b> flag is given, the requested number of points is
generated for each individual area. For example, if 20 points should be
generated and the input map has 100 individual areas, 2000 points will
be generated in total.

<p>
Attributes attached to <b>restrict</b> vector map are also transferred
if the <b>layer</b> parameter is defined &gt; 0,
see <em><a href="#stratified-random-sampling:-random-sampling-from-vector-map-by-attribute">example</a></em>
below.

<h2>NOTES</h2>

Importantly, attributes will only be transferred if <b>layer</b> &gt; 0
(e.g., <code>layer=1</code>).

<h2>EXAMPLES</h2>

All examples are based on the North Carolina sample dataset.

<h3>Generating random points in 2D</h3>

Generate 20 random points with binary attributes (only 0 or 1):
<div class="code"><pre>
v.random output=binary_random npoints=20 zmin=0 zmax=1 column='binary'
v.db.select binary_random
cat|binary
1|0.63495
2|0.233421
3|0.489302
4|0.748264
5|0.505556
6|0.32975
[...]

v.univar -d binary_random
Calculating geometric distances between 20 primitives...
[...]
minimum: 148.515
maximum: 16572.8
[...]
</pre></div>

<h3>Generating random points in 2D with binary attributes</h3>

Generate 20 random points with binary attributes (only 0 or 1):
<div class="code"><pre>
v.random output=binary_random npoints=20 zmin=0 zmax=1 column='binary' column_type=integer
v.db.select binary_random
cat|binary
1|0
2|0
3|0
4|0
5|1
6|0
[...]
</pre></div>

<h3>Generating random points in 3D</h3>

Generate 20 random 3D points using a specific random seed:
<div class="code"><pre>
v.random seed=52 output=height_random npoints=40 zmin=110 zmax=170 -z
v.univar -d height_random
Calculating geometric distances between 40 primitives...
[...]
minimum: 334.889
maximum: 18351.9
range: 18017
sum: 5.38425e+06
mean: 7266.2
mean of absolute values: 7266.2
population standard deviation: 3563.95
[...]
skewness: 0.34703
</pre></div>

<!--
g.region raster=elev_lid792_1m
...
d.vect height_random color=60:60:60 icon=basic/point size=40 width=2 zcolor=gyr
optipng -o5 map.png
mv map.png vrandom_z.png
-->

<p>
<center>
<img src="vrandom_z.png" border="1"><br>
Random points with different X, Y, and Z coordinates
</center>

<h3>Generating random points in selected areas</h3>

Generate 3 random points only in selected areas ("RALEIGH" related ZIP
code areas):
<div class="code"><pre>
v.random restrict=zipcodes_wake output=zipcodes_local_random_n3 npoints=3 where="ZIPNAME = 'RALEIGH'" -a

# visualization
d.mon wx0
d.vect zipcodes_wake
d.vect zipcodes_wake fcolor=yellow where="ZIPNAME = 'RALEIGH'"
d.vect zipcodes_local_random_n3 color=red icon=basic/circle
</pre></div>

<div align="center" style="margin: 10px">
<a href="v_random_points_in_polygon.png">
<img src="v_random_points_in_polygon.png" width="400" height="368" alt="v.random example" border="0">
</a><br>
<i>Fixed number of random points generated in selected areas</i>
</div>

<h3>Generating random adjacent areas</h3>

To generate random adjacent areas, first the centroids are generated as
points, then a triangulation is run (North Carolina sample dataset:

<div class="code"><pre>
g.region vector=nc_state
v.random output=randpoints6k npoints=6000
v.voronoi input=randpoints6k output=randareas6k
v.info -t randareas6k
v.category randareas6k option=print

# plot vector areas
d.mon wx0
d.vect randareas6k -c
</pre></div>
<p>
<center>
<img src="vrandom_polygons.png" border="1"><br>
Random adjacent areas from random points (here: used as centroids)
</center>

<p>
To eventually obtain isolated areas, selected areas can be extracted with
<em><a href="v.extract.html">v.extract</a></em>.
<p>

These vector areas can also be rasterized:
<div class="code"><pre>
# rasterize areas
# note: rastermaps must result in at least 6k pixel in this example
g.region vector=nc_state res=500 -p -a
v.to.rast randareas6k out=randareas6k use=cat
r.colors randareas6k color=random
d.rast randareas6k
</pre></div>

<h3>Random sampling from raster map</h3>

Generate 20 random samples from a raster map:
<div class="code"><pre>
g.region -p raster=elevation
v.random output=random_samples npoints=20
v.db.addtable map=random_samples columns='cat INTEGER, sample DOUBLE PRECISION'
v.what.rast map=random_samples raster=elevation column=sample
v.db.select random_samples
cat|sample
1|103.9935
2|129.1266
3|96.01388
[...]
</pre></div>

<h3>Random sampling from vector map</h3>

Generate 20 random points and sample attribute data from geology (vector) map:
<div class="code"><pre>
g.region -p vector=geology
v.random output=random_samples npoints=20
v.db.addtable map=random_samples columns='cat integer, geology varchar(100)'
v.what.vect map=random_samples column=geology query_map=geology query_layer=1 query_column=GEO_NAME
v.db.select random_samples
cat|geology
1|PzZm
2|
3|Zatm
[...]
</pre></div>

<h3>Stratified random sampling: Random sampling from vector map by attribute</h3>

Generate 20 random points restricted to forested areas:
<div class="code"><pre>
g.region -p raster=landclass96
r.to.vect -v input=landclass96 output=landclass96 type=area
v.random restrict=landclass96 output=random_samples npoints=20 where="label = 'forest'" layer=1
v.db.select map=random_samples
cat|landclass96_cat|landclass96_label
1|5|forest
2|5|forest
3|5|forest
...
</pre></div>

<!--
d.font Vera
d.rast landclass96
d.vect random_samples icon=basic/triangle color=blue fcolor=black size=14
d.vect random_samples color=white
-->
<p>
<center>
<img src="vrandom_restricted_attr.png" border="1"><br>
Random points only sampled in forested areas (stratified random sampling)
</center>

<h3>Stratified random sampling: Random sampling from vector map with spatial constraints</h3>

Generating n points for each individual area: in this example two random
points in each water body:

<div class="code"><pre>
g.region -p raster=landclass96
r.to.vect -v input=landclass96 output=landclass96 type=area
v.random restrict=landclass96 output=random_samples npoints=2 where="label = 'water'" layer=1 -a
</pre></div>

<!--
d.font Vera
d.rast landclass96
d.vect random_samples icon=basic/triangle color=blue fcolor=black size=14
d.vect random_samples color=white
-->
<p>
<center>
<img src="vrandom_restricted_area.png" border="1"><br>
Two random points sampled in each individual water body (stratified
random sampling)
</center>

<h2>SEE ALSO</h2>

<em>
<a href="g.region.html">g.region</a>,
<a href="r.random.html">r.random</a>,
<a href="v.db.addtable.html">v.db.addtable</a>,
<a href="v.perturb.html">v.perturb</a>,
<a href="v.sample.html">v.sample</a>,
<a href="v.univar.html">v.univar</a>,
<a href="v.what.rast.html">v.what.rast</a>,
<a href="v.what.vect.html">v.what.vect</a>
</em>
<p>
<a href="sql.html">SQL support in GRASS GIS</a>

<h2>AUTHOR</h2>

<a href="http://mccauley-usa.com/">James Darrell McCauley</a>
<a href="mailto:darrell@mccauley-usa.com">&lt;darrell@mccauley-usa.com&gt;</a>,
<br>when he was at:
<a href="http://ABE.www.ecn.purdue.edu/ABE/">Agricultural Engineering</a>
<a href="http://www.purdue.edu/">Purdue University</a>