R: Construct a New Determinantal Point Process Model Family...

detpointprocfamilyfun {spatstat.core} | R Documentation

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

### Value

A function in the R language, belonging to the class `"detpointprocfamilyfun"`. The function has formal arguments `...` and returns a determinantal point process family (object of class `"detpointprocfamily"`).

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner r.turner@auckland.ac.nz and Ege Rubak rubak@math.aau.dk.

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

[Package spatstat.core version 2.3-1 Index]