In cmjt/stelfi: Hawkes and Log-Gaussian Cox Point Processes Using Template Model Builder
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 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 an ETAS-type marked model
- Fitting a multivariate 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.
-
-
-
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.
cmjt/stelfi documentation built on Oct. 25, 2023, 2:53 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
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 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()andfit_hawkes_cbf()fit self-exciting Hawkes (Hawkes AG., 1971) processes to temporal point pattern data. - Fitting an ETAS-type marked model
- Fitting a multivariate 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. -
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.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.