# envelope.pp3

##### Simulation Envelopes of Summary Function for 3D Point Pattern

Computes simulation envelopes of a summary function for a three-dimensional point pattern.

##### Usage

```
## S3 method for class 'pp3':
envelope(Y, fun=K3est, nsim=99, nrank=1, \dots,
simulate=NULL, verbose=TRUE,
transform=NULL,global=FALSE,ginterval=NULL,use.theory=NULL,
alternative=c("two.sided", "less", "greater"),
savefuns=FALSE, savepatterns=FALSE,
nsim2=nsim, VARIANCE=FALSE, nSD=2, Yname=NULL, maxnerr=nsim,
do.pwrong=FALSE, envir.simul=NULL)
```

##### Arguments

- Y
- A three-dimensional point pattern (object of class
`"pp3"`

). - fun
- Function that computes the desired summary statistic for a 3D 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. - ...
- Extra arguments passed to
`fun`

. - simulate
- Optional. Specifies how to generate the simulated point patterns.
If
`simulate`

is an expression in the R language, then this expression will be evaluated`nsim`

times, to obtain`nsim`

point patterns which are - verbose
- Logical flag indicating whether to print progress reports during the simulations.
- transform
- Optional. A transformation to be applied to the function values, before the envelopes are computed. An expression object (see Details).
- global
- Logical flag indicating whether envelopes should be pointwise
(
`global=FALSE`

) or simultaneous (`global=TRUE`

). - ginterval
- Optional.
A vector of length 2 specifying
the interval of $r$ values for the simultaneous critical
envelopes. Only relevant if
`global=TRUE`

. - use.theory
- Logical value indicating whether to use the theoretical value,
computed by
`fun`

, as the reference value for simultaneous envelopes. Applicable only when`global=TRUE`

. - alternative
- Character string determining whether the envelope corresponds
to a two-sided test (
`side="two.sided"`

, the default) or a one-sided test with a lower critical boundary (`side="less"`

) or a one-sided test with an upper - savefuns
- Logical flag indicating whether to save all the simulated function values.
- savepatterns
- Logical flag indicating whether to save all the simulated point patterns.
- nsim2
- Number of extra simulated point patterns to be generated
if it is necessary to use simulation to estimate the theoretical
mean of the summary function. Only relevant when
`global=TRUE`

and the simulations are not based on CSR. - VARIANCE
- Logical. If
`TRUE`

, critical envelopes will be calculated as sample mean plus or minus`nSD`

times sample standard deviation. - nSD
- Number of estimated standard deviations used to determine
the critical envelopes, if
`VARIANCE=TRUE`

. - Yname
- Character string that should be used as the name of the
data point pattern
`Y`

when printing or plotting the results. - maxnerr
- Maximum number of rejected patterns.
If
`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 - do.pwrong
- Logical. If
`TRUE`

, the algorithm will also estimate the true significance level of thewrong test (the test that declares the summary function for the data to be significant if it lies outside the*pointwise* - envir.simul
- Environment in which to evaluate the expression
`simulate`

, if not the current environment.

##### Details

The `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.
The `envelope`

function is generic, with methods for
the classes `"ppp"`

, `"ppm"`

and `"kppm"`

described in the help file for `envelope`

.
This function `envelope.pp3`

is the method for
three-dimensional point patterns (objects of class `"pp3"`

).
For the most basic use, if you have a 3D point pattern `X`

and
you want to test Complete Spatial Randomness (CSR), type
`plot(envelope(X, K3est,nsim=39))`

to see the three-dimensional
$K$ function for `X`

plotted together with the envelopes of
the three-dimensional $K$ function for 39 simulations of CSR.
To create simulation envelopes, the command `envelope(Y, ...)`

first generates `nsim`

random point patterns
in one of the following ways.

- If
`simulate=NULL`

, then we generate`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
`simulate`

is supplied, then it determines how the simulated point patterns are generated. See`envelope`

for details.

`fun`

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

is one of the functions
`K3est`

, `G3est`

, `F3est`

or `pcf3est`

.
It may also be a character string
containing the name of one of these functions.
For further information, see the documentation for
`envelope`

.
##### Value

- A function value table (object of class
`"fv"`

) which can be plotted directly. See`envelope`

for further details.

##### References

Baddeley, A.J, Moyeed, R.A., Howard, C.V. and Boyde, A. (1993)
Analysis of a three-dimensional point pattern with replication.
*Applied Statistics* **42**, 641--668.

##### See Also

##### Examples

```
X <- rpoispp3(20, box3())
plot(envelope(X, nsim=39))
<testonly>plot(envelope(X, nsim=4))</testonly>
```

*Documentation reproduced from package spatstat, version 1.42-2, License: GPL (>= 2)*