spatstat.random (version 3.4-2)

rpoint: Generate N Random Points

Description

Generate a random point pattern containing \(n\) independent, identically distributed random points with any specified distribution.

Usage

rpoint(n, f, fmax=NULL, win=unit.square(),
        ..., giveup=1000, fail.action=c("error", "pass", "missing"),
        warn=TRUE, verbose=FALSE,
        nsim=1, drop=TRUE, forcewin=FALSE)

Value

A point pattern (an object of class "ppp") if nsim=1, or a list of point patterns if nsim > 1.

Arguments

n

Number of points to generate.

f

The probability density of the points, possibly un-normalised. Either a constant, a function f(x,y,...), or a pixel image object.

fmax

An upper bound on the values of f. If missing, this number will be estimated.

win

Window in which to simulate the pattern. (Ignored if f is a pixel image, unless forcewin=TRUE).

...

Arguments passed to the function f.

giveup

Number of attempts in the rejection method after which the algorithm should stop trying to generate new points.

fail.action

Character string (partially matched) specifying what to do if the number of attempts exceeds giveup. If fail.action="error" (the default), a fatal error will be generated. If fail.action="pass", the pattern of accepted points (containing fewer than n points) will be returned. If fail.action="missing", the result will be a ‘missing point pattern’, an object belonging to the classes "NAobject" and "ppp".

warn

Logical value specifying whether to issue a warning if n is very large. See Details.

verbose

Flag indicating whether to report details of performance of the simulation algorithm.

nsim

Number of simulated realisations to be generated.

drop

Logical. If nsim=1 and drop=TRUE (the default), the result will be a point pattern, rather than a list containing a point pattern.

forcewin

Logical. If TRUE, then simulations will be generated inside win in all cases. If FALSE (the default), the argument win is ignored when f is a pixel image.

Author

Adrian Baddeley , Rolf Turner and Ege Rubak .

Details

This function generates n independent, identically distributed random points with common probability density proportional to f.

The argument f may be

a numerical constant:

uniformly distributed random points will be generated.

a function:

random points will be generated in the window win with probability density proportional to f(x,y,...) where x and y are the cartesian coordinates. The function f must accept two vectors of coordinates x,y and return the corresponding vector of function values. Additional arguments ... of any kind may be passed to the function.

a pixel image:

if f is a pixel image (object of class "im", see im.object) then random points will be generated with probability density proportional to the pixel values of f. To be precise, pixels are selected with probabilities proportional to the pixel values, and within each selected pixel, a point is generated with a uniform distribution inside the pixel.

The window of the simulated point pattern is determined as follows. If forcewin=FALSE (the default) then the argument win is ignored, and the simulation window is the window of the pixel image, Window(f). If forcefit=TRUE then the simulation window is win.

The algorithm is as follows:

• If f is a constant, we invoke runifpoint.

• If f is a function, then we use the rejection method. Proposal points are generated from the uniform distribution. A proposal point \((x,y)\) is accepted with probability f(x,y,...)/fmax and otherwise rejected. The algorithm continues until n points have been accepted. It gives up after giveup * n proposals if there are still fewer than n points.

• If f is a pixel image, then a random sequence of pixels is selected (using sample) with probabilities proportional to the pixel values of f. Then for each pixel in the sequence we generate a uniformly distributed random point in that pixel.

The algorithm for pixel images is more efficient than that for functions.

If warn=TRUE (the default), a warning will be issued if n is very large. The threshold is spatstat.options("huge.npoints"). This warning has no consequences, but it helps to trap a number of common errors.

See Also

ppp.object, owin.object, im.object, runifpoint

Examples

 # 100 uniform random points in the unit square
 X <- rpoint(100)

 # 100 random points with probability density proportional to x^2 + y^2
 X <- rpoint(100, function(x,y) { x^2 + y^2}, 1)

 # `fmax' may be omitted
 X <- rpoint(100, function(x,y) { x^2 + y^2})

 # irregular window
 X <- rpoint(100, function(x,y) { x^2 + y^2}, win=letterR)

 # make a pixel image 
 Z <- setcov(letterR)
 # 100 points with density proportional to pixel values
 X <- rpoint(100, Z)