rlabel: Random Re-Labelling of Point Pattern

Description

Randomly allocates marks to a point pattern, or permutes the existing marks, or resamples from the existing marks.

Usage

rlabel(X, labels=marks(X), permute=TRUE, group=NULL, …, nsim=1, drop=TRUE)

Arguments

Point pattern (object of class "ppp", "lpp", "pp3" or "ppx") or line segment pattern (object of class "psp").

labels

Vector of values from which the new marks will be drawn at random. Defaults to the vector of existing marks.

permute

Logical value indicating whether to generate new marks by randomly permuting labels or by drawing a random sample with replacement.

group

Optional. A factor, or other data dividing the points into groups. Random relabelling will be performed separately within each group. See Details.

…

Additional arguments passed to cut.ppp to determine the grouping factor, when group is given.

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.

Value

If nsim = 1 and drop=TRUE, a marked point pattern (of the same class as X). If nsim > 1, a list of point patterns.

Details

This very simple function allocates random marks to an existing point pattern X. It is useful for hypothesis testing purposes. (The function can also be applied to line segment patterns.)

In the simplest case, the command rlabel(X) yields a point pattern obtained from X by randomly permuting the marks of the points.

If permute=TRUE, then labels should be a vector of length equal to the number of points in X. The result of rlabel will be a point pattern with locations given by X and marks given by a random permutation of labels (i.e. a random sample without replacement).

If permute=FALSE, then labels may be a vector of any length. The result of rlabel will be a point pattern with locations given by X and marks given by a random sample from labels (with replacement).

The argument group specifies that the points are divided into several different groups, and that the random labelling shall be performed separately on each group. The arguments group and … are passed to cut.ppp to determine the grouping. Thus group could be a factor, or the name of a column of marks in X, or a tessellation, or a factor-valued pixel image, etc.

Examples

Run this code

# NOT RUN {
   amacrine

   # Randomly permute the marks "on" and "off"
   # Result always has 142 "off" and 152 "on"
   Y <- rlabel(amacrine)

   # randomly allocate marks "on" and "off"
   # with probabilities p(off) = 0.48, p(on) = 0.52
   Y <- rlabel(amacrine, permute=FALSE)

   # randomly allocate marks "A" and "B" with equal probability
   Y <- rlabel(cells, labels=factor(c("A", "B")), permute=FALSE)

   # divide the window into tiles and 
   # randomly permute the marks within each tile
   Z <- rlabel(amacrine, group=quadrats(Window(amacrine), 4, 3))
# }