discretise {spatstat.geom}

Safely Convert Point Pattern Window to Binary Mask

Description

Given a point pattern, discretise its window by converting it to a binary pixel mask, adjusting the mask so that it still contains all the points. Optionally discretise the point locations as well, by moving them to the nearest pixel centres.

Usage

  discretise(X, eps = NULL, dimyx = NULL, xy = NULL, move.points=FALSE,
             rule.eps=c("adjust.eps", "grow.frame", "shrink.frame"))

Arguments

X

A point pattern (object of class "ppp") to be converted.

eps

(optional) width and height of each pixel

dimyx

(optional) pixel array dimensions

xy

(optional) pixel coordinates

move.points

Logical value specifying whether the points should also be discretised by moving each point to the nearest pixel centre.

rule.eps

Argument passed to as.mask controlling the discretisation.

Details

This function modifies the point pattern X by converting its observation window Window(X) to a binary pixel image (a window of type "mask"). It ensures that no points of X are deleted by the discretisation. If move.points=TRUE, the point coordinates are also discretised.

The window is first discretised using as.mask. Next,

• If move.points=TRUE, each point of X is moved to the centre of the nearest pixel inside the discretised window.

• If move.points=FALSE (the default), the point coordinates are unchanged. It can happen that points of X that were inside the original window may fall outside the new mask. The discretise function corrects this by augmenting the mask (so that the mask includes any pixel that contains a point of the pattern).

The arguments eps, dimyx, xy and rule.eps control the fineness of the pixel array. They are passed to as.mask.

If eps, dimyx and xy are all absent or NULL, and if the window of X is of type "mask" to start with, then discretise(X) returns X unchanged.

See as.mask for further details about the arguments eps, dimyx, xy and rule.eps, and the process of converting a window to one of type mask.

Value

A point pattern (object of class "ppp").

Error checking

Before doing anything, discretise checks that all the points of the pattern are actually inside the original window. This is guaranteed to be the case if the pattern was constructed using ppp or as.ppp. However anomalies are possible if the point pattern was created or manipulated inappropriately. These will cause an error.

Author(s)

Adrian Baddeley [e-mail] and Rolf Turner [e-mail]

See Also

as.mask

Examples

  X <- demopat
  plot(X, main="original pattern")
  Y <- discretise(X, dimyx=50)
  plot(Y, main="discretise(X)")
  stopifnot(npoints(X) == npoints(Y))

  # what happens if we just convert the window to a mask?
  W <- Window(X)
  M <- as.mask(W, dimyx=50)
  plot(M, main="window of X converted to mask")
  plot(X, add=TRUE, pch=16)
  plot(X[M], add=TRUE, pch=1, cex=1.5)
  XM <- X[M]
  cat(paste(npoints(X) - npoints(XM), "points of X lie outside M\n"))