v.random manual: major cleanup; screenshots added

git-svn-id: https://svn.osgeo.org/grass/grass/branches/releasebranch_7_0@68779 15284696-431f-4ddb-bdfa-cd5b030d7da7

vector/v.random/main.c

@@ -98,6 +98,7 @@ int main(int argc, char *argv[])
     G_add_keyword(_("statistics"));
     G_add_keyword(_("random"));
     G_add_keyword(_("point pattern"));
+    G_add_keyword(_("stratified random sampling"));
     module->description = _("Generates random 2D/3D vector points.");
 
     parm.output = G_define_standard_option(G_OPT_V_OUTPUT);

vector/v.random/v.random.html

@@ -28,24 +28,66 @@ generated and the input map has 100 individual areas, 2000 points will
 be generated in total.
 
 <h2>EXAMPLES</h2>
-All examples use the North Carolina sample dataset.
-<p>
-Generate 20 random points with binary attribute (only 0 or 1):
+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 INTEGER'
+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>
 
-<p>
-<center>
-<img src="vrandom_z.png"><br>
-Random points with different X, Y, and Z coordinates
-</center>
-
 <!--
 g.region rast=elev_lid792_1m
 ...
@@ -54,50 +96,108 @@ optipng -o5 map.png
 mv map.png vrandom_z.png
 -->
 
-Get 20 random samples from raster map:
+<p>
+<center>
+<img src="vrandom_z.png" border=1><br>
+Random points with different X, Y, and Z coordinates
+</center>
+
+<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 layer=1 columns='cat INTEGER, sample DOUBLE PRECISION'
-v.what.rast vector=random_samples raster=elevation@PERMANENT layer=1 column=sample 
+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 layer=1 columns='cat integer, geology varchar(100)'
-v.what.vect vector=random_samples layer=1 column=geology \
-  qvector=geology@PERMANENT qlayer=1 qcolumn=label 
+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>
 
-Generate 20 random points in forested areas
+<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 input=landclass96 output=random_samples npoints=20 \
-  where="label = 'forest'"
+v.random restrict=landclass96 output=random_samples npoints=20 \
+  where="label = 'forest'" layer=1
 </pre></div>
 
-Generate 20 random points in each forest patch
+<!--
+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 contraints</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 input=landclass96 output=random_samples npoints=20 \
-  where="label = 'forest'" -a
+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>