as.psp.Rd
\name{as.psp}
\alias{as.psp}
\alias{as.psp.psp}
\alias{as.psp.data.frame}
\alias{as.psp.matrix}
\alias{as.psp.owin}
\alias{as.psp.default}
\title{Convert Data To Class psp}
\description{
Tries to coerce any reasonable kind of data object to a line segment pattern
(an object of class \code{"psp"})
for use by the \pkg{spatstat} package.
}
\usage{
as.psp(x, \dots, from=NULL, to=NULL)
\method{as.psp}{psp}(x, \dots, check=FALSE, fatal=TRUE)
\method{as.psp}{data.frame}(x, \dots, window=NULL, marks=NULL, check=spatstat.options("checksegments"), fatal=TRUE)
\method{as.psp}{matrix}(x, \dots, window=NULL, marks=NULL, check=spatstat.options("checksegments"),
fatal=TRUE)
\method{as.psp}{owin}(x, \dots, check=spatstat.options("checksegments"), fatal=TRUE)
\method{as.psp}{default}(x, \dots, window=NULL, marks=NULL,
check=spatstat.options("checksegments"), fatal=TRUE)
}
\arguments{
\item{x}{Data which will be converted into a line segment pattern}
\item{window}{Data which define a window for the pattern
when \code{x} does not contain a window}
\item{\dots}{Ignored.}
\item{marks}{(Optional) vector or data frame of marks for the pattern}
\item{check}{
Logical value indicating whether to check the validity of the data,
e.g. to check that the line segments lie inside the window.
}
\item{fatal}{Logical value. See Details.}
\item{from,to}{Point patterns (object of class \code{"ppp"})
containing the first and second endpoints (respectively) of each
segment. Incompatible with \code{x}.
}
}
\value{
An object of class \code{"psp"} (see \code{\link{psp.object}})
describing the line segment pattern and its window of observation.
The value \code{NULL} may also be returned; see Details.
}
\details{
Converts the dataset \code{x} to a line segment pattern
(an object of class \code{"psp"}; see \code{\link{psp.object}} for
an overview).
This function is normally used to convert an existing line segment pattern
dataset, stored in another format, to the \code{"psp"} format.
To create a new point pattern from raw data such as \eqn{x,y}
coordinates, it is normally easier to use the creator function
\code{\link{psp}}.
The dataset \code{x} may be:
\itemize{
\item
an object of class \code{"psp"}
\item
a data frame with at least 4 columns
\item a structure (list) with elements named \code{x0, y0,
x1, y1} or elements named \code{xmid, ymid, length, angle}
and possibly a fifth element named \code{marks}
\item
an object of class \code{"owin"} representing a spatial window;
it must be of type \code{"rectangle"} or \code{"polygonal"}.
The boundary edges of the window will be extracted as a line
segment pattern.
}
If \code{x} is a data frame the interpretation of its columns is
as follows:
\itemize{
\item
If there are columns named \code{x0, y0, x1, y1} then these
will be interpreted as the coordinates of the endpoints of
the segments and used to form the \code{ends} component of
the \code{psp} object to be returned.
\item
If there are columns named \code{xmid, ymid, length, angle}
then these will be interpreted as the coordinates of the segment
midpoints, the lengths of the segments, and the orientations
of the segments in radians and used to form the \code{ends}
component of the \code{psp} object to be returned.
\item
If there is a column named \code{marks} then this will
be interpreted as the marks of the pattern provided that
the argument \code{marks} of this function is \code{NULL}.
If argument \code{marks} is not \code{NULL} then the value
of this argument is taken to be the marks of the pattern and
the column named \code{marks} is ignored (with a warning).
In either case the column named marks is deleted and omitted
from further consideration.
\item
If there is no column named \code{marks} and if the \code{marks}
argument of this function is \code{NULL}, and if after
interpreting 4 columns of \code{x} as determining the \code{ends}
component of the \code{psp} object to be returned, there remain
other columns of \code{x}, then these remaining columns will be
taken to form a data frame of marks for the \code{psp} object
to be returned.
}
If \code{x} is a structure (list) with elements named \code{x0,
y0, x1, y1, marks} or \code{xmid, ymid, length, angle, marks},
then the element named \code{marks} will be interpreted as the
marks of the pattern provide that the argument \code{marks} of
this function is \code{NULL}. If this argument is non-\code{NULL}
then it is interpreted as the marks of the pattern and the element
\code{marks} of \code{x} is ignored --- with a warning.
Alternatively, you may specify two point patterns
\code{from} and \code{to} containing the first and second endpoints
of the line segments.
The argument \code{window} is converted to a window object
by the function \code{\link{as.owin}}.
The argument \code{fatal} indicates what to do when
the data cannot be converted to a line segment pattern.
If \code{fatal=TRUE}, a fatal error
will be generated; if \code{fatal=FALSE}, the
value \code{NULL} is returned.
The function \code{as.psp} is generic, with methods for the
classes \code{"psp"}, \code{"data.frame"}, \code{"matrix"}
and a default method.
Point pattern datasets can also be created by the function
\code{\link{psp}}.
}
\section{Warnings}{
If only a proper subset of the names \code{x0,y0,x1,y1} or
\code{xmid,ymid,length,angle} appear amongst the names of the
columns of \code{x} where \code{x} is a data frame, then these
special names are ignored.
For example if the names of the columns were
\code{xmid,ymid,length,degrees}, then these columns would be
interpreted as if the represented \code{x0,y0,x1,y1} in that order.
Whether it gets used or not, column named \code{marks} is
\emph{always} removed from \code{x} before any attempt to form the
\code{ends} component of the \code{psp} object that is returned.
}
\seealso{
\code{\link{psp}},
\code{\link{psp.object}},
\code{\link{as.owin}},
\code{\link{owin.object}}
}
\examples{
mat <- matrix(runif(40), ncol=4)
mx <- data.frame(v1=sample(1:4,10,TRUE),
v2=factor(sample(letters[1:4],10,TRUE),levels=letters[1:4]))
a <- as.psp(mat, window=owin(),marks=mx)
mat <- cbind(as.data.frame(mat),mx)
b <- as.psp(mat, window=owin()) # a and b are identical.
stuff <- list(xmid=runif(10),
ymid=runif(10),
length=rep(0.1, 10),
angle=runif(10, 0, 2 * pi))
a <- as.psp(stuff, window=owin())
b <- as.psp(from=runifpoint(10), to=runifpoint(10))
}
\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{manip}