Set Control Parameters for Metropolis-Hastings Algorithm.

Description

Sets up a list of parameters controlling the iterative behaviour of the Metropolis-Hastings algorithm.

Usage

   rmhcontrol(control, ...)
   ## Default S3 method:
   rmhcontrol(control=NULL, ..., p=0.9, q=0.5, nrep=5e5,
                      expand=NULL, periodic=FALSE, ptypes=NULL,
                      fixall=FALSE, nverb=0)

Arguments

Details

The Metropolis-Hastings algorithm, implemented as rmh, generates simulated realisations of point process models. This function rmhcontrol sets up a list of parameters which control the iterative behaviour and termination of the Metropolis-Hastings algorithm, for use in a subsequent call to rmh. It also checks that the parameters are valid.

(A separate function rmhstart determines the initial state of the algorithm, and rmhmodel determines the model to be simulated.)

The algorithm control parameters should be specified either by the first argument control or by the other arguments p, q etc.

If control is specified, it may be a list of parameter values (with components named p, q etc, having the same interpretation as described below) or an object of class "rmhcontrol" obtained by a previous call to rmhcontrol.

The parameters are as follows:

p

The probability of proposing a ``shift'' (as opposed to a birth or death) in the Metropolis-Hastings algorithm.

If p = 1 then the algorithm only alters existing points, so the number of points never changes, i.e. we are simulating conditionally upon the number of points. The number of points is determined by the initial state (specified by rmhstart).

If p=1 and fixall=TRUE and the model is a multitype point process model, then the algorithm only shifts the locations of existing points and does not alter their marks (types). This is equivalent to simulating conditionally upon the number of points of each type. These numbers are again specified by the initial state.

If p = 1 then no expansion of the simulation window is allowed (see expand below).

q

The conditional probability of proposing a death (rather than a birth) given that a shift is not proposed. This is of course ignored if p is equal to 1.

nrep

The number of repetitions or iterations to be made by the Metropolis-Hastings algorithm. It should be large.

expand

Either a numerical expansion factor, or a window (object of class "owin"). Indicates that the process is to be simulated on a larger domain than the original data window w, then clipped to w when the algorithm has finished. This would often be done in order to approximate the simulation of a stationary process (Geyer, 1999) or more generally a process existing in the whole plane, rather than just in the window w.

If expand is a window object, it is taken as the larger domain in which simulation is performed. If expand is numeric, it is interpreted as the factor by which the area of the enclosing box of the window w is to be expanded (i.e. width and height are stretched by the same factor sqrt(area)). The expansion is computed by the function expand.owin.

If expand equals 1 then no expansion is performed. Any value of expand smaller than 1 is ignored and treated as 1.

Expansion is not permitted if the number of points has been fixed by setting p = 1 or if the starting configuration has been specified via the argument x.start in rmhstart. In these cases expand defaults to 1.

Otherwise, expand defaults to 2.

periodic

A logical scalar; if periodic is TRUE we simulate a process on the torus formed by identifying opposite edges of a rectangular window. This window could be the ``original'' window if that window is rectangular, or the bounding box of that window, or an expansion of the bounding box (when expand is greater than 1). In the latter two cases the simulated pattern is clipped to the original window.

ptypes

A vector of probabilities (summing to 1) to be used in assigning a random type to a new point. Defaults to a vector each of whose entries is 1/nt where nt is the number of types for the process. Convergence of the simulation algorithm should be improved if ptypes is close to the relative frequencies of the types which will result from the simulation.

fixall

A logical scalar specifying whether to condition on the number of points of each type. Meaningful only if a marked process is being simulated, and if p = 1. A warning message is given if fixall is set equal to TRUE when it is not meaningful.

nverb

An integer specifying how often ``progress reports'' (which consist simply of the number of repetitions completed) should be printed out. If nverb is left at 0, the default, the simulation proceeds silently.

Value

An object of class "rmhcontrol", which is essentially a list of parameter values for the algorithm.
There is a print method for this class, which prints a sensible description of the parameters chosen.

Author(s)

Adrian Baddeley adrian@maths.uwa.edu.au http://www.maths.uwa.edu.au/~adrian/ and Rolf Turner rolf@math.unb.ca http://www.math.unb.ca/~rolf

References

Geyer, C.J. (1999) Likelihood Inference for Spatial Point Processes. Chapter 3 in O.E. Barndorff-Nielsen, W.S. Kendall and M.N.M. Van Lieshout (eds) Stochastic Geometry: Likelihood and Computation, Chapman and Hall / CRC, Monographs on Statistics and Applied Probability, number 80. Pages 79–140.

See Also

rmh, rmhmodel, rmhstart, expand.owin

Examples

   # parameters given as named arguments
   c1 <- rmhcontrol(p=0.3,periodic=TRUE,nrep=1e6,nverb=1e5)

   # parameters given as a list
   liz <- list(p=0.9, nrep=1e4)
   c2 <- rmhcontrol(liz)

   # parameters given in rmhcontrol object
   c3 <- rmhcontrol(c1)