1. Home
2. KCSRENVELOPES procedure

# KCSRENVELOPES procedure

Simulates K function bounds under complete spatial randomness (M.A. Mugglestone, S.A. Harding, B.Y.Y. Lee, P.J. Diggle & B.S. Rowlingson).

### Option

`PRINT` = string tokens What to print (`summary`, `monitoring`); default `summ`, `moni`

### Parameters

`YPOLYGON` = variates Vertical coordinates of each polygon; no default – this parameter must be set Horizontal coordinates of each polygon; no default – this parameter must be set How many points to generate in each simulation; no default – this parameter must be set How many simulations of CSR to use; no default – this parameter must be set Vectors of distances to use; no default – this parameter must be set Variates to receive the values of the lower bound of the K function Variates to receive the values of the upper bound of the K function Seeds for the random numbers used in the simulations; default 0

### Description

The K function, or reduced second-order moment function, relates to the distribution of the inter-event distances between all ordered pairs of events in a spatial point pattern (see Diggle 1983). The term complete spatial randomness (CSR) is used to represent the hypothesis that the overall density of events in a spatial point pattern is constant throughout the study region, and that the events are distributed independently and uniformly.

The K function for a completely random pattern is given by

K(s) = π × s2 .

(The K function for a clustered (regular) pattern will tend to be larger (smaller) than the values given by the above expression, at least for small distances.) The procedure `KHAT` can be used to obtain an approximately unbiased estimate of K(s) for an observed pattern which can be compared with the expected value under CSR given by the above expression. However, the variance of the estimate under the null hypothesis cannot be expressed in closed form, and so critical values for the estimated K function cannot be obtained analytically. This problem can be overcome by repeatedly simulating from the null hypothesis and estimating the K function for each simulated pattern. If `NSIMULATIONS` denotes the number of simulations used, then, for each value of s, the minimum (maximum) value of the estimated K function provides an approximate 100/(`NSIMULATIONS`+1) percent lower (upper) critical value for K(s).

The procedure `KCSRENVELOPES` computes lower and upper bounds (envelopes) for the K function under CSR. The data required by the procedure are the coordinates of a polygon in which to simulate CSR (specified by the parameters `XPOLYGON` and `YPOLYGON`), the number of points to generate in each simulation (specified using the parameter `NPOINTS`), the number of simulations to use (specified by the parameter `NSIMULATIONS`) and a vector of distances at which to calculate the EDF of K (specified by the parameter `S`). The `SEED` parameter allows a seed to be supplied for generating the random numbers for the simulations (thereby producing reproducible results). If this is not supplied, the default of 0 initializes the random number generator (if necessary) from the system clock. The output of the procedure consists of two vectors, the first containing the minimum value obtained for K(s) for each distance in `S`, and the second containing the corresponding maximum values. The minimum and maximum values of the K function can be saved using the parameters `KLOWER` and `KUPPER`.

Printed output is controlled using the `PRINT` option. The settings available are `monitoring` (which prints a message to mark the start of each simulation) and `summary` (which prints the distances at which the K function is estimated under the heading `S`, together with the lower and upper bounds for the K function under the headings `KLOWER` and `KUPPER`).

Option: `PRINT`.

Parameters: `YPOLYGON`, `XPOLYGON`, `NPOINTS`, `NSIMULATIONS`, `S`, `KLOWER`, `KUPPER`, `SEED`.

### Method

A procedure `PTCHECKXY` is used to check that `XPOLYGON` and `YPOLYGON` have identical restrictions. The `SORT `function is then used to create a variate containing the distances in `S` arranged in ascending order. (The original variate is left unchanged.) The procedures `GRCSR` and `KHAT` are called `NSIMULATIONS` times to calculate estimates of the K function under CSR. Finally, the `VMINIMA` and `VMAXIMA` functions are used to calculate the minimum and maximum values of the K function for each distance in `S`.

### Action with `RESTRICT`

If `XPOLYGON` and `YPOLYGON` are restricted, only the subset of values specified by the restriction will be included in the calculations. The parameter `S` may also be restricted.

### Reference

Diggle, P.J. (1983). Statistical Analysis of Spatial Point Patterns. Academic Press, London.

Procedures: `FHAT`, `GHAT`, `KHAT`, `KLABENVELOPES`, `KSED`, `KSTHAT`, `KSTSE`, `K12HAT`.

Commands for: Spatial statistics.

### Example

```CAPTION 'KCSRENVELOPES example'; STYLE=meta
VARIATE pinex,piney
0.09 0.91   0.02 0.71   0.03 0.62   0.18 0.61   0.03 0.52
0.02 0.41   0.16 0.35   0.13 0.33   0.13 0.27   0.03 0.21
0.13 0.14   0.08 0.11   0.02 0.02   0.18 0.98   0.31 0.89
0.22 0.58   0.13 0.52   0.21 0.38   0.23 0.27   0.23 0.11
0.41 0.98   0.44 0.97   0.42 0.93   0.42 0.48   0.43 0.36
0.59 0.92   0.63 0.92   0.63 0.88   0.66 0.88   0.58 0.83
0.53 0.69   0.52 0.68   0.49 0.58   0.52 0.48   0.52 0.09
0.58 0.06   0.68 0.66   0.68 0.63   0.67 0.53   0.67 0.48
0.67 0.41   0.68 0.34   0.66 0.24   0.73 0.27   0.74 0.11
0.78 0.06   0.79 0.02   0.86 0.03   0.84 0.88   0.94 0.89
0.95 0.83   0.79 0.79   0.84 0.71   0.83 0.68   0.86 0.65
0.79 0.61   0.93 0.48   0.83 0.42   0.93 0.31   0.93 0.23
0.97 0.64   0.96 0.64   0.96 0.61   0.96 0.57   0.97 0.38  :
VARIATE xpoly; VALUES=!(0,1,1,0)
&       ypoly; VALUES=!(0,0,1,1)
&       s; VALUES=!(0.01,0.02...0.1)
KHAT    [PRINT=*] Y=piney; X=pinex; YPOLYGON=ypoly; XPOLYGON=xpoly;\
S=s; KVALUES=kpines
KCSRENVELOPES [PRINT=monitoring] YPOLYGON=ypoly; XPOLYGON=xpoly;\
NPOINTS=65; NSIMULATIONS=19; S=s; KLOWER=mincsr; KUPPER=maxcsr;\
SEED=741342
PRINT   s,kpines,mincsr,maxcsr
```
Updated on March 7, 2019