r.random.cells: generate only limited number of cells [news]

Also improve documentation with a picture and example of creating vector points.

Add test for old and new functionality.


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@66467 15284696-431f-4ddb-bdfa-cd5b030d7da7

raster/r.random.cells/indep.c

@@ -21,6 +21,11 @@ void Indep(void)
 	G_debug(3, "(CellCount):%d", CellCount);
 	G_debug(3, "(Count):%d", Count);
 
+        if (Found >= MaxCellsNum) {
+            G_debug(1, "Hit maximum number of cells");
+            break;
+        }
+
 	DRow = DoNext[Count].R;
 	DCol = DoNext[Count++].C;
 

raster/r.random.cells/init.c

@@ -65,6 +65,13 @@ void Init()
 	CellCount = Rs * Cs;
     }
 
+    /* cut down num of cells if requested */
+    if (MaxCells->answer)
+        sscanf(MaxCells->answer, "%d", &MaxCellsNum);
+    else
+        MaxCellsNum = CellCount;
+    G_debug(1, "(CellCount):%d", CellCount);
+
     sscanf(Distance->answer, "%lf", &MaxDist);
     if (MaxDist < 0.0)
 	G_fatal_error(_("Distance must be >= 0.0"));

raster/r.random.cells/main.c

@@ -30,10 +30,12 @@ FLAG *Cells;
 CELLSORTER *DoNext;
 CELL **Out, *CellBuffer;
 int Seed, OutFD;
+int MaxCellsNum;
 struct Flag *Verbose;
 struct Option *Distance;
 struct Option *Output;
 struct Option *SeedStuff;
