---
title: "stelfi"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{stelfi}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

`stelfi` fits Hawkes and Log-Gaussian Cox Point Process models using Template Model Builder. See [the package's website](https://cmjt.github.io/stelfi/) 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:

```{r, eval = FALSE}
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](https://cmjt.github.io/stelfi/univariate-hawkes.html)
   + [Fitting an ETAS-type marked model](https://cmjt.github.io/stelfi/marked-hawkes.html)
   + [Fitting a multivariate Hawkes model](https://cmjt.github.io/stelfi/multi-hawkes.html)
   + [Fitting an inhomogenous Hawkes process](https://cmjt.github.io/stelfi/univariate-hawkes.html#fitting-an-inhomogenous-hawkes-model)
 
 + 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](https://cmjt.github.io/stelfi/lgcp.html)
 
 + 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  | Extract estimated     |
|                       |     model object      | parameter values from |
|                       |     returned by any   | a fitted model.       |
|                       |     one of the        |                       |
|                       |     functions in the  |                       |
|                       |     Table  above      |                       |
+-----------------------+-----------------------+-----------------------+
| `get_fields()`        | As `fit_lgcp()` and   | Extract estimated     |
|                       |                       | mean, or standard     |
|                       | -   `sd` - logical,   | deviation, of         |
|                       |     return standard   | GMRF(s).              |
|                       |     deviation.        |                       |
+-----------------------+-----------------------+-----------------------+
| `get_weights()`       | -   `mesh` - a        | Calculate mesh        |
|                       |     Delaunay          | weights.              |
|                       |     triangulation of  |                       |
|                       |     the spatial       |                       |
|                       |     domain returned   |                       |
|                       |     by                |                       |
|                       |     `INLA::inla.mesh. |                       |
|                       | 2d()`.                |                       |
|                       |                       |                       |
|                       | -   `sf` - a polygon  |                       |
|                       |     of the spatial    |                       |
|                       |     domain.           |                       |
+-----------------------+-----------------------+-----------------------+
| `mesh_2_sf()`         | -   `mesh` - a        | Transforms `mesh`     |
|                       |     Delaunay          | into a `sf` object.   |
|                       |     triangulation of  |                       |
|                       |     the spatial       |                       |
|                       |     domain returned   |                       |
|                       |     by                |                       |
|                       |     `INLA::inla.mesh. |                       |
|                       | 2d()`.                |                       |
+-----------------------+-----------------------+-----------------------+
| `show_field()`        | -   `x` - a vector of | Plots spatial random  |
|                       |     values, one per   | field values.         |
|                       |     each smesh node.  |                       |
|                       |                       |                       |
|                       | -   `smesh` - as      |                       |
|                       |     `fit_lgcp()` .    |                       |
|                       |                       |                       |
|                       | -   `sf` - as         |                       |
|                       |     `fit_lgcp()`.     |                       |
|                       |                       |                       |
|                       | -   `clip` - logical, |                       |
|                       |     *clip* to domain  |                       |
+-----------------------+-----------------------+-----------------------+
| `show_hawkes()`       | -   `obj` - a fitted  | Plot fitted Hawkes    |
|                       |     model object      | model.                |
|                       |     returned by       |                       |
|                       |     `fit_hawkes()` or |                       |
|                       |     `fit_hawkes_cbf() |                       |
|                       | `.                    |                       |
+-----------------------+-----------------------+-----------------------+
| `show_hawkes_GOF()`   | -   `obj` - as        | Plot goodness-of-fit  |
|                       |     `show_hawkes()`.  | metrics for a Hawkes  |
|                       |                       | model.                |
|                       | -   `plot` - logical  |                       |
|                       |                       |                       |
|                       | -   `return_values` - |                       |
|                       |     logical, return   |                       |
|                       |     compensator       |                       |
|                       |     values            |                       |
+-----------------------+-----------------------+-----------------------+
| `show_lambda()`       | As `fit_lgcp()` and   | Plot estimated        |
|                       |                       | spatial intensity     |
|                       | -   `clip` - logical, | from a fitted         |
|                       |     *clip* to domain  | 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.

