split.ppp.Rd
\name{split.ppp}
\alias{split.ppp}
\alias{split<-.ppp}
\title{Divide Point Pattern into Sub-patterns}
\description{
Divides a point pattern into several sub-patterns,
according to their marks, or according to any user-specified grouping.
}
\usage{
\method{split}{ppp}(x, f = marks(x), drop=FALSE, un=NULL, \dots)
\method{split}{ppp}(x, f = marks(x), drop=FALSE, un=missing(f), \dots) <- value
}
\arguments{
\item{x}{
A two-dimensional point pattern.
An object of class \code{"ppp"}.
}
\item{f}{
Data determining the grouping. Either a factor,
a pixel image with factor values, a tessellation,
or the name of one of the columns of marks.
}
\item{drop}{
Logical. Determines whether empty groups will
be deleted.
}
\item{un}{
Logical. Determines whether the resulting subpatterns will be unmarked
(i.e. whether marks will be removed from the points in each
subpattern).
}
\item{\dots}{
Other arguments are ignored.
}
\item{value}{
List of point patterns.
}
}
\value{
The value of \code{split.ppp} is a list of point patterns.
The components of the list are named by the levels of \code{f}.
The list also has the class \code{"splitppp"}.
The assignment form \code{split<-.ppp} returns the updated
point pattern \code{x}.
}
\details{
The function \code{split.ppp}
divides up the points of the point pattern \code{x}
into several sub-patterns according to the values of \code{f}.
The result is a list of point patterns.
The argument \code{f} may be
\itemize{
\item
a factor, of length equal to the number of points in \code{x}.
The levels of \code{f}
determine the destination of each point in \code{x}.
The \code{i}th point of \code{x} will be placed in the sub-pattern
\code{split.ppp(x)$l} where \code{l = f[i]}.
\item
a pixel image (object of class \code{"im"}) with factor values.
The pixel value of \code{f}
at each point of \code{x} will be used as the classifying variable.
\item
a tessellation (object of class \code{"tess"}).
Each point of \code{x} will be classified according to
the tile of the tessellation into which it falls.
\item
a character string, matching the name of one of the columns of
marks, if \code{marks(x)} is a data frame. This column should
be a factor.
}
If \code{f} is missing, then it will be determined by the
marks of the point pattern. The pattern \code{x} can be either
\itemize{
\item
a multitype point pattern
(a marked point pattern whose marks vector is a factor).
Then \code{f} is taken to be the marks vector.
The effect is that the points of each type
are separated into different point patterns.
\item
a marked point pattern with a data frame of marks, containing at least one
column that is a factor. The first such column will be used to
determine the splitting factor \code{f}.
}
Some of the sub-patterns created by the split
may be empty. If \code{drop=TRUE}, then empty sub-patterns will
be deleted from the list. If \code{drop=FALSE} then they are retained.
The argument \code{un} determines how to handle marks
in the case where \code{x} is a marked point pattern.
If \code{un=TRUE} then the marks of the
points will be discarded when they are split into groups,
while if \code{un=FALSE} then the marks will be retained.
If \code{f} and \code{un} are both missing,
then the default is \code{un=TRUE} for multitype point patterns
and \code{un=FALSE} for marked point patterns with a data frame of
marks.
The result of \code{split.ppp} has class \code{"splitppp"}
and can be plotted using \code{\link{plot.splitppp}}.
The assignment function \code{split<-.ppp}
updates the point pattern \code{x} so that
it satisfies \code{split(x, f, drop, un) = value}. The argument \code{value}
is expected to be a list of point patterns, one for each level of
\code{f}. These point patterns are expected to be compatible with the
type of data in the original pattern \code{x}.
Splitting can also be undone by the function \code{\link{superimpose}}.
}
\seealso{
\code{\link{cut.ppp}},
\code{\link{plot.splitppp}},
\code{\link{superimpose}},
\code{\link{im}},
\code{\link{tess}},
\code{\link{ppp.object}}
}
\examples{
# (1) Splitting by marks
# Multitype point pattern: separate into types
data(amacrine)
u <- split(amacrine)
# plot them
plot(split(amacrine))
# the following are equivalent:
amon <- split(amacrine)$on
amon <- unmark(amacrine[amacrine$marks == "on"])
# the following are equivalent:
amon <- split(amacrine, un=FALSE)$on
amon <- amacrine[amacrine$marks == "on"]
# Scramble the locations of the 'on' cells
u <- split(amacrine)
u$on <- runifpoint(amon$n, amon$window)
split(amacrine) <- u
# Point pattern with continuous marks
data(longleaf)
\testonly{
# smaller dataset
longleaf <- longleaf[seq(1, longleaf$n, by=80)]
}
# cut the range of tree diameters into three intervals
# using cut.ppp
long3 <- cut(longleaf, breaks=3)
# now split them
long3split <- split(long3)
# (2) Splitting by a factor
# Unmarked point pattern
data(swedishpines)
# cut & split according to nearest neighbour distance
f <- cut(nndist(swedishpines), 3)
u <- split(swedishpines, f)
# (3) Splitting over a tessellation
tes <- tess(xgrid=seq(0,96,length=5),ygrid=seq(0,100,length=5))
v <- split(swedishpines, tes)
}
\author{Adrian Baddeley
\email{Adrian.Baddeley@csiro.au}
\url{http://www.maths.uwa.edu.au/~adrian/}
and Rolf Turner
\email{r.turner@auckland.ac.nz}
}
\keyword{spatial}
\keyword{methods}
\keyword{manip}