1. Home
  2. 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).


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


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


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.



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.


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

See also


Commands for: Spatial statistics.


VARIATE pinex,piney
READ    [SETNVALUES=yes] 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
        NPOINTS=65; NSIMULATIONS=19; S=s; KLOWER=mincsr; KUPPER=maxcsr;\ 
PRINT   s,kpines,mincsr,maxcsr
Updated on March 7, 2019

Was this article helpful?