# ippm

##### Fit Point Process Model Involving Irregular Trend Parameters

Experimental extension to `ppm`

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

##### Usage

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

##### Arguments

- Q,...
- Arguments passed to
`ppm`

to fit the point process model. - iScore
- Optional. A named list of Rfunctions 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.

##### Details

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 Rfunction
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.

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.

##### Value

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

).

##### See Also

##### Examples

```
nd <- 32
<testonly>nd <- 10</testonly>
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),
nd=nd)
```

*Documentation reproduced from package spatstat, version 1.42-2, License: GPL (>= 2)*