spatstat (version 1.48-0)

ppp: Create a Point Pattern

Description

Creates an object of class "ppp" representing a point pattern dataset in the two-dimensional plane.

Usage

ppp(x,y, ..., window, marks, check=TRUE, drop=TRUE)

Arguments

x

Vector of $x$ coordinates of data points

y

Vector of $y$ coordinates of data points

window

window of observation, an object of class "owin"

...

arguments passed to owin to create the window, if window is missing

marks

(optional) mark values for the points. A vector or data frame.

check

Logical flag indicating whether to check that all the $(x,y)$ points lie inside the specified window. Do not set this to FALSE unless you are sure that this check is unnecessary.

drop

Logical flag indicating whether to simplify data frames of marks. See Details.

Value

An object of class "ppp" describing a point pattern in the two-dimensional plane (see ppp.object).

Rejected points

The points with coordinates x and y must lie inside the specified window, in order to define a valid object of class "ppp". Any points which do not lie inside the window will be removed from the point pattern, and a warning will be issued. The rejected points are still accessible: they are stored as an attribute of the point pattern called "rejects" (which is an object of class "ppp" containing the rejected points in a large window). However, rejected points in a point pattern will be ignored by all other functions except plot.ppp. To remove the rejected points altogether, use as.ppp. To include the rejected points, you will need to find a larger window that contains them, and use this larger window in a call to ppp.

Details

In the spatstat library, a point pattern dataset is described by an object of class "ppp". This function creates such objects.

The vectors x and y must be numeric vectors of equal length. They are interpreted as the cartesian coordinates of the points in the pattern.

A point pattern dataset is assumed to have been observed within a specific region of the plane called the observation window. An object of class "ppp" representing a point pattern contains information specifying the observation window. This window must always be specified when creating a point pattern dataset; there is intentionally no default action of ``guessing'' the window dimensions from the data points alone.

You can specify the observation window in several (mutually exclusive) ways:

• xrange, yrange specify a rectangle with these dimensions;
• poly specifies a polygonal boundary. If the boundary is a single polygon then poly must be a list with components x,y giving the coordinates of the vertices. If the boundary consists of several disjoint polygons then poly must be a list of such lists so that poly[[i]]$x gives the $x$ coordinates of the vertices of the $i$th boundary polygon.
• mask specifies a binary pixel image with entries that are TRUE if the corresponding pixel is inside the window.
• window is an object of class "owin" (see owin.object) specifying the window.

The arguments xrange, yrange or poly or mask are passed to the window creator function owin for interpretation. See owin for further details.

The argument window, if given, must be an object of class "owin". It is a full description of the window geometry, and could have been obtained from owin or as.owin, or by just extracting the observation window of another point pattern, or by manipulating such windows. See owin or the Examples below.

The points with coordinates x and y must lie inside the specified window, in order to define a valid object of this class. Any points which do not lie inside the window will be removed from the point pattern, and a warning will be issued. See the section on Rejected Points.

The name of the unit of length for the x and y coordinates can be specified in the dataset, using the argument unitname, which is passed to owin. See the examples below, or the help file for owin. The optional argument marks is given if the point pattern is marked, i.e. if each data point carries additional information. For example, points which are classified into two or more different types, or colours, may be regarded as having a mark which identifies which colour they are. Data recording the locations and heights of trees in a forest can be regarded as a marked point pattern where the mark is the tree height. The argument marks can be either

• a vector, of the same length as x and y, which is interpreted so that marks[i] is the mark attached to the point (x[i],y[i]). If the mark is a real number then marks should be a numeric vector, while if the mark takes only a finite number of possible values (e.g. colours or types) then marks should be a factor.
• a data frame, with the number of rows equal to the number of points in the point pattern. The ith row of the data frame is interpreted as containing the mark values for the ith point in the point pattern. The columns of the data frame correspond to different mark variables (e.g. tree species and tree diameter).

If drop=TRUE (the default), then a data frame with only one column will be converted to a vector, and a data frame with no columns will be converted to NULL. See ppp.object for a description of the class "ppp".

Users would normally invoke ppp to create a point pattern, but the functions as.ppp and scanpp may sometimes be convenient.

See Also

ppp.object, as.ppp, owin.object, owin, as.owin

Examples

  # some arbitrary coordinates in [0,1]
  x <- runif(20)
  y <- runif(20)

  # the following are equivalent
  X <- ppp(x, y, c(0,1), c(0,1))
  X <- ppp(x, y)
  X <- ppp(x, y, window=owin(c(0,1),c(0,1)))

  # specify that the coordinates are given in metres
  X <- ppp(x, y, c(0,1), c(0,1), unitname=c("metre","metres"))

  ## Not run: plot(X)

  # marks
  m <- sample(1:2, 20, replace=TRUE)
  m <- factor(m, levels=1:2)
  X <- ppp(x, y, c(0,1), c(0,1), marks=m)
  ## Not run: plot(X)

  # polygonal window
  X <- ppp(x, y, poly=list(x=c(0,10,0), y=c(0,0,10)))
  ## Not run: plot(X)

  # copy the window from another pattern
  data(cells)
  X <- ppp(x, y, window=Window(cells))