Generates a random point pattern of \(n\) iid points with any specified distribution based on a pixel image and a corresponding polygonal window.

rimpoly(n, z, w = NULL, correction = 1.1, maxpass = 50)

Arguments

n

Number of points to generate.

z

A pixel image of class im defining the probability density of the points, possibly unnormalised.

w

A polygonal window of class owin. See `Details'.

correction

An adjustment to the number of points generated at the initial pass of the internal loop in an effort to minimise the total number of passes required to reach \(n\) points. See `Details'.

maxpass

The maximum number of passes allowed before the function exits. If this is reached before \(n\) points are found that fall within w, a warning is issued.

Value

An object of class ppp containing the n generated points, defined with the polygonal owin, w.

Details

This function is a deliberate variant of rpoint (Baddeley et. al, 2015), to be accessed when the user desires a randomly generated point pattern based on a pixel image, but wants the window of the point pattern to be a corresponding irregular polygon, as opposed to a binary image mask (which, when converted to a polygon directly, gives jagged edges based on the union of the pixels). When the user specifies their own polygonal window, a while loop is called and repeated as many times as necessary (up to maxpass times) to find n points inside w (when w = NULL, then the aforementioned union of the pixels of z is used, obtained via as.polygonal(Window(z))). The loop is necessary because the standard behaviour of rpoint can (and often does) yield points that sit in corners of pixels which lie outside the corresponding w.

The correction argument is used to determine how many points are generated initially, which will be ceiling(correction*n); to minimise the number of required passes over the loop this is by default set to give a number slightly higher than the requested n.

An error is thrown if Window(z) and w do not overlap.

References

Baddeley, A., Rubak, E. and Turner, R. (2015) Spatial Point Patterns: Methodology and Applications with R, Chapman and Hall/CRC Press, UK.

Author

T.M. Davies

Examples


data(pbc)
Y <- bivariate.density(pbc,h0=2.5,res=25)

# Direct use of 'rpoint':
A <- rpoint(500,Y$z)
npoints(A)
#> [1] 500

# Using 'rimpoly' without supplying polygon:
B <- rimpoly(500,Y$z)
npoints(B)
#> [1] 500

# Using 'rimpoly' with the original pbc polygonal window:
C <- rimpoly(500,Y$z,Window(Y$pp))
npoints(C)
#> [1] 500

par(mfrow=c(1,3))
plot(A,main="rpoint")
plot(B,main="rimpoly (no polygon supplied)")
plot(C,main="rimpoly (original polygon supplied)")