rmhcontrol             package:spatstat             R Documentation

_S_e_t _C_o_n_t_r_o_l _P_a_r_a_m_e_t_e_r_s _f_o_r _M_e_t_r_o_p_o_l_i_s-_H_a_s_t_i_n_g_s _A_l_g_o_r_i_t_h_m.

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

 control: An existing list of control parameters in some other format.
          Incompatible with the arguments listed below. 

     ...: There should be no other arguments.

       p: Probability of proposing a shift (as against a birth/death)

       q: Conditional probability of proposing a death given that a
          birth or death will be proposed

    nrep: Total number of steps (proposals) of Metropolis-Hastings
          algorithm that should be run

  expand: Either a numerical expansion factor, or a window (object of
          class '"owin"'), specifying that simulations are to be
          performed in a domain larger than the original data window,
          then clipped to the original data window. 

periodic: (Logical) whether to simulate ``periodically'', i.e. on a
          torus formed by identifying opposite edges of a rectangle.

  ptypes: For multitype point processes, the distribution of the mark
          attached to a new random point (when a birth is proposed)

  fixall: (Logical) for multitype point processes, whether to fix the
          number of points of each type.

   nverb: Progress reports will be printed every 'nverb' iterations

_D_e_t_a_i_l_s:

     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.

     _n_r_e_p The number of repetitions or iterations  to be made by the
          Metropolis-Hastings algorithm.  It should be large.

     _e_x_p_a_n_d 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.

     _p_e_r_i_o_d_i_c 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.

     _p_t_y_p_e_s 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.

     _f_i_x_a_l_l 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.

     _n_v_e_r_b 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.

_V_a_l_u_e:

     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.

_A_u_t_h_o_r(_s):

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

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

     'rmh', 'rmhmodel', 'rmhstart', 'expand.owin'

_E_x_a_m_p_l_e_s:

        # 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)

