pixellate.ppp {spatstat.geom}

Convert Point Pattern to Pixel Image

Description

Converts a point pattern to a pixel image. The value in each pixel is the number of points falling in that pixel, and is typically either 0 or 1.

Usage

## S3 method for class 'ppp'
pixellate(x, W=NULL, ..., weights = NULL,
                        padzero=FALSE, fractional=FALSE, preserve=FALSE,
                        DivideByPixelArea=FALSE, savemap=FALSE)

## S3 method for class 'ppp'
as.im(X, ...)

Arguments

x, X

Point pattern (object of class "ppp").

...

Arguments passed to as.mask to determine the pixel resolution

W

Optional window mask (object of class "owin") determining the pixel raster.

weights

Optional vector of weights associated with the points.

padzero

Logical value indicating whether to set pixel values to zero outside the window.

fractional, preserve

Logical values determining the type of discretisation. See Details.

DivideByPixelArea

Logical value, indicating whether the resulting pixel values should be divided by the pixel area.

savemap

Logical value, indicating whether to save information about the discretised coordinates of the points of x.

Details

The functions pixellate.ppp and as.im.ppp convert a spatial point pattern x into a pixel image, by counting the number of points (or the total weight of points) falling in each pixel.

Calling as.im.ppp is equivalent to calling pixellate.ppp with its default arguments. Note that pixellate.ppp is more general than as.im.ppp (it has additional arguments for greater flexibility).

The functions as.im.ppp and pixellate.ppp are methods for the generic functions as.im and pixellate respectively, for the class of point patterns.

The pixel raster (in which points are counted) is determined by the argument W if it is present (for pixellate.ppp only). In this case W should be a binary mask (a window object of class "owin" with type "mask"). Otherwise the pixel raster is determined by extracting the window containing x and converting it to a binary pixel mask using as.mask. The arguments ... are passed to as.mask to control the pixel resolution.

If weights is NULL, then for each pixel in the mask, the algorithm counts how many points in x fall in the pixel. This count is usually either 0 (for a pixel with no data points in it) or 1 (for a pixel containing one data point) but may be greater than 1. The result is an image with these counts as its pixel values.

If weights is given, it should be a numeric vector of the same length as the number of points in x. For each pixel, the algorithm finds the total weight associated with points in x that fall in the given pixel. The result is an image with these total weights as its pixel values.

By default (if zeropad=FALSE) the resulting pixel image has the same spatial domain as the window of the point pattern x. If zeropad=TRUE then the resulting pixel image has a rectangular domain; pixels outside the original window are assigned the value zero.

The discretisation procedure is controlled by the arguments fractional and preserve.

• The argument fractional specifies how data points are mapped to pixels. If fractional=FALSE (the default), each data point is allocated to the nearest pixel centre. If fractional=TRUE, each data point is allocated with fractional weight to four pixel centres (the corners of a rectangle containing the data point).

• The argument preserve specifies what to do with pixels lying near the boundary of the window, if the window is not a rectangle. If preserve=FALSE (the default), any contributions that are attributed to pixel centres lying outside the window are reset to zero. If preserve=TRUE, any such contributions are shifted to the nearest pixel lying inside the window, so that the total mass is preserved.

If savemap=TRUE then the result has an attribute "map" which is a 2-column matrix containing the row and column indices of the discretised positions of the points of x in the pixel grid.

Value

A pixel image (object of class "im").

Author(s)

Adrian Baddeley [e-mail], Rolf Turner [e-mail] and Ege Rubak [e-mail].

See Also

pixellate, im, as.im, density.ppp, Smooth.ppp.

Examples

  plot(pixellate(humberside))
  plot(pixellate(humberside, fractional=TRUE))