# 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, ...)`

##### 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
- 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`

.

##### Details

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

If `Y`

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

)
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"`

) then this routine generates `nsim`

simulated
realisations of that model.
The summary statistic `fun`

is applied to each of these simulated
patterns. Typically `fun`

is one of the functions
`Kest`

, `Gest`

, `Fest`

, `Jest`

or `pcf`

.
It can also be a home-made function; it should 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.

##### 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>
```

*Documentation reproduced from package spatstat, version 1.6-5, License: GPL version 2 or newer*