mincontrast: Method of Minimum Contrast

In spatstat.core: Core Functionality of the 'spatstat' Family

Method of Minimum Contrast

Description

A general low-level algorithm for fitting theoretical point process models to point pattern data by the Method of Minimum Contrast.

Usage

mincontrast(observed, theoretical, startpar, ...,
          ctrl=list(q = 1/4, p = 2, rmin=NULL, rmax=NULL),
          fvlab=list(label=NULL, desc="minimum contrast fit"),
          explain=list(dataname=NULL, modelname=NULL, fname=NULL),
          action.bad.values=c("warn", "stop", "silent"),
          control=list(), stabilize=TRUE,
          pspace=NULL)

Arguments

observed	Summary statistic, computed for the data. An object of class "fv".
theoretical	An R language function that calculates the theoretical expected value of the summary statistic, given the model parameters. See Details.
startpar	Vector of initial values of the parameters of the point process model (passed to theoretical).
...	Additional arguments passed to the function theoretical and to the optimisation algorithm optim.
ctrl	Optional. List of arguments controlling the optimisation. See Details.
fvlab	Optional. List containing some labels for the return value. See Details.
explain	Optional. List containing strings that give a human-readable description of the model, the data and the summary statistic.
action.bad.values	String (partially matched) specifying what to do if values of the summary statistic are NA, NaN or infinite. See Details.
control	Optional. Argument passed to optim. A list of parameters which control the behaviour of the optimization algorithm.
stabilize	Logical value specifying whether to numerically stabilize the optimization algorithm, by specifying suitable default values of control$fnscale and control$parscale.
pspace	For internal use by the package only.

Details

This function is a general algorithm for fitting point process models by the Method of Minimum Contrast. If you want to fit the Thomas process, see thomas.estK. If you want to fit a log-Gaussian Cox process, see lgcp.estK. If you want to fit the \Matern cluster process, see matclust.estK.

The Method of Minimum Contrast (Pfanzagl, 1969; Diggle and Gratton, 1984) is a general technique for fitting a point process model to point pattern data. First a summary function (typically the K function) is computed from the data point pattern. Second, the theoretical expected value of this summary statistic under the point process model is derived (if possible, as an algebraic expression involving the parameters of the model) or estimated from simulations of the model. Then the model is fitted by finding the optimal parameter values for the model to give the closest match between the theoretical and empirical curves.

The argument observed should be an object of class "fv" (see fv.object) containing the values of a summary statistic computed from the data point pattern. Usually this is the function K(r) computed by Kest or one of its relatives.

The argument theoretical should be a user-supplied function that computes the theoretical expected value of the summary statistic. It must have an argument named par that will be the vector of parameter values for the model (the length and format of this vector are determined by the starting values in startpar). The function theoretical should also expect a second argument (the first argument other than par) containing values of the distance r for which the theoretical value of the summary statistic K(r) should be computed. The value returned by theoretical should be a vector of the same length as the given vector of r values.

The argument ctrl determines the contrast criterion (the objective function that will be minimised). The algorithm minimises the criterion

D(theta) = integral from rmin to rmax of abs(Fhat(r)^q - F(theta,r)^q)^p

where theta is the vector of parameters of the model, Fhat(r) is the observed value of the summary statistic computed from the data, F(theta,r) is the theoretical expected value of the summary statistic, and p,q are two exponents. The default is q = 1/4, p=2 so that the contrast criterion is the integrated squared difference between the fourth roots of the two functions (Waagepetersen, 2007).

The argument action.bad.values specifies what to do if some of the values of the summary statistic are NA, NaN or infinite. If action.bad.values="stop", or if all of the values are bad, then a fatal error occurs. Otherwise, the domain of the summary function is shortened to avoid the bad values. The shortened domain is the longest interval on which the function values are finite (provided this interval is at least half the length of the original domain). A warning is issued if action.bad.values="warn" (the default) and no warning is issued if action.bad.values="silent".

The other arguments just make things print nicely. The argument fvlab contains labels for the component fit of the return value. The argument explain contains human-readable strings describing the data, the model and the summary statistic.

The "..." argument of mincontrast can be used to pass extra arguments to the function theoretical and/or to the optimisation function optim. In this case, the function theoretical should also have a "..." argument and should ignore it (so that it ignores arguments intended for optim).

Value

An object of class "minconfit". There are methods for printing and plotting this object. It contains the following components:

par	Vector of fitted parameter values.
fit	Function value table (object of class "fv") containing the observed values of the summary statistic (observed) and the theoretical values of the summary statistic computed from the fitted model parameters.
opt	The object returned from the optimizer optim.
crtl	List of parameters determining the contrast objective.
info	List of explanatory strings.

Author(s)

Rasmus Waagepetersen [e-mail], adapted for spatstat by \adrian.

References

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.

\Moller

, J. and Waagepetersen, R. (2003). Statistical Inference and Simulation for Spatial Point Processes. Chapman and Hall/CRC, Boca Raton.

Pfanzagl, J. (1969). On the measurability and consistency of minimum contrast estimates. Metrika 14, 249–276.

Waagepetersen, R. (2007). An estimating function approach to inference for inhomogeneous Neyman-Scott processes. Biometrics 63, 252–258.

See Also

kppm, lgcp.estK, matclust.estK, thomas.estK,

spatstat.core documentation built on May 18, 2022, 9:05 a.m.