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