Creates an object of class "ppp" representing
a point pattern dataset in the two-dimensional plane.
ppp(x,y, …, window, marks,
check=TRUE, checkdup=check, drop=TRUE)Vector of \(x\) coordinates of data points
Vector of \(y\) coordinates of data points
window of observation,
an object of class "owin"
arguments passed to owin to create the
window, if window is missing
(optional) mark values for the points. A vector or data frame.
Logical value indicating whether to check
that all the \((x,y)\) points lie inside the specified window.
Do not set this to FALSE unless you are absolutely sure that this
check is unnecessary. See Warnings below.
Logical value indicating whether to check for duplicated coordinates. See Warnings below.
Logical flag indicating whether to simplify data frames of marks. See Details.
An object of class "ppp"
describing a point pattern in the two-dimensional plane
(see ppp.object).
The coordinate vectors x and y must contain only
finite numerical values. If the coordinates include
any of the values NA, NaN, Inf or -Inf,
these will be removed.
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.
The code will check for problems with the data, and issue a warning if any problems are found. The checks and warnings can be switched off, for efficiency's sake, but this should only be done if you are confident that the data do not have these problems.
Setting check=FALSE will disable all the checking procedures:
the check for points outside the window, and the check for
duplicated points. This is extremely dangerous, because points lying
outside the window will break many of the procedures in
spatstat, causing crashes and strange errors.
Set check=FALSE only if you are absolutely
sure that there are no points outside the window.
If duplicated points are found, a warning is issued, but no action is
taken. Duplicated points are not illegal, but may cause unexpected problems
later. Setting checkdup=FALSE will disable the check for duplicated
points. Do this only if you already know the answer.
Methodology and software for spatial point patterns often assume
that all points are distinct so that there are no duplicated points.
If duplicated points are present, the consequence could be
an incorrect result or a software crash. To the best of our knowledge,
all spatstat code handles duplicated points correctly.
However, if duplicated points are present, we advise using
unique.ppp or multiplicity.ppp
to eliminate duplicated points and re-analyse the data.
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. Note that x and y are
permitted to have length zero, corresponding to an empty point
pattern; this is the default if these arguments are missing.
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"
specifying the window. A window object can be created
by owin from raw coordinate data. Special shapes
of windows can be created by the functions
square, hexagon,
regularpolygon, disc
and ellipse. See the Examples.
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.
# NOT RUN {
# 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)
# }
# NOT RUN {
# 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)
# }
# NOT RUN {
# polygonal window
X <- ppp(x, y, poly=list(x=c(0,10,0), y=c(0,0,10)))
# }
# NOT RUN {
plot(X)
# }
# NOT RUN {
# circular window of radius 2
X <- ppp(x, y, window=disc(2))
# copy the window from another pattern
data(cells)
X <- ppp(x, y, window=Window(cells))
# }
Run the code above in your browser using DataLab