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.
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
- Fitting a spatiotemporal LGCP
The function fit_mlgcp() fits a joint likelihood model between the point locations and the mark(s).
- Fitting a marked LGCP
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.
- Spatiotemporal self-exciting models

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.