+struct Option *MaxCells;
 
 int main(int argc, char *argv[])
 {
@@ -59,6 +61,14 @@ int main(int argc, char *argv[])
     Distance->description =
 	_("Maximum distance of spatial correlation (value >= 0.0)");
 
+    MaxCells = G_define_option();
+    MaxCells->key = "ncells";
+    MaxCells->type = TYPE_INTEGER;
+    MaxCells->required = NO;
+    MaxCells->options = "1-";
+    MaxCells->description =
+        _("Maximum number of cells to be created");
+
     SeedStuff = G_define_option();
     SeedStuff->key = "seed";
     SeedStuff->type = TYPE_INTEGER;

raster/r.random.cells/r.random.cells.html

@@ -40,6 +40,8 @@ number of non-masked cells in the study region. -->
 
 <h2>EXAMPLE</h2>
 
+<h3>Random cells in given distances</h3>
+
 North Carolina sample dataset example:
 
 <div class="code"><pre>
@@ -47,6 +49,76 @@ g.region n=228500 s=215000 w=630000 e=645000 res=100 -p
 r.random.cells output=random_500m distance=500
 </pre></div>
 
+<h3>Limited number of random points</h3>
+
+Here is another example where we will create given number of vector points
+with the given minimal distances.
+Let's star with setting the region (we use large cells here):
+
+<div class="code"><pre>
+g.region raster=elevation
+g.region rows=20 cols=20 -p
+</pre></div>
+
+Then we generate random cells and we limit their count to 20:
+
+<div class="code"><pre>
+r.random.cells output=random_cells distance=1500 ncells=20 seed=200
+</pre></div>
+
+Finally, we convert the raster cells to points using
+<em><a href="r.to.vect.html">r.to.vect</a></em> module:
+
+<div class="code"><pre>
+r.to.vect input=random_cells output=random_points type=point
+</pre></div>
+
+An example of the result is at the Figure below on the left
+in comparison with the result without the cell limit on the right.
+
+<p>
+Additionally, we can use <em><a href="v.perturb.html">v.perturb</a></em> module
+to add random spatial deviation to their position so that they are not
+perfectly aligned with the grid. We cannot perturb the points too much,
+otherwise we might seriously break the minimal distance we set earlier.
+
+<div class="code"><pre>
+v.perturb input=random_points output=random_points_moved parameters=50 seed=200
+</pre></div>
+
+In the above examples, we were using fixed seed. This is advantageous when
+we want to generate (pseudo) random data, but we want to get reproducible
+results at the same time.
+
+<center>
+<img src="r_random_cells.png" alt="Cells and points filling the space">
+<p><em>
+    Figure: Generated cells with limited number of cells (upper left),
+    derived vector points (lower left), cells without a count limit
+    (upper right) and corresponding vector points (lower right)
+</em></p>
+</center>
+
+<!--
+r.random.cells output=random_cells_all distance=1500 seed=200
+r.random.cells output=random_cells distance=1500 ncells=20 seed=200
+r.to.vect input=random_cells_all output=random_points_all type=point
+r.to.vect input=random_cells output=random_points type=point
+
+d.mon cairo out=r_random_cells.png
+d.frame frame=a at=50,100,0,50 -c
+d.rast random_cells
+d.frame frame=b at=50,100,50,100 -c
+d.rast random_cells_all
+d.frame frame=c at=0,50,0,50 -c
+d.vect random_points color=0:53:106 fill_color=30:144:255 width=1 icon=basic/point size=20
+d.frame frame=d at=0,50,50,100 -c
+d.vect random_points_all color=0:53:106 fill_color=30:144:255 width=1 icon=basic/point size=20
+d.mon stop=cairo
+mogrify -trim r_random_cells.png
+-->
+
+
 <h2>REFERENCES</h2>
 Random Field Software for GRASS GIS by Chuck Ehlschlaeger
 
@@ -87,8 +159,12 @@ Goodchild. Proceedings, GIS/LIS'94, pp. 246-253, Phoenix AZ,
 r.2Dcorrelogram, 
 r.2Dto1D, -->
 <a href="r.random.surface.html">r.random.surface</a>,
-<a href="r.random.html">r.random</a>
-</em> 
+<a href="r.random.html">r.random</a>,
+<a href="v.random.html">v.random</a>,
+<a href="r.to.vect.html">r.to.vect</a>,
+<a href="v.perturb.html">v.perturb</a>
+</em>
+
 
 <h2>AUTHOR</h2>
 

raster/r.random.cells/ransurf.h

@@ -24,7 +24,9 @@ extern FLAG *Cells;
 extern CELLSORTER *DoNext;
 extern CELL **Out, *CellBuffer;
 extern int Seed, OutFD;
+extern int MaxCellsNum;
 extern struct Flag *Verbose;
 extern struct Option *Distance;
 extern struct Option *Output;
 extern struct Option *SeedStuff;
+extern struct Option *MaxCells;

raster/r.random.cells/testsuite/test_random_cells.py

@@ -0,0 +1,77 @@
+"""
+TEST:      r.random.cells
+
+AUTHOR(S): Vaclav Petras
+
+PURPOSE:   Test r.random.cells
+
+COPYRIGHT: (C) 2015 Vaclav Petras, and by the GRASS Development Team
+
+           This program is free software under the GNU General Public
+           License (>=v2). Read the file COPYING that comes with GRASS
+           for details.
+"""
+
+
+from grass.gunittest.case import TestCase
+from grass.gunittest.main import test
+
+
+
+class TestCounts(TestCase):
+
+    # TODO: replace by unified handing of maps
+    to_remove = []
+    all_rast = "r_random_cells_all"
+    some_rast = "r_random_cells_some"
+    count_rast = "r_random_cells_count"
+    n_cells = 50
+
+    @classmethod
+    def setUpClass(cls):
+        cls.use_temp_region()
+        # (20-10) / 2 * (60-40) / 2 = 50 cells
+        cls.runModule('g.region', n=20, s=10, e=60, w=40, res=2)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.del_temp_region()
+        if cls.to_remove:
+            cls.runModule('g.remove', flags='f', type='raster',
+                          name=','.join(cls.to_remove), verbose=True)
+
+    def test_fill_all(self):
+        self.assertModule('r.random.cells', output=self.all_rast,
+                          distance=0.01, seed=100)
+        self.to_remove.append(self.all_rast)
+        self.assertRasterFitsUnivar(
+            self.all_rast,
+            reference=dict(cells=self.n_cells, n=self.n_cells, null_cells=0,
+                           min=1, max=self.n_cells))
+
+    def test_fill_some(self):
+        self.assertModule('r.random.cells', output=self.some_rast,
+                          distance=2, seed=100)
+        self.to_remove.append(self.some_rast)
+        self.assertRasterFitsUnivar(
+            self.some_rast,
+            reference=dict(cells=self.n_cells, min=1))
+        # it is hard to say how much but it will be less than half
+        self.assertRasterMinMax(self.some_rast, 1, self.n_cells / 2)
+
+    def test_fill_count(self):
+        count = 12
+        self.assertModule('r.random.cells', output=self.count_rast,
+                          distance=2, seed=100, ncells=count)
+        self.to_remove.append(self.count_rast)
+        self.assertRasterFitsUnivar(
+            self.count_rast,
+            reference=dict(cells=self.n_cells, n=count,
+                           null_cells=self.n_cells - count,
+                           min=1, max=count))
+        # it is hard to say how much but it will be less than half
+        self.assertRasterMinMax(self.count_rast, 1, count)
+
+
+if __name__ == '__main__':
+    test()