R: Build Point Process Model for Metropolis-Hastings Simulation.

rmhmodel.default {spatstat.core} | R Documentation

## Build Point Process Model for Metropolis-Hastings Simulation.

### Description

Builds a description of a point process model for use in simulating the model by the Metropolis-Hastings algorithm.

### Usage

      ## Default S3 method:
    rmhmodel(...,
             cif=NULL, par=NULL, w=NULL, trend=NULL, types=NULL)

### Arguments

`...` | Ignored.
`cif` | Character string specifying the choice of model
`par` | Parameters of the model
`w` | Spatial window in which to simulate
`trend` | Specification of the trend in the model
`types` | A vector of factor levels defining the possible marks, for a multitype process.

### Details

The generic function `rmhmodel` takes a description of a point process model in some format, and converts it into an object of class `"rmhmodel"` so that simulations of the model can be generated using the Metropolis-Hastings algorithm `rmh`.

This function `rmhmodel.default` is the default method. It builds a description of the point process model from the simple arguments listed.

The argument `cif` is a character string specifying the choice of interpoint interaction for the point process. The current options are

`'areaint'`

  Area-interaction process.

`'badgey'`

  Baddeley-Geyer (hybrid Geyer) process.

`'dgs'`

  Diggle, Gates and Stibbard (1987) process

`'diggra'`

  Diggle and Gratton (1984) process

`'fiksel'`

  Fiksel double exponential process (Fiksel, 1984).

`'geyer'`

  Saturation process (Geyer, 1999).

`'hardcore'`

  Hard core process

`'lennard'`

  Lennard-Jones process

`'lookup'`

  General isotropic pairwise interaction process, with the interaction function specified via a “lookup table”.

`'multihard'`

  Multitype hardcore process

`'penttinen'`

  The Penttinen process

`'strauss'`

  The Strauss process

`'straush'`

  The Strauss process with hard core

`'sftcr'`

  The Softcore process

`'straussm'`

  The multitype Strauss process

`'straushm'`

  Multitype Strauss process with hard core

`'triplets'`

  Triplets process (Geyer, 1999).

It is also possible to specify a hybrid of these interactions in the sense of Baddeley et al (2013). In this case, `cif` is a character vector containing names from the list above. For example, `cif=c('strauss', 'geyer')` would specify a hybrid of the Strauss and Geyer models.

The argument `par` supplies parameter values appropriate to the conditional intensity function being invoked. For the interactions listed above, these parameters are:

areaint:

  (Area-interaction process.) A named list with components `beta,eta,r` which are respectively the “base” intensity, the scaled interaction parameter and the interaction radius.

badgey:

  (Baddeley-Geyer process.) A named list with components `beta` (the “base” intensity), `gamma` (a vector of non-negative interaction parameters), `r` (a vector of interaction radii, of the same length as `gamma`, in increasing order), and `sat` (the saturation parameter(s); this may be a scalar, or a vector of the same length as `gamma` and `r`; all values should be at least 1). Note that because of the presence of “saturation” the `gamma` values are permitted to be larger than 1.

dgs:

  (Diggle, Gates, and Stibbard process. See Diggle, Gates, and Stibbard (1987)) A named list with components `beta` and `rho`. This process has pairwise interaction function equal to

  e(t) = sin^2((pi * t)/(2 * rho))

  for t < rho, and equal to 1 for t >= rho.

diggra:

  (Diggle-Gratton process. See Diggle and Gratton (1984) and Diggle, Gates and Stibbard (1987).) A named list with components `beta`, `kappa`, `delta` and `rho`. This process has pairwise interaction function e(t) equal to 0 for t < delta, equal to

  ((t-delta)/(rho-delta))^kappa

  for delta <= t < rho, and equal to 1 for t >= rho. Note that here we use the symbol kappa where Diggle, Gates, and Stibbard use beta since we reserve the symbol beta for an intensity parameter.

fiksel:

  (Fiksel double exponential process, see Fiksel (1984)) A named list with components `beta`, `r`, `hc`, `kappa` and `a`. This process has pairwise interaction function e(t) equal to 0 for t < hc, equal to

  exp(a * exp( - kappa * t))

  for hc <= t < r, and equal to 1 for t >= r.

