rmhcontrol {spatstat} | R Documentation |
Sets up a list of parameters controlling the iterative behaviour of the Metropolis-Hastings algorithm.
rmhcontrol(...) ## Default S3 method: rmhcontrol(..., p=0.9, q=0.5, nrep=5e5, expand=NULL, periodic=FALSE, ptypes=NULL, x.cond=NULL, fixall=FALSE, nverb=0)
... |
Arguments passed to methods. |
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 |
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) |
x.cond |
Conditioning points for conditional simulation. |
fixall |
(Logical) for multitype point processes, whether to fix the number of points of each type. |
nverb |
Progress reports will be printed every |
The Metropolis-Hastings algorithm, implemented as rmh
,
generates simulated realisations of point process models.
The 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 parameters are as follows:
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).
The default value of p
can be changed by setting
the parameter rmh.p
in spatstat.options
.
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.
The default value of q
can be changed by setting
the parameter rmh.q
in spatstat.options
.
The number of repetitions or iterations to be made by the Metropolis-Hastings algorithm. It should be large.
The default value of nrep
can be changed by setting
the parameter rmh.nrep
in spatstat.options
.
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
spatstat.options("expand")
which defaults to 2.
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.
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.
If this argument is given,
then conditional simulation will be performed,
and x.cond
specifies the location of the
fixed points as well as the type of conditioning.
It should be either a point pattern
(object of class "ppp"
) or a list(x,y)
or a data.frame
.
See the section on Conditional Simulation.
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.
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.
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.
For a Gibbs point process X, the Metropolis-Hastings algorithm easily accommodates several kinds of conditional simulation:
We fix the total number of points N(X) to be equal to n. We simulate from the conditional distribution of X given N(X) = n.
In a multitype point process, where Y[[j]] denotes the process of points of type j, we fix the number N(Y[[j]]) of points of type j to be equal to n[j], for j=1,2,...,m. We simulate from the conditional distribution of X given N(Y[[j]]) = n[j] for j=1,2,...,m.
We require that the point process X should, within a specified sub-window V, coincide with a specified point pattern y. We simulate from the conditional distribution of X given (X intersect V) = y.
We require that the point process X include a specified list of points y. We simulate from the point process with probability density g(x) = c * f(x union y) where f is the probability density of the original process X, and c is a normalising constant.
To achieve each of these types of conditioning we do as follows:
Set p=1
.
The number of points is determined by the initial state
of the simulation: see rmhstart
.
Set p=1
and fixall=TRUE
.
The number of points of each type is determined by the initial state
of the simulation: see rmhstart
.
Set x.cond
to be a point pattern (object of
class "ppp"
). Its window V=x.cond$window
becomes the
conditioning subwindow V.
Set x.cond
to be a list(x,y)
or data.frame
with two columns containing the coordinates of the points, or a
list(x,y,marks)
or data.frame
with three columns
containing the coordinates and marks of the points.
The arguments x.cond
, p
and fixall
can be
combined.
Adrian Baddeley Adrian.Baddeley@csiro.au http://www.maths.uwa.edu.au/~adrian/ and Rolf Turner r.turner@auckland.ac.nz
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.
rmh
,
rmhmodel
,
rmhstart
,
expand.owin
,
spatstat.options
# 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)