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