geyer:

  (Geyer's saturation process. See Geyer (1999).) A named list with components `beta`, `gamma`, `r`, and `sat`. The components `beta`, `gamma`, `r` are as for the Strauss model, and `sat` is the “saturation” parameter. The model is Geyer's “saturation” point process model, a modification of the Strauss process in which we effectively impose an upper limit (`sat`) on the number of neighbours which will be counted as close to a given point.

  Explicitly, a saturation point process with interaction radius r, saturation threshold s, and parameters beta and gamma, is the point process in which each point x[i] in the pattern X contributes a factor

  beta gamma^min(s,t(x[i],X))

  to the probability density of the point pattern, where t(x[i],X) denotes the number of “r-close neighbours” of x[i] in the pattern X.

  If the saturation threshold s is infinite, the Geyer process reduces to a Strauss process with interaction parameter gamma^2 rather than gamma.

hardcore:

  (Hard core process.) A named list with components `beta` and `hc` where `beta` is the base intensity and `hc` is the hard core distance. This process has pairwise interaction function e(t) equal to 1 if t > hc and 0 if t <= hc.

lennard:

  (Lennard-Jones process.) A named list with components `sigma` and `epsilon`, where `sigma` is the characteristic diameter and `epsilon` is the well depth. See `LennardJones` for explanation.

multihard:

  (Multitype hard core process.) A named list with components `beta` and `hradii`, where `beta` is a vector of base intensities for each type of point, and `hradii` is a matrix of hard core radii between each pair of types.

penttinen:

  (Penttinen process.) A named list with components `beta,gamma,r` which are respectively the “base” intensity, the pairwise interaction parameter, and the disc radius. Note that `gamma` must be less than or equal to 1. See `Penttinen` for explanation. (Note that there is also an algorithm for perfect simulation of the Penttinen process, `rPenttinen`)

strauss:

  (Strauss process.) A named list with components `beta,gamma,r` which are respectively the “base” intensity, the pairwise interaction parameter and the interaction radius. Note that `gamma` must be less than or equal to 1. (Note that there is also an algorithm for perfect simulation of the Strauss process, `rStrauss`)

straush:

  (Strauss process with hardcore.) A named list with entries `beta,gamma,r,hc` where `beta`, `gamma`, and `r` are as for the Strauss process, and `hc` is the hardcore radius. Of course `hc` must be less than `r`.

sftcr:

  (Softcore process.) A named list with components `beta,sigma,kappa`. Again `beta` is a “base” intensity. The pairwise interaction between two points u != v is

  -(sigma/||u-v||)^(2/kappa)

  Note that it is necessary that 0 < kappa <1.

straussm:

  (Multitype Strauss process.) A named list with components

  - `beta`: A vector of “base” intensities, one for each possible type.

  - `gamma`: A symmetric matrix of interaction parameters, with gamma_ij pertaining to the interaction between type i and type j.

  - `radii`: A symmetric matrix of interaction radii, with entries r_ij pertaining to the interaction between type i and type j.

straushm:

  (Multitype Strauss process with hardcore.) A named list with components `beta` and `gamma` as for `straussm` and two “radii” components:

  - `iradii`: the interaction radii

  - `hradii`: the hardcore radii

  which are both symmetric matrices of nonnegative numbers. The entries of `hradii` must be less than the corresponding entries of `iradii`.

triplets:

  (Triplets process.) A named list with components `beta,gamma,r` which are respectively the “base” intensity, the triplet interaction parameter and the interaction radius. Note that `gamma` must be less than or equal to 1.

lookup:

  (Arbitrary pairwise interaction process with isotropic interaction.) A named list with components `beta`, `r`, and `h`, or just with components `beta` and `h`.

  This model is the pairwise interaction process with an isotropic interaction given by any chosen function H. Each pair of points x[i], x[j] in the point pattern contributes a factor H(d(x[i],x[j])) to the probability density, where d denotes distance and H is the pair interaction function.

  The component `beta` is a (positive) scalar which determines the “base” intensity of the process.

  In this implementation, H must be a step function. It is specified by the user in one of two ways.

  - as a vector of values: If `r` is present, then `r` is assumed to give the locations of jumps in the function H, while the vector `h` gives the corresponding values of the function.

    Specifically, the interaction function H(t) takes the value `h[1]` for distances t in the interval `[0, r[1])`; takes the value `h[i]` for distances t in the interval `[r[i-1], r[i])` where i = 2, ..., n; and takes the value 1 for t >= r[n]. Here n denotes the length of `r`.

    The components `r` and `h` must be numeric vectors of equal length. The `r` values must be strictly positive, and sorted in increasing order.

    The entries of `h` must be non-negative. If any entry of `h` is greater than 1, then the entry `h[1]` must be 0 (otherwise the specified process is non-existent).

    Greatest efficiency is achieved if the values of `r` are equally spaced.

    [Note: The usage of `r` and `h` has changed from the previous usage in spatstat versions 1.4-7 to 1.5-1, in which ascending order was not required, and in which the first entry of `r` had to be 0.]

  - as a stepfun object: If `r` is absent, then `h` must be an object of class `"stepfun"` specifying a step function. Such objects are created by `stepfun`.

    The stepfun object `h` must be right-continuous (which is the default using `stepfun`.)

    The values of the step function must all be nonnegative. The values must all be less than 1 unless the function is identically zero on some initial interval [0,r). The rightmost value (the value of `h(t)` for large `t`) must be equal to 1.

    Greatest efficiency is achieved if the jumps (the “knots” of the step function) are equally spaced.

For a hybrid model, the argument `par` should be a list, of the same length as `cif`, such that `par[[i]]` is a list of the parameters required for the interaction `cif[i]`. See the Examples.

The optional argument `trend` determines the spatial trend in the model, if it has one. It should be a function or image (or a list of such, if the model is multitype) to provide the value of the trend at an arbitrary point.

trend given as a function:

  A trend function may be a function of any number of arguments, but the first two must be the x,y coordinates of a point. Auxiliary arguments may be passed to the `trend` function at the time of simulation, via the `...` argument to `rmh`.

  The function must be vectorized. That is, it must be capable of accepting vector valued `x` and `y` arguments. Put another way, it must be capable of calculating the trend value at a number of points, simultaneously, and should return the vector of corresponding trend values.

trend given as an image:

  An image (see `im.object`) provides the trend values at a grid of points in the observation window and determines the trend value at other points as the value at the nearest grid point.

Note that the trend or trends must be non-negative; no checking is done for this.

The optional argument `w` specifies the window in which the pattern is to be generated. If specified, it must be in a form which can be coerced to an object of class `owin` by `as.owin`.

The optional argument `types` specifies the possible types in a multitype point process. If the model being simulated is multitype, and `types` is not specified, then this vector defaults to `1:ntypes` where `ntypes` is the number of types.

### Value

An object of class `"rmhmodel"`, which is essentially a list of parameter values for the model.

There is a `print` method for this class, which prints a sensible description of the model chosen.

### Warnings in Respect of “lookup”

For the `lookup` cif, the entries of the `r` component of `par` must be strictly positive and sorted into ascending order.

Note that if you specify the `lookup` pairwise interaction function via `stepfun()` the arguments `x` and `y` which are passed to `stepfun()` are slightly different from `r` and `h`: `length(y)` is equal to `1+length(x)`; the final entry of `y` must be equal to 1 — i.e. this value is explicitly supplied by the user rather than getting tacked on internally.

The step function returned by `stepfun()` must be right continuous (this is the default behaviour of `stepfun()`) otherwise an error is given.

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Rolf Turner r.turner@auckland.ac.nz

### References

Baddeley, A., Turner, R., Mateu, J. and Bevan, A. (2013) Hybrids of Gibbs point process models and their implementation. Journal of Statistical Software 55:11, 1–43. https://www.jstatsoft.org/v55/i11/

Diggle, P. J. (2003) Statistical Analysis of Spatial Point Patterns (2nd ed.) Arnold, London.

Diggle, P.J. and Gratton, R.J. (1984) Monte Carlo methods of inference for implicit statistical models. Journal of the Royal Statistical Society, series B 46, 193 – 212.

Diggle, P.J., Gates, D.J., and Stibbard, A. (1987) A nonparametric estimator for pairwise-interaction point processes. Biometrika 74, 763 – 770. Scandinavian Journal of Statistics 21, 359–373.

Fiksel, T. (1984) Estimation of parameterized pair potentials of marked and non-marked Gibbsian point processes. Electronische Informationsverabeitung und Kybernetika 20, 270–278.

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`, `rmhcontrol`, `rmhstart`, `ppm`, `AreaInter`, `BadGey`, `DiggleGatesStibbard`, `DiggleGratton`, `Fiksel`, `Geyer`, `Hardcore`, `Hybrid`, `LennardJones`, `MultiStrauss`, `MultiStraussHard`, `PairPiece`, `Penttinen`, `Poisson`, `Softcore`, `Strauss`, `StraussHard` and `Triplets`.

### Examples

       # Strauss process:
       mod01 <- rmhmodel(cif="strauss",par=list(beta=2,gamma=0.2,r=0.7),
                     w=c(0,10,0,10))
       mod01
       # The above could also be simulated using 'rStrauss'

       # Strauss with hardcore:
       mod04 <- rmhmodel(cif="straush",par=list(beta=2,gamma=0.2,r=0.7,hc=0.3),
                    w=owin(c(0,10),c(0,5)))

       # Hard core:
       mod05 <- rmhmodel(cif="hardcore",par=list(beta=2,hc=0.3),
                  w=square(5))

       # Soft core:
       w    <- square(10)
       mod07 <- rmhmodel(cif="sftcr",
                         par=list(beta=0.8,sigma=0.1,kappa=0.5),
                         w=w)

       # Penttinen process:
       modpen <- rmhmodel(cif="penttinen",par=list(beta=2,gamma=0.6,r=1),
                     w=c(0,10,0,10))

       # Area-interaction process:
       mod42 <- rmhmodel(cif="areaint",par=list(beta=2,eta=1.6,r=0.7),
                     w=c(0,10,0,10))

       # Baddeley-Geyer process:
       mod99 <- rmhmodel(cif="badgey",par=list(beta=0.3,
                         gamma=c(0.2,1.8,2.4),r=c(0.035,0.07,0.14),sat=5),
                         w=unit.square())

       # Multitype Strauss:
       beta <- c(0.027,0.008)
       gmma <- matrix(c(0.43,0.98,0.98,0.36),2,2)
       r    <- matrix(c(45,45,45,45),2,2)
       mod08 <- rmhmodel(cif="straussm",
                         par=list(beta=beta,gamma=gmma,radii=r),
                         w=square(250))
       # specify types
       mod09 <- rmhmodel(cif="straussm",
                         par=list(beta=beta,gamma=gmma,radii=r),
                         w=square(250),
                         types=c("A", "B"))

       # Multitype Hardcore:
       rhc  <- matrix(c(9.1,5.0,5.0,2.5),2,2)
       mod08hard <- rmhmodel(cif="multihard",
                         par=list(beta=beta,hradii=rhc),
                         w=square(250),
                         types=c("A", "B"))

       # Multitype Strauss hardcore with trends for each type:
       beta  <- c(0.27,0.08)
       ri    <- matrix(c(45,45,45,45),2,2)
       rhc  <- matrix(c(9.1,5.0,5.0,2.5),2,2)
       tr3   <- function(x,y){x <- x/250; y <- y/250;
       			   exp((6*x + 5*y - 18*x^2 + 12*x*y - 9*y^2)/6)
                             }
                             # log quadratic trend
       tr4   <- function(x,y){x <- x/250; y <- y/250;
                             exp(-0.6*x+0.5*y)}
                            # log linear trend
       mod10 <- rmhmodel(cif="straushm",par=list(beta=beta,gamma=gmma,
                     iradii=ri,hradii=rhc),w=c(0,250,0,250),
                     trend=list(tr3,tr4))

       # Triplets process:
       mod11 <- rmhmodel(cif="triplets",par=list(beta=2,gamma=0.2,r=0.7),
                     w=c(0,10,0,10))

       # Lookup (interaction function h_2 from page 76, Diggle (2003)):
          r <- seq(from=0,to=0.2,length=101)[-1] # Drop 0.
          h <- 20*(r-0.05)
          h[r<0.05] <- 0
          h[r>0.10] <- 1
          mod17 <- rmhmodel(cif="lookup",par=list(beta=4000,h=h,r=r),w=c(0,1,0,1))

      # hybrid model
      modhy <- rmhmodel(cif=c('strauss', 'geyer'),
                        par=list(list(beta=100,gamma=0.5,r=0.05),
                                 list(beta=1, gamma=0.7,r=0.1, sat=2)),
                        w=square(1))
      modhy

[Package spatstat.core version 1.65-5 Index]