envelope(Y, fun, ...)
## S3 method for class 'ppp':
envelope(Y, fun=Kest, nsim=99, nrank=1, \dots,
simulate=NULL, verbose=TRUE, clipdata=TRUE,
transform=NULL, global=FALSE, ginterval=NULL,
savefuns=FALSE, savepatterns=FALSE,
nsim2=nsim, VARIANCE=FALSE, nSD=2, Yname=NULL, maxnerr=nsim)
## S3 method for class 'ppm':
envelope(Y, fun=Kest, nsim=99, nrank=1, \dots,
simulate=NULL, verbose=TRUE, clipdata=TRUE,
start=NULL, control=default.rmhcontrol(Y, nrep=nrep), nrep=1e5,
transform=NULL, global=FALSE, ginterval=NULL,
savefuns=FALSE, savepatterns=FALSE,
nsim2=nsim, VARIANCE=FALSE, nSD=2, Yname=NULL, maxnerr=nsim)
## S3 method for class 'kppm':
envelope(Y, fun=Kest, nsim=99, nrank=1, \dots,
simulate=NULL, verbose=TRUE, clipdata=TRUE,
transform=NULL, global=FALSE, ginterval=NULL,
savefuns=FALSE, savepatterns=FALSE,
nsim2=nsim, VARIANCE=FALSE, nSD=2, Yname=NULL, maxnerr=nsim)
"ppp"
) or a fitted point process model
(object of class "ppm"
or "kppm"
).nsim
simulated
values. A rank of 1 means that the minimum and maximum
simulated values will be used.fun
.simulate
is an expression in the R language, then this
expression will be evaluated nsim
times,
to obtain nsim
point patterns which areTRUE
to ensure that the
data astart
and control
of rmh
, giving complete control over the simulation
algorithm. Applicable only when Y
is a fitted model
of class "ppm"
.Y
is a fitted model
of class "ppm"
.global=FALSE
) or simultaneous (global=TRUE
).global=TRUE
.global=TRUE
and the simulations are not based on CSR.TRUE
, critical envelopes will be calculated
as sample mean plus or minus nSD
times sample standard
deviation.VARIANCE=TRUE
.Y
when printing or plotting the results.fun
yields an error when applied to a simulated point
pattern (for example, because the pattern is empty and fun
requires at least one point), the pattern will be rejected
a"fv"
, see fv.object
,
which can be printed and plotted directly.Essentially a data frame containing columns
fun
has been estimatedsavepatterns=TRUE
, the return value has an attribute
"simpatterns"
which is a list containing the nsim
simulated patterns. If savefuns=TRUE
, the return value
has an attribute "simfuns"
which is an object of class
"fv"
containing the summary functions
computed for each of the nsim
simulated patterns.fun
.
The upper envelope may be NA
(plotted as plus or minus
infinity) if some of the function values
computed for the simulated point patterns are NA
.
Whether this occurs will depend on the function fun
,
but it usually happens when the simulated point pattern does not contain
enough points to compute a meaningful value.varblock
.envelope
command performs simulations and
computes envelopes of a summary statistic based on the simulations.
The result is an object that can be plotted to display the envelopes.
The envelopes can be used to assess the goodness-of-fit of
a point process model to point pattern data. For the most basic use, if you have a point pattern X
and
you want to test Complete Spatial Randomness (CSR), type
plot(envelope(X, Kest,nsim=39))
to see the $K$ function
for X
plotted together with the envelopes of the
$K$ function for 39 simulations of CSR.
The envelope
function is generic, with methods for
the classes "ppp"
, "ppm"
and "kppm"
described here. There is also a method for the class "pp3"
which is described separately as envelope.pp3
.
To create simulation envelopes, the command envelope(Y, ...)
first generates nsim
random point patterns
in one of the following ways.
Y
is a point pattern (an object of class"ppp"
)
andsimulate=NULL
,
then we generatensim
simulations of
Complete Spatial Randomness (i.e.nsim
simulated point patterns
each being a realisation of the uniform Poisson point process)
with the same intensity as the patternY
.
(IfY
is a multitype point pattern, then the simulated patterns
are also given independent random marks; the probability
distribution of the random marks is determined by the
relative frequencies of marks inY
.)Y
is a fitted point process model (an object of class"ppm"
or"kppm"
) andsimulate=NULL
,
then this routine generatesnsim
simulated
realisations of that model.simulate
is supplied, then it determines how the
simulated point patterns are generated. It may be eithernsim
times to yieldnsim
point patterns. For example
ifsimulate=expression(runifpoint(100))
then each simulated
pattern consists of exactly 100 independent uniform random points."envelope"
. This should have been
produced by callingenvelope
with the
argumentsavepatterns=TRUE
.
The simulated point patterns that were saved in this object
will be extracted and used as the simulated patterns for the
new envelope computation. This makes it possible to plot envelopes
for two different summary functions based on exactly the same set of
simulated point patterns.fun
is applied to each of these simulated
patterns. Typically fun
is one of the functions
Kest
, Gest
, Fest
, Jest
, pcf
,
Kcross
, Kdot
, Gcross
, Gdot
,
Jcross
, Jdot
, Kmulti
, Gmulti
,
Jmulti
or Kinhom
. It may also be a character string
containing the name of one of these functions. The statistic fun
can also be a user-supplied function;
if so, then it must have arguments X
and r
like those in the functions listed above, and it must return an object
of class "fv"
.
Upper and lower critical envelopes are computed in one of the following ways:
[object Object],[object Object],[object Object]
The return value is an object of class "fv"
containing
the summary function for the data point pattern,
the upper and lower simulation envelopes, and
the theoretical expected value (exact or estimated) of the summary function
for the model being tested. It can be plotted
using plot.envelope
.
If VARIANCE=TRUE
then the return value also includes the
sample mean, sample variance and other quantities.
Arguments can be passed to the function fun
through
...
. This makes it possible to select the edge correction
used to calculate the summary statistic. See the Examples.
Selecting only a single edge
correction will make the code run much faster.
If Y
is a fitted cluster point process model (object of
class "kppm"
), and simulate=NULL
,
then the model is simulated directly
using simulate.kppm
.
If Y
is a fitted Gibbs point process model (object of
class "ppm"
), and simulate=NULL
,
then the model is simulated
by running the Metropolis-Hastings algorithm rmh
.
Complete control over this algorithm is provided by the
arguments start
and control
which are passed
to rmh
.
For simultaneous critical envelopes (global=TRUE
)
the following options are also useful:
[object Object],[object Object]
It is also possible to extract the summary functions for each of the
individual simulated point patterns, by setting savefuns=TRUE
.
Then the return value also
has an attribute "simfuns"
containing all the
summary functions for the individual simulated patterns.
It is an "fv"
object containing
functions named sim1, sim2, ...
representing the nsim
summary functions.
It is also possible to save the simulated point patterns themselves,
by setting savepatterns=TRUE
. Then the return value also has
an attribute "simpatterns"
which is a list of length
nsim
containing all the simulated point patterns.
See plot.envelope
and plot.fv
for information about how to plot the envelopes.
Different envelopes can be recomputed from the same data
using envelope.envelope
.
Envelopes can be combined using pool.envelope
.
Diggle, P.J. Statistical analysis of spatial point patterns. Arnold, 2003.
Ripley, B.D. (1981) Spatial statistics. John Wiley and Sons.
Ripley, B.D. Statistical inference for spatial processes. Cambridge University Press, 1988.
Stoyan, D. and Stoyan, H. (1994) Fractals, random shapes and point fields: methods of geometrical statistics. John Wiley and Sons.
fv.object
,
plot.envelope
,
plot.fv
,
envelope.envelope
,
pool.envelope
,
Kest
,
Gest
,
Fest
,
Jest
,
pcf
,
ppp
,
ppm
,
default.expand
data(simdat)
X <- simdat
# Envelope of K function under CSR
plot(envelope(X))
<testonly>plot(envelope(X, nsim=4))</testonly>
# Translation edge correction (this is also FASTER):
plot(envelope(X, correction="translate"))
<testonly>plot(envelope(X, nsim=4, correction="translate"))</testonly>
# Envelope of K function for simulations from Gibbs model
data(cells)
fit <- ppm(cells, ~1, Strauss(0.05))
plot(envelope(fit))
plot(envelope(fit), global=TRUE)
<testonly>plot(envelope(fit, nsim=4))
plot(envelope(fit, nsim=4, global=TRUE))</testonly>
# Envelope of K function for simulations from cluster model
data(redwood)
fit <- kppm(redwood, ~1, "Thomas")
plot(envelope(fit, Gest))
plot(envelope(fit, Gest, global=TRUE))
<testonly>plot(envelope(fit, Gest, nsim=4))
plot(envelope(fit, Gest, nsim=4, global=TRUE))</testonly>
# Envelope of G function under CSR
plot(envelope(X, Gest))
<testonly>plot(envelope(X, Gest, nsim=4))</testonly>
# Envelope of L function under CSR
# L(r) = sqrt(K(r)/pi)
E <- envelope(X, Kest)
plot(E, sqrt(./pi) ~ r)
<testonly>E <- envelope(X, Kest, nsim=4)
plot(E, sqrt(./pi) ~ r)</testonly>
# Simultaneous critical envelope for L function
# (alternatively, use Lest)
plot(envelope(X, Kest, transform=expression(sqrt(./pi)), global=TRUE))
<testonly>plot(envelope(X, Kest, nsim=4,transform=expression(sqrt(./pi)), global=TRUE))</testonly>
# How to pass arguments needed to compute the summary functions:
# We want envelopes for Jcross(X, "A", "B")
# where "A" and "B" are types of points in the dataset 'demopat'
data(demopat)
plot(envelope(demopat, Jcross, i="A", j="B"))
<testonly>plot(envelope(demopat, Jcross, i="A", j="B", nsim=4))</testonly>
# Use of `simulate'
plot(envelope(cells, Gest, simulate=expression(runifpoint(42))))
plot(envelope(cells, Gest, simulate=expression(rMaternI(100,0.02))))
<testonly>plot(envelope(cells, Gest, simulate=expression(runifpoint(42)), nsim=4))
plot(envelope(cells, Gest, simulate=expression(rMaternI(100, 0.02)), nsim=4))
plot(envelope(cells, Gest, simulate=expression(runifpoint(42)),
nsim=4, global=TRUE))
plot(envelope(cells, Gest, simulate=expression(rMaternI(100, 0.02)),
nsim=4, global=TRUE))</testonly>
# Envelope under random toroidal shifts
data(amacrine)
plot(envelope(amacrine, Kcross, i="on", j="off",
simulate=expression(rshift(amacrine, radius=0.25))))
# Envelope under random shifts with erosion
plot(envelope(amacrine, Kcross, i="on", j="off",
simulate=expression(rshift(amacrine, radius=0.1, edge="erode"))))
# Envelope of INHOMOGENEOUS K-function with fitted trend
trend <- density.ppp(X, 1.5)
plot(envelope(X, Kinhom, lambda=trend,
simulate=expression(rpoispp(trend))))
# Precomputed list of point patterns
X <- rpoispp(50)
PatList <- list()
for(i in 1:20) PatList[[i]] <- runifpoint(X$n)
plot(envelope(X, Kest, nsim=20, simulate=PatList))
# re-using the same point patterns
EK <- envelope(X, Kest, nsim=10, savepatterns=TRUE)
EG <- envelope(X, Kest, nsim=10, simulate=EK)
Run the code above in your browser using DataLab