spatstat (version 1.48-0)

detpointprocfamilyfun: Construct a New Determinantal Point Process Model Family Function

Description

Function to ease the implementation of a new determinantal point process model family.

Usage

detpointprocfamilyfun(kernel = NULL, specden = NULL, basis = "fourierbasis",  convkernel = NULL, Kfun = NULL, valid = NULL, intensity = NULL,  dim = 2, name = "User-defined", isotropic = TRUE, range = NULL,  parbounds = NULL, specdenrange = NULL, startpar = NULL, ...)

Arguments

kernel

function specifying the kernel. May be set to NULL. See Details.

specden

function specifying the spectral density. May be set to NULL. See Details.

basis

character string giving the name of the basis. Defaults to the Fourier basis. See Details.

convkernel

function specifying the k-fold auto-convolution of the kernel. May be set to NULL. See Details.

Kfun

function specifying the K-function. May be set to NULL. See Details.

valid

function determining whether a given set of parameter values yields a valid model. May be set to NULL. See Examples.

intensity

character string specifying which parameter is the intensity in the model family. Should be NULL if the model family has no intensity parameter.

dim

character strig specifying which parameter is the dimension of the state space in this model family (if any). Alternatively a positive integer specifying the dimension.

name

character string giving the name of the model family used for printing.

isotropic

logical value indicating whether or not the model is isotropic.

range

function determining the interaction range of the model. May be set to NULL. See Examples.

parbounds

function determining the bounds for each model parameter when all other parameters are fixed. May be set to NULL. See Examples.

specdenrange

function specifying the the range of the spectral density if it is finite (only the case for very few models). May be set to NULL.

startpar

function determining starting values for parameters in any estimation algorithm. May be set to NULL. See Examples.

...

Additional arguments for inclusion in the returned model object. These are not checked in any way.

Details

A determinantal point process family is specified either in terms of a kernel (a positive semi-definite function, i.e. a covariance function) or a spectral density, or preferably both. One of these can be NULL if it is unknown, but not both. When both are supplied they must have the same arguments. The first argument gives the values at which the function should be evaluated. In general the function should accept an $n$ by $d$ matrix or data.frame specifying $n (>=0)$ points in dimension $d$. If the model is isotropic it only needs to accept a non-negative valued numeric of length $n$. (In fact there is currently almost no support for non-isotropic models, so it is recommended not to specify such a model.) The name of this argument could be chosen freely, but $x$ is recommended. The remaining arguments are the parameters of the model. If one of these is an intensity parameter the name should be mentioned in the argument intensity. If one of these specifies the dimension of the model it should be mentioned in the argument dim.

The kernel and spectral density is with respect to a specific set of basis functions, which is typically the Fourier basis. However this can be changed to any user-supplied basis in the argument basis. If such an alternative is supplied it must be the name of a function expecting the same arguments as fourierbasis and returning the results in the same form as fourierbasis.

If supplied, the arguments of convkernel must obey the following: first argument should be like the first argument of kernel and/or specden (see above). The second argument (preferably called k) should be the positive integer specifying how many times the auto-convolution is done (i.e. the $k$ in $k$-fold auto-convolution). The remaining arguments must agree with the arguments of kernel and/or specden (see above).

If supplied, the arguments of Kfun should be like the arguments of kernel and specden (see above).

Examples

  ## Example of how to define the Gauss family
exGauss <- detpointprocfamilyfun(
    name="Gaussian",
    kernel=function(x, lambda, alpha, d){
        lambda*exp(-(x/alpha)^2)
    },
    specden=function(x, lambda, alpha, d){
        lambda * (sqrt(pi)*alpha)^d * exp(-(x*alpha*pi)^2)
    },
    convkernel=function(x, k, lambda, alpha, d){
        logres <- k*log(lambda*pi*alpha^2) - log(pi*k*alpha^2) - x^2/(k*alpha^2)
        return(exp(logres))
    },
    Kfun = function(x, lambda, alpha, d){
        pi*x^2 - pi*alpha^2/2*(1-exp(-2*x^2/alpha^2))
    },
    valid=function(lambda, alpha, d){
        lambda>0 && alpha>0 && d>=1 && lambda <= (sqrt(pi)*alpha)^(-d)
    },
    isotropic=TRUE,
    intensity="lambda",
    dim="d",
    range=function(alpha, bound = .99){
        if(missing(alpha))
            stop("The parameter alpha is missing.")
        if(!(is.numeric(bound)&&bound>0&&bound<1))
            stop("Argument bound must be a numeric between 0 and 1.")
        return(alpha*sqrt(-log(sqrt(1-bound))))
    },
    parbounds=function(name, lambda, alpha, d){
        switch(name,
               lambda = c(0, (sqrt(pi)*alpha)^(-d)),
               alpha = c(0, lambda^(-1/d)/sqrt(pi)),
               stop("Parameter name misspecified")
               )
    },
    startpar=function(model, X){
        rslt <- NULL
        if("lambda" %in% model$freepar){
            lambda <- intensity(X)
            rslt <- c(rslt, "lambda" = lambda)
            model <- update(model, lambda=lambda)
        }
        if("alpha" %in% model$freepar){
            alpha <- .8*dppparbounds(model, "alpha")[2]
            rslt <- c(rslt, "alpha" = alpha)
        }
        return(rslt)
    }
    )
  exGauss
  m <- exGauss(lambda=100, alpha=.05, d=2)
  m