Performs a random toroidal shift on a spatial point pattern (M.A. Mugglestone, S.A. Harding, B.Y.Y. Lee, P.J. Diggle & B.S. Rowlingson).
Option
PRINT = string token |
What to print (summary ); default summ |
---|
Parameters
OLDY = variates |
Vertical coordinates of each spatial point pattern; no default – this parameter must be set |
---|---|
OLDX = variates |
Horizontal coordinates of each spatial point pattern; no default – this parameter must be set |
YBOX = variates |
Vertical coordinates of the toroidal regions |
XBOX = variates |
Horizontal coordinates of the toroidal regions |
NEWY = variates |
Variates to receive the vertical coordinates of the randomly shifted patterns |
NEWX = variates |
Variates to receive the horizontal coordinates of the randomly shifted patterns |
SEED = scalars |
Seeds for the random numbers used to perform the shifts; default 0 |
Description
A simple shift of a spatial point pattern is obtained by applying constant horizontal and vertical displacements to every event in the pattern. Although the pattern itself is translated, its internal structure is preserved. In a random shift, the vertical and horizontal displacements are obtained using a pseudo-random number generator.
Applying a random shift to a spatial point pattern contained in a polygonal study region may move some of the events outside the polygon. If the polygon is a rectangle, then events which are moved outside can be mapped onto the rectangle by assuming that the pattern repeats periodically at the scale of the rectangle. This may be achieved by wrapping the rectangle on a torus, so that the top edge is connected to the bottom edge, and the left-hand edge to the right-hand edge. An event which moves beyond the right-hand boundary will re-enter from the left, and so on. This process is termed toroidal edge-correction.
The procedure GRTORSHIFT
performs a random toroidal shift on a spatial point pattern given the coordinates of the pattern (specified using the OLDX
and OLDY
parameters) and the coordinates of a rectangle on which the shift is to be performed (specified using the XBOX
and YBOX
parameters). The default values of XBOX
and YBOX
are the coordinates of the bounding box of the spatial point pattern (see the procedure PTBOX
). The coordinates of the shifted pattern can be saved using the parameters NEWX
and NEWY
. The SEED
parameter allows a seed to be supplied for generating the random numbers used to perform the random shift (thereby producing reproducible results). If this is not supplied, the default of 0 initializes the random number generator (if necessary) from the system clock.
Printed output is controlled using the PRINT
option. The default setting of summary prints the coordinates of the shifted pattern under the headings NEWX
and NEWY
.
Option: PRINT
.
Parameters: OLDY
, OLDX
, YBOX
, XBOX
, NEWY
, NEWX
, SEED
.
Method
A procedure PTCHECKXY
is used to check that OLDX
and OLDY
have identical restrictions. If either XBOX
or YBOX
is unset, the procedure PTBOX
is then used to assign the corresponding coordinates of the bounding box for the point pattern specified by OLDX
and OLDY
(any values supplied for XBOX
and YBOX
will remain unchanged). PTCHECKXY
is then used to check that XBOX
and YBOX
have identical restrictions. The URAND
function is then used to generate the horizontal and vertical displacements. The coordinates of the pattern and the horizontal and vertical displacements are passed to a sub-procedure (TORSHIFT
) which performs the toroidal shift.
Action with RESTRICT
If OLDX
and OLDY
are restricted, only the subset of values specified by the restriction will be included in the calculations. XBOX
and YBOX
may also be restricted, as long as the same restrictions apply to both parameters.
See also
Procedures: GRCSR
, GRLABEL
, GRTHIN
.
Commands for: Calculations and manipulation, Spatial statistics.
Example
CAPTION 'GRTORSHIFT example'; STYLE=meta VARIATE oldx; VALUES=!( 3, 4, 4, 5, 5, 6, 6, 7,\ 4, 5, 6, 6, 6, 6, 7, 8,\ 14,14,15,15,16,16,17,17) & oldy; VALUES=!( 2, 2, 3, 3, 4, 4, 5, 5,\ 16,16,14,15,17,18,16,16,\ 10,11, 9,12, 9,12,10,11) & xbox; VALUES=!( 0,20,20, 0) & ybox; VALUES=!( 0, 0,20,20) GRTORSHIFT [PRINT=*] OLDY=oldy; OLDX=oldx; YBOX=ybox;\ XBOX=xbox; NEWY=newy; NEWX=newx; SEED=911437 DPTMAP [YLOWER=0; YUPPER=20; XLOWER=0; XUPPER=20]\ Y=oldy,newy; X=oldx,newx