1  Introduction

stelfi fits Hawkes processes, log-Gaussian Cox processes (LGCPs), and spatiotemporal self-exciting models to point pattern data. All models are fitted by maximum likelihood using Template Model Builder (TMB, Kristensen et al. (2016)), which makes fitting fast even for fairly large datasets. Where a model includes a spatial random field, the field is assumed to be Gaussian, it is built using the stochastic partial differential equation (SPDE) approach of Lindgren, Rue, and Lindström (2011), and it is integrated out of the likelihood using the Laplace approximation.

This book is written for people who have point pattern data of their own and want to know (1) which stelfi model suits their data, (2) what shape the data need to be in, (3) how to fit and interpret the model, and (4) how to check whether the model is any good. The emphasis is on using the models rather than on the theory behind them.

1.1 What is a point pattern?

A point pattern is a record of when and/or where events happened. Examples are the times of retweets of a tweet, the locations of sasquatch sightings, or the times, locations, and magnitudes of earthquakes. The thing being modelled is the intensity, the expected rate of events per unit time (or per unit area, or per unit area per unit time). A high intensity means events are likely, a low intensity means events are unlikely.

The models in stelfi differ in why the intensity varies:

  • In a Hawkes process events cause more events. Each event temporarily increases the chance of another event occurring soon afterwards (self-excitement). Think of aftershocks following an earthquake or retweets following a tweet.
  • In a log-Gaussian Cox process the intensity varies smoothly over space (and time) because of some underlying, unobserved, environment. Events do not cause other events, they are just more common in some places than others. Think of where species are found or where crimes tend to occur.
  • A spatiotemporal self-exciting model combines the two: there is a background intensity over space and events trigger further events nearby in both space and time.

1.2 Which chapter do I need?

The table below summarises which model suits which type of data, and in which chapter it is covered.

Your data Model stelfi function Chapter
Event times only, events seem to trigger further events Univariate Hawkes process fit_hawkes() Chapter 2
As above, but with a background rate that changes over time (e.g., yearly cycles) Hawkes with a custom background function fit_hawkes_cbf() Section 2.5
Event times plus a numeric value for each event that might change how much it triggers (e.g., magnitude) Marked Hawkes process fit_hawkes() with marks Chapter 3
Event times for two or more types of event that might trigger each other Multivariate Hawkes process fit_mhawkes() Chapter 4
Event locations within a study region Spatial LGCP fit_lgcp() Chapter 6
Event locations and times (e.g., year), spatial pattern changes over time Spatiotemporal LGCP fit_lgcp() with tmesh Section 6.5
Event locations plus one or more measurements on each event Marked LGCP fit_mlgcp() Chapter 7
Event locations and times, events trigger further events nearby Spatiotemporal self-exciting (Hawkes) model fit_stelfi() Chapter 8
You want to write and modify the likelihood yourself RTMB templates – Chapter 9

1.3 How the model chapters are organised

Each of the model fitting chapters (Chapter 2 to Chapter 8, other than Chapter 5 on meshes) follows the same structure:

  1. The model and your data: a short description of the model, what the parameters mean, and what your data need to look like (including common problems and limitations).
  2. A simulated example: data are simulated from the model with known parameter values. The model is then fitted using stelfi and, where one exists, a competing R package, and the estimates from both are compared with each other and with the truth. The code used to simulate the data is shown, so that every chapter is fully reproducible, and so that you can change the parameter values (or the amount of data) and see how well the model is estimated.
  3. An applied example: the model is fitted to one of the datasets that come with stelfi (see Chapter 10) and the estimates are interpreted.
  4. Goodness-of-fit: some procedures to check whether the fitted model adequately describes the data.

The chapters build on one another: the univariate Hawkes chapter (Chapter 2) introduces ideas used in all of the Hawkes-type chapters, and the chapter on meshes (Chapter 5) and the spatial LGCP chapter (Chapter 6) introduce ideas used in all of the spatial chapters. If you are new to these models, start there.

1.4 A typical stelfi workflow

Whatever the model, using stelfi involves the same steps:

  1. Prepare the data. Times must be numeric (e.g., days since the first event) and sorted. Locations must be in a projected (planar) coordinate system, such as UTM, ideally in sensible units (e.g., km).
  2. For spatial models, define the study region and build a mesh. The study region is an sf polygon and the mesh is a triangulation of it built with fmesher::fm_mesh_2d() (see Chapter 5).
  3. Choose starting values for the parameters and fit the model with one of the fit_*() functions.
  4. Extract the estimates using get_coefs() (and, for spatial models, the estimated random field using get_fields()).
  5. Visualise the fitted model using show_hawkes(), show_multivariate_hawkes(), show_field() or show_lambda().
  6. Check the fit using show_hawkes_GOF() (temporal models) or simulation-based checks (spatial models).

1.5 Key stelfi functions

Model fitting functions

Function Key arguments
fit_hawkes() times, a sorted numeric vector of event times with no ties; parameters, named starting values for \(\mu\) (mu), \(\alpha\) (alpha), and \(\beta\) (beta); marks, optional, a numeric vector of marks (one per event).
fit_hawkes_cbf() As fit_hawkes() plus background, a function giving the background rate \(\mu(t)\); background_integral, its integral; and background_parameters, starting values for the parameters of \(\mu(t)\). (mu in parameters is ignored.)
fit_mhawkes() times, a sorted numeric vector of event times (all streams together); stream, a character vector giving the stream (type) of each event; parameters, a list with mu (vector, one per stream), alpha (matrix, streams \(\times\) streams), and beta (vector, one per stream), with alpha[j, k] the effect of stream \(k\) on stream \(j\) and beta[j] the decay rate of stream \(j\).
fit_lgcp() locs, a data frame of event locations with columns x, y (and t for a spatiotemporal model); sf, an sf polygon of the study region; smesh, a spatial mesh from fmesher::fm_mesh_2d(); tmesh, optional, a temporal mesh from fmesher::fm_mesh_1d(); parameters, starting values for beta (intercept and any covariate coefficients), log_tau, log_kappa, and (spatiotemporal only) atanh_rho; covariates, optional, a matrix with one row per mesh node.
fit_mlgcp() locs, sf, and smesh as fit_lgcp(); marks, a matrix of marks with one column per mark; methods, the distribution of each mark (0 Gaussian, 1 Poisson, 2 binomial, 3 gamma); fields, whether each mark has its own random field; strfixed, fixed structural parameters (e.g., the log standard deviation of a Gaussian mark); parameters, a list of starting values (betapp, betamarks, marks_coefs_pp, log_tau, log_kappa).
fit_stelfi() times, as fit_hawkes(); locs, sf, and smesh, as fit_lgcp(); parameters, a list of starting values for coefs (log background rate, or mu), alpha, beta, xsigma, ysigma, rho, and, if GMRF = TRUE, kappa and tau; GMRF, logical, include a spatial random field in the background; time_independent, logical, whether the spatial spread of the triggering kernel is fixed over time.

Utility and plotting functions

Function Purpose
get_coefs() Estimated parameters and standard errors from any fitted model.
get_fields() Estimated values (or standard errors, sd = TRUE) of the random field(s) at each mesh node.
get_weights() The area of the study region associated with each mesh node.
mesh_2_sf() Converts a mesh to an sf object (e.g., for plotting with ggplot2).
meshmetrics() Geometric summaries of each triangle in a mesh (see Section 5.3).
show_hawkes() Plots the fitted conditional intensity of a Hawkes model (and/or the data).
show_multivariate_hawkes() As show_hawkes() for a multivariate Hawkes model.
show_hawkes_GOF() Goodness-of-fit plots and tests for a Hawkes model.
compensator_differences() The transformed inter-event times (compensator differences) of a fitted Hawkes model.
show_field() Plots values at the mesh nodes (e.g., an estimated random field) as a surface.
show_lambda() Plots the estimated intensity surface of a fitted LGCP.
sim_hawkes() Simulates from a univariate Hawkes process.
sim_lgcp() Simulates a random field and event counts from a spatial LGCP.