# envelope

##### Simulation envelopes of summary function

Computes simulation envelopes of a summary function.

- Keywords
- spatial

##### Usage

```
envelope(Y, fun=Kest, nsim=99, nrank=1, verbose=TRUE, ...,
simulate=NULL, start=NULL, control=list(nrep=1e5, expand=1.5))
```

##### Arguments

- Y
- Either a point pattern (object of class
`"ppp"`

) or a fitted point process model (object of class`"ppm"`

). - fun
- Function that computes the desired summary statistic for a point pattern.
- nsim
- Number of simulated point patterns to be generated when computing the envelopes.
- nrank
- Integer. Rank of the envelope value amongst the
`nsim`

simulated values. A rank of 1 means that the minimum and maximum simulated values will be used. - verbose
- Logical flag indicating whether to print progress reports during the simulations.
- ...
- Extra arguments passed to
`fun`

. - simulate
- Optional. An expression. If this is present, then the simulated
point patterns will be generated by evaluating this expression
`nsim`

times. - start,control
- Optional. These specify the arguments
`start`

and`control`

of`rmh`

, giving complete control over the simulation algorithm.

##### Details

Simulation envelopes can be used to assess the goodness-of-fit of a point process model to point pattern data. See the References.

This function first generates `nsim`

random point patterns
in one of the following ways.

- If
`Y`

is a point pattern (an object of class`"ppp"`

) and`simulate=NULL`

, then this routine generates`nsim`

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 pattern`Y`

. - If
`Y`

is a fitted point process model (an object of class`"ppm"`

) and`simulate=NULL`

, then this routine generates`nsim`

simulated realisations of that model. - If
`simulate`

is supplied, then it must be an expression. It will be evaluated`nsim`

times to yield`nsim`

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 pointwise envelopes are computed pointwise (i.e.
for each value of the distance argument $r$), by sorting the
`nsim`

simulated values, and taking the `m`

-th lowest
and `m`

-th highest values, where `m = nrank`

.
For example if `nrank=1`

, the upper and lower envelopes
are the pointwise maximum and minimum of the simulated values.

The significance level of the associated Monte Carlo test is
`alpha = 2 * nrank/(1 + nsim)`

.
The return value is an object of class `"fv"`

containing
the summary function for the data point pattern
and the upper and lower simulation envelopes. It can be plotted
using `plot.fv`

.

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.

If `Y`

is a fitted point process model, 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`

.

##### Value

- An object of class
`"fv"`

, see`fv.object`

, which can be plotted directly using`plot.fv`

.Essentially a data frame containing columns

r the vector of values of the argument $r$ at which the summary function `fun`

has been estimatedobs values of the summary function for the data point pattern lo lower envelope of simulations hi upper envelope of simulations

##### References

Cressie, N.A.C. *Statistics for spatial data*.
John Wiley and Sons, 1991.

Diggle, P.J. *Statistical analysis of spatial point patterns*.
Arnold, 2003.

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.

##### See Also

##### Examples

```
X <- rpoispp(42)
# Envelope of K function under CSR
plot(envelope(X))
<testonly>plot(envelope(X, nsim=5))</testonly>
# Translation edge correction (this is also FASTER):
plot(envelope(X, correction="translate"))
<testonly>plot(envelope(X, nsim=5, correction="translate"))</testonly>
# Envelope of K function for simulations from model
data(cells)
fit <- ppm(cells, ~1, Strauss(0.05))
plot(envelope(fit))
<testonly>plot(envelope(fit, nsim=4))</testonly>
# Envelope of G function under CSR
plot(envelope(X, Gest))
<testonly>plot(envelope(X, Gest, nsim=5))</testonly>
# Use of `simulate'
plot(envelope(X, Gest, simulate=expression(runifpoint(42))))
plot(envelope(X, Gest, simulate=expression(rMaternI(100,0.02))))
<testonly>plot(envelope(X, Gest, simulate=expression(runifpoint(42)), nsim=5))
plot(envelope(X, Gest, simulate=expression(rMaternI(100, 0.02)), nsim=5))</testonly>
```

*Documentation reproduced from package spatstat, version 1.7-11, License: GPL version 2 or newer*