\HeaderA{spsample}{sample point locations within a spatial region}{spsample}
\aliasA{makegrid}{spsample}{makegrid}
\aliasA{sample.Line}{spsample}{sample.Line}
\aliasA{sample.Polygon}{spsample}{sample.Polygon}
\aliasA{sample.Polygons}{spsample}{sample.Polygons}
\aliasA{sample.Sgrid}{spsample}{sample.Sgrid}
\aliasA{sample.Spatial}{spsample}{sample.Spatial}
\keyword{manip}{spsample}
\begin{Description}\relax
sample point locations within a square area,
a ring, or on a spatial line, using regular or random sampling
\end{Description}
\begin{Usage}
\begin{verbatim}
spsample(x, n, type, ...)
sample.Spatial(x, n, type, bb = bbox(x), offset = runif(2), cellsize, ...)
sample.Line(x, n, type, offset = runif(1), proj4string=CRS(as.character(NA)), ...)
sample.Polygon(x, n, type = "random", bb = bbox(x), offset = runif(2), proj4string=CRS(as.character(NA)), ...)
sample.Polygons(x, n, type = "random", bb = bbox(x), offset = runif(2), proj4string=CRS(as.character(NA)), ...)
sample.Sgrid(x, n, type = "random", bb = bbox(x), offset = runif(2), ...)
makegrid(x, n = 10000, nsig = 2, cellsize, offset = c(0.5,0.5), 
        type = "regular", ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] Spatial object; \code{spsample(x,...)} is a generic method for the
existing \code{sample.Xxx} fumctions
\item[\code{...}] optional arguments, passed to the appropriate \code{sample.Xxx}
functions
\item[\code{n}] (approximate) sample size 
\item[\code{type}] character; \code{"random"} for completely spatial random;
\code{"regular"} for regular (systematically aligned) sampling;
\code{"stratified"} for stratified random (one single random location in
each "cell"); or \code{"nonaligned"} for nonaligned systematic sampling
(nx random y coordinates, ny random x coordinates) 
\item[\code{bb}] bounding box of the sampled domain; setting this to a smaller
value leads to sub-region sampling 
\item[\code{offset}] for regular sampling only: the offset (position) of the regular
grid; the default for \code{spsample} methods is a random location in
the unit cell $[0,1] \times [0,1]$, leading to a different grid after
each call; if this is set to \code{c(0.5,0.5)}, the returned grid is
not random (but, in Ripley's wording, "centric systematic") 
\item[\code{cellsize}] if missing, a cell size is derived from the sample size
\code{n}; otherwise, this cell size is used for all sampling methods
except \code{"random"} 
\item[\code{proj4string}] Object of class \code{"CRS"};
holding a valid proj4 string
\item[\code{nsig}] for "pretty" coordinates; \code{spsample} do not result in
pretty grids 
\end{ldescription}
\end{Arguments}
\begin{Value}
an object of class \LinkA{SpatialPoints-class}{SpatialPoints.Rdash.class}. The number of
points is only guaranteed to equal \code{n} when sampling is done in a
square box, i.e. (\code{sample.Spatial}). Otherwise, the obtained number
of points will have expected value \code{n}. 

When \code{x} is of a class deriving from \LinkA{Spatial-class}{Spatial.Rdash.class} for which
no \LinkA{spsample-methods}{spsample.Rdash.methods} exists, sampling is done in the bounding box
of the object, using \code{spsample.Spatial}. An \LinkA{overlay}{overlay} may be
necessary to select afterwards. 

Sampling type \code{"nonaligned"} is not implemented for line objects.
\end{Value}
\begin{Note}\relax
If an \LinkA{Polygon-class}{Polygon.Rdash.class} object has zero area (i.e. is a line),
samples on this line element are returned. If the area is very close
to zero, the algorithm taken here (generating points in a square area,
selecting those inside the polygon) may be very resource intensive
\end{Note}
\begin{Author}\relax
Edzer J. Pebesma, \email{e.pebesma@geo.uu.nl}
\end{Author}
\begin{References}\relax
Chapter 3 in B.D. Ripley, 1981. Spatial Statistics, Wiley
\end{References}
\begin{SeeAlso}\relax
\LinkA{overlay-methods}{overlay.Rdash.methods}, \LinkA{point.in.polygon}{point.in.polygon}, \LinkA{sample}{sample}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

data(meuse.riv)
meuse.sr = SpatialPolygons(list(Polygons(list(Polygon(meuse.riv)), "x")))

plot(meuse.sr)
points(spsample(meuse.sr, n = 1000, "regular"), pch = 3)

plot(meuse.sr)
points(spsample(meuse.sr, n = 1000, "random"), pch = 3)

plot(meuse.sr)
points(spsample(meuse.sr, n = 1000, "stratified"), pch = 3)

plot(meuse.sr)
points(spsample(meuse.sr, n = 1000, "nonaligned"), pch = 3)

plot(meuse.sr)
points(spsample(meuse.sr@polygons[[1]], n = 100, "stratified"), pch = 3, cex=.5)

data(meuse.grid)
gridded(meuse.grid) = ~x+y
image(meuse.grid)
points(spsample(meuse.grid,n=1000,type="random"), pch=3, cex=.5)
image(meuse.grid)
points(spsample(meuse.grid,n=1000,type="stratified"), pch=3, cex=.5)
image(meuse.grid)
points(spsample(meuse.grid,n=1000,type="regular"), pch=3, cex=.5)
image(meuse.grid)
points(spsample(meuse.grid,n=1000,type="nonaligned"), pch=3, cex=.5)

fullgrid(meuse.grid) = TRUE
image(meuse.grid)
points(spsample(meuse.grid,n=1000,type="stratified"), pch=3,cex=.5)

\end{ExampleCode}
\end{Examples}

