Geografic-Information-System/raster/r.random.cells/r.random.cells.html

<h2>DESCRIPTION</h2>

<em>r.random.cells</em> generates a random sets of raster cells that are
at least <b>distance</b> apart. The cells are numbered from 1 to the
numbers of cells generated, all other cells are NULL (no data). Random
cells will not be generated in areas masked off.

<h3>Detailed parameter description</h3>

<dl>
<dt><b>output</b></dt>
<dd>Random cells. Each random cell has a unique non-zero cell value
ranging from 1 to the number of cells generated. The heuristic for
this algorithm is to randomly pick cells until there are no cells
outside of the chosen cell's buffer of radius <b>distance</b>.</dd>

<dt><b>distance</b></dt>
<dd>Determines the minimum distance the centers of the random cells
will be apart.</dd>

<dt><b>seed</b></dt>
<dd>Specifies the random seed that
<em>r.random.cells</em> will use to generate the cells. If the random seed
is not given,<em> r.random.cells</em> will get a seed from the process ID
number.</dd>

</dl>

<h2>NOTES</h2>

The original purpose for this program was to generate independent
random samples of cells in a study area. The <b>distance</b> value is
the amount of spatial autocorrelation for the map being studied. 

<!-- The amount of spatial autocorrelation can be determined by
using <em>r.2Dcorrelogram</em> with
<em>r.2Dto1D</em>, or <em>r.1Dcorrelogram</em>. With <b>distance</b> set to
zero, the <b>output</b> map will number each non-masked cell from 1 to the
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>
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

<p>  As part of my dissertation, I put together several programs that help
GRASS (4.1 and beyond) develop uncertainty models of spatial data. I hope
you find it useful and dependable. The following papers might clarify their
use:

<ul>
<li> Ehlschlaeger, C.R., Shortridge, A.M., Goodchild, M.F., 1997. 
 Visualizing spatial data uncertainty using animation. 
 Computers &amp; Geosciences 23, 387-395. doi:10.1016/S0098-3004(97)00005-8</li>

<li><a href="http://www.geo.hunter.cuny.edu/~chuck/paper.html">Modeling
Uncertainty in Elevation Data for Geographical Analysis</a>, by
Charles R. Ehlschlaeger, and Ashton M.  Shortridge. Proceedings of the
7th International Symposium on Spatial Data Handling, Delft,
Netherlands, August 1996.</li>

<li><a href="http://www.geo.hunter.cuny.edu/~chuck/acm/paper.html">Dealing
with Uncertainty in Categorical Coverage Maps: Defining, Visualizing,
and Managing Data Errors</a>, by Charles Ehlschlaeger and Michael
Goodchild.  Proceedings, Workshop on Geographic Information Systems at
the Conference on Information and Knowledge Management, Gaithersburg
MD, 1994.</li>

<li><a href="http://www.geo.hunter.cuny.edu/~chuck/gislis/gislis.html">Uncertainty
in Spatial Data: Defining, Visualizing, and Managing Data
Errors</a>, by Charles Ehlschlaeger and Michael
Goodchild. Proceedings, GIS/LIS'94, pp. 246-253, Phoenix AZ,
1994.</li>
</ul>

<h2>SEE ALSO</h2>

<em>
<!--r.1Dcorrelogram, 
r.2Dcorrelogram, 
r.2Dto1D, -->
<a href="r.random.surface.html">r.random.surface</a>,
<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>

Charles Ehlschlaeger; National Center for Geographic Information and
Analysis, University of California, Santa Barbara.

<p><i>Last changed: $Date$</i>