Experimental extension to `ppm`

which finds optimal values of the irregular trend parameters in a
point process model.

```
ippm(Q, …,
iScore=NULL,
start=list(),
covfunargs=start,
nlm.args=list(stepmax=1/2),
silent=FALSE,
warn.unused=TRUE)
```

Q,…

Arguments passed to `ppm`

to fit the point process model.

iScore

Optional. A named list of R functions that compute the partial derivatives of the logarithm of the trend, with respect to each irregular parameter. See Details.

start

Named list containing initial values of the irregular parameters over which to optimise.

covfunargs

Argument passed to `ppm`

.
A named list containing values for *all* irregular parameters
required by the covariates in the model.
Must include all the parameters named in `start`

.

nlm.args

Optional list of arguments passed to `nlm`

to control the optimization algorithm.

silent

Logical. Whether to print warnings if the optimization algorithm fails to converge.

warn.unused

Logical. Whether to print a warning if some of the parameters
in `start`

are not used in the model.

A fitted point process model (object of class `"ppm"`

)
which also belongs to the special class `"ippm"`

.

This function is an experimental extension to the
point process model fitting command `ppm`

.
The extension allows the trend of the model to include irregular parameters,
which will be maximised by a Newton-type iterative
method, using `nlm`

.

For the sake of explanation,
consider a Poisson point process with intensity function
\(\lambda(u)\) at location \(u\). Assume that
$$
\lambda(u) = \exp(\alpha + \beta Z(u)) \, f(u, \gamma)
$$
where \(\alpha,\beta,\gamma\) are
parameters to be estimated, \(Z(u)\) is a spatial covariate
function, and \(f\) is some known function.
Then the parameters
\(\alpha,\beta\) are called *regular* because they
appear in a loglinear form; the parameter
\(\gamma\) is called *irregular*.

To fit this model using `ippm`

, we specify the
intensity using the `trend`

formula
in the same way as usual for `ppm`

.
The trend formula is a representation of the log intensity.
In the above example the log intensity is
$$
\log\lambda(u) = \alpha + \beta Z(u) + \log f(u, \gamma)
$$
So the model above would be encoded with the trend formula
`~Z + offset(log(f))`

. Note that the irregular part of the model
is an *offset* term, which means that it is included in the log trend
as it is, without being multiplied by another regular parameter.

The optimisation runs faster if we specify the derivative
of \(\log f(u,\gamma)\) with
respect to \(\gamma\). We call this the
*irregular score*. To specify this, the user must write an R function
that computes the irregular score for any value of
\(\gamma\) at any location `(x,y)`

.

Thus, to code such a problem,

The argument

`trend`

should define the log intensity, with the irregular part as an offset;The argument

`start`

should be a list containing initial values of each of the irregular parameters;The argument

`iScore`

, if provided, must be a list (with one entry for each entry of`start`

) of functions with arguments`x,y,…`

, that evaluate the partial derivatives of \(\log f(u,\gamma)\) with respect to each irregular parameter.

The coded example below illustrates the model with two irregular parameters \(\gamma,\delta\) and irregular term $$ f((x,y), (\gamma, \delta)) = 1 + \exp(\gamma - \delta x^3) $$

Arguments `…`

passed to `ppm`

may
also include `interaction`

. In this case the model is not
a Poisson point process but a more general Gibbs point process;
the trend formula `trend`

determines the first-order trend
of the model (the first order component of the conditional intensity),
not the intensity.

# NOT RUN { nd <- 32 # } # NOT RUN { gamma0 <- 3 delta0 <- 5 POW <- 3 # Terms in intensity Z <- function(x,y) { -2*y } f <- function(x,y,gamma,delta) { 1 + exp(gamma - delta * x^POW) } # True intensity lamb <- function(x,y,gamma,delta) { 200 * exp(Z(x,y)) * f(x,y,gamma,delta) } # Simulate realisation lmax <- max(lamb(0,0,gamma0,delta0), lamb(1,1,gamma0,delta0)) set.seed(42) X <- rpoispp(lamb, lmax=lmax, win=owin(), gamma=gamma0, delta=delta0) # Partial derivatives of log f DlogfDgamma <- function(x,y, gamma, delta) { topbit <- exp(gamma - delta * x^POW) topbit/(1 + topbit) } DlogfDdelta <- function(x,y, gamma, delta) { topbit <- exp(gamma - delta * x^POW) - (x^POW) * topbit/(1 + topbit) } # irregular score Dlogf <- list(gamma=DlogfDgamma, delta=DlogfDdelta) # fit model ippm(X ~Z + offset(log(f)), covariates=list(Z=Z, f=f), iScore=Dlogf, start=list(gamma=1, delta=1), nlm.args=list(stepmax=1), nd=nd) # }