# stelfi

## Introduction

`stelfi` fits Hawkes and Log-Gaussian Cox Point Process models using Template Model Builder. See the package’s website for more details.

Introduced in Hawkes (1971) a Hawkes process is a self-exciting temporal point process where the occurrence of an event immediately increases the chance of another. We extend this to consider self-inhibiting process and a non-homogeneous background rate. A log-Gaussian Cox process is a Poisson point process where the log-intensity is given by a Gaussian random field. We extend this to a joint likelihood formulation fitting a marked log-Gaussian Cox model.

In addition, the package offers functionality to fit self-exciting spatiotemporal point processes. Models are fitted via maximum likelihood using `TMB` (Template Model Builder) (Kristensen, Nielsen, Berg, Skaug, and Bell, 2016). Where included 1) random fields are assumed to be Gaussian and are integrated over using the Laplace approximation and 2) a stochastic partial differential equation model, introduced by Lindgren, Rue, and Lindström. (2011), is defined for the field(s).

## Installation

From CRAN `install.packages("stelfi")` or development version from GitHub:

    require(devtools)
    devtools::install_github("cmjt/stelfi")

## Model fitting functions and examples

- The functions `fit_hawkes()` and `fit_hawkes_cbf()` fit self-exciting Hawkes (Hawkes AG., 1971) processes to temporal point pattern data.

  - Fitting a Hawkes model
  - Fitting an ETAS-type marked model
  - Fitting a multivariate Hawkes model
  - Fitting an inhomogenous Hawkes process

- The function `fit_lgcp()` fit a log-Gaussian Cox process to either spatial or spatiotemporal point pattern data. If a spatiotemporal model is fitted a AR1 process is assumed for the temporal progression.

  - Fitting a spatial LGCP

- The function `fit_mlgcp()` fits a joint likelihood model between the point locations and the mark(s).

- The function `fit_stelfi()` fits self-exciting spatiotemporal Hawkes models to point pattern data. The self-excitement is Gaussian in space and exponentially decaying over time. In addition, a GMRF can be included to account for latent spatial dependency.

### Key arguments for each each model fitting function

Function | Key arguments
--- | ---
`fit_hawkes()` | `times` - a vector of `numeric` occurrence times. `parameters` - a vector of named starting values for \(\mu\) (`mu`), \(\alpha\) (`alpha`), and \(\beta\) (`beta`). `marks` - optional, a vector of marks (\(m(t)\)).
`fit_mhawkes()` | `times` - a vector of `numeric` occurrence times. `stream` - `character` vector specifying the stream ID of each observation in `times`. `parameters` - a vector of named starting values for \(\mu\) (`mu`), \(\alpha\) (`alpha`), and \(\beta\) (`beta`).
`fit_hawkes_cbf()` | As `fit_hawkes()` plus `background` - some assumed time dependent background function \(\mu(t)\). `background_integral` - the integral of `background`. `background_parameters` - parameter starting values for \(\mu(t)\). ( \(^*\)Note, \(\texttt{mu}\) in `parameters` will be ignored)
`fit_lgcp()` | `locs` - a named data frame of event locations, `x`, `y`, and `t` (optional). `sf` - a polygon of the spatial domain. `smesh` - a Delaunay triangulation of the spatial domain returned by `INLA::inla.mesh.2d()`. `tmesh` - optional, a temporal mesh returned by `INLA::inla.mesh.1d()`). `parameters` - a vector of named starting values for \(\boldsymbol{\beta}\) (`beta`), \(\text{log}(\tau)\) (`log_tau`), \(\text{log}(\kappa)\) (`log_kappa`), and \(\textrm{arctan}(\rho)\) (`atanh_rho`, optional).
`fit_mlgcp()` | `locs`, `sf`, and `smesh` - as `fit_lgcp()`. `marks` - a matrix of marks for each observation of the point pattern. `parameters` - a list of named parameters, as `fit_lgcp()` plus (`betamarks`), (`betapp`), (`marks_coefs_pp` ). `methods` - integer(s) specifying mark distribution: `0`, Gaussian; `1`, Poisson; `2`, binomial; `3`, gamma. `strfixed` - fixed structural parameters, depends on mark distribution. `fields` - a binary vector indicating whether there is a new random field for each mark.
`fit_stelfi()` | `times` - as `fit_hawkes()`. `locs`, `sf`, and `smesh` - as `fit_lgcp()`. `parameters` - a list of named parameter starting values for \(\mu\) (`mu`), \(\alpha\) (`alpha`), \(\beta\) (`beta`), \(\sigma_x\) (`xsigma`) \(\sigma_y\) (`ysigma`), and \(\rho\) (`rho`). `GMRF` - logical, should a GMRF be included as a latent spatial effect if so \(\tau\) (`tau`) and \(\kappa\)(`kappa`) supplied to `parameters`.

## Other useful funcions

Function | Key arguments | Purpose
--- | --- | ---
`get_coefs()` | `obj` - a fitted model object returned by any one of the functions in the Table above | Extract estimated parameter values from a fitted model.
`get_fields()` | As `fit_lgcp()` and `sd` - logical, return standard deviation. | Extract estimated mean, or standard deviation, of GMRF(s).
`get_weights()` | `mesh` - a Delaunay triangulation of the spatial domain returned by `INLA::inla.mesh. 2d()`. `sf` - a polygon of the spatial domain. | Calculate mesh weights.
`mesh_2_sf()` | `mesh` - a Delaunay triangulation of the spatial domain returned by `INLA::inla.mesh. 2d()`. | Transforms `mesh` into a `sf` object.
`show_field()` | `x` - a vector of values, one per each smesh node. `smesh` - as `fit_lgcp()` . `sf` - as `fit_lgcp()`. `clip` - logical, clip to domain | Plots spatial random field values.
`show_hawkes()` | `obj` - a fitted model object returned by `fit_hawkes()` or `fit_hawkes_cbf()`. | Plot fitted Hawkes model.
`show_hawkes_GOF()` | `obj` - as `show_hawkes()`. `plot` - logical `return_values` - logical, return compensator values | Plot goodness-of-fit metrics for a Hawkes model.
`show_lambda()` | As `fit_lgcp()` and `clip` - logical, clip to domain | Plot estimated spatial intensity from a fitted log-Gaussian Cox process model.
`sim_hawkes()` | As `fit_hawkes()` | Simulate a Hawkes process.
`sim_lgcp()` | As `fit_lgcp()` | Simulate a realisation of a log-Gaussian Cox process.

### References

Hawkes, AG. (1971) Spectra of some self-exciting and mutually exciting point processes. Biometrika, 58: 83–90.

Lindgren, F., Rue, H., and Lindström, J. (2011) An explicit link between Gaussian fields and Gaussian Markov random fields: the stochastic partial differential equation approach. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 73: 423–498.

Kristensen, K., Nielsen, A., Berg, C. W., Skaug, H., and Bell B. M. (2016). TMB: Automatic Differentiation and Laplace Approximation. Journal of Statistical Software, 70: 1–21.