fit_hawkes {stelfi}

Self-exciting Hawkes process(es)

Description

Fit a Hawkes process using Template Model Builder (TMB). The function fit_hawkes() fits a self-exciting Hawkes process with a constant background rate. Whereas, fit_hawkes_cbf() fits a Hawkes processes with a user defined custom background function (non-homogeneous background rate). The function fit_mhawkes() fits a multivariate Hawkes process that allows for between- and within-stream self-excitement.

Usage

fit_hawkes(
  times,
  parameters = list(),
  model = 1,
  marks = c(rep(1, length(times))),
  tmb_silent = TRUE,
  optim_silent = TRUE,
  ...
)

fit_hawkes_cbf(
  times,
  parameters = list(),
  model = 1,
  marks = c(rep(1, length(times))),
  background,
  background_integral,
  background_parameters,
  background_min,
  tmb_silent = TRUE,
  optim_silent = TRUE
)

fit_mhawkes(
  times,
  stream,
  parameters = list(),
  tmb_silent = TRUE,
  optim_silent = TRUE,
  ...
)

Arguments

times

A vector of numeric observed time points.

parameters

A named list of parameter starting values:

• mu, a vector of base rates for each stream of the multivariate Hawkes process,

• alpha, a matrix of the between- and within-stream self-excitement: the diagonal elements represent the within-stream excitement and the off-diagonals the excitement between streams,

• beta, a vector of the exponential intensity decay for each stream of the multivariate Hawkes process,

model

A numeric indicator specifying which model to fit:

• model = 1, fits a Hawkes process with exponential decay (default);

• model = 2, fits a Hawkes process with an alpha that can be negative.

marks

Optional, a vector of numeric marks, defaults to 1 (i.e., no marks).

tmb_silent

Logical, if TRUE (default) then TMB inner optimisation tracing information will be printed.

optim_silent

Logical, if TRUE (default) then for each iteration optim() output will be printed.

...

Additional arguments to pass to optim()

background

A function taking one parameter and an independent variable, returning a scalar.

background_integral

The integral of background.

background_parameters

The parameter(s) for the background function background. This could be a list of multiple values.

background_min

A function taking one parameter and two points, returns min of background between those points.

stream

A character vector specifying the stream ID of each observation in times

Details

A univariate Hawkes (Hawkes, AG. 1971) process is a self-exciting temporal point process with conditional intensity function \lambda(t) = \mu + \alpha \Sigma_{i:\tau_i<t}e^{(-\beta * (t-\tau_i))}. Here \mu is the constant baseline rate, \alpha is the instantaneous increase in intensity after an event, and \beta is the exponential decay in intensity. The term \Sigma_{i:\tau_i<t} \cdots describes the historic dependence and the clustering density of the temporal point process, where the \tau_i are the events in time occurring prior to time t. From this we can derive the following quantities 1) \frac{\alpha}{\beta} is the branching ratio, it gives the average number of events triggered by an event, and 2) \frac{1}{\beta} gives the rate of decay of the self-excitement. Including mark information results in the conditional intensity \lambda(t; m(t)) = \mu + \alpha \Sigma_{i:\tau_i<t}m(\tau_i)e^{(-\beta * (t-\tau_i))}, where m(t) is the temporal mark. This model can be fitted with fit_hawkes().

An in-homogenous marked Hawkes process has conditional intensity function \lambda(t) = \mu(t) + \alpha \Sigma_{i:\tau_i<t}e^{(-\beta * (t-\tau_i))}. Here, the background rate, \mu(t), varies in time. Such a model can be fitted using fit_hawkes_cbf() where the parameters of the custom background function are estimated before being passed to TMB.

A multivariate Hawkes process that allows for between- and within-stream self-excitement. The conditional intensity for the j^{th} (j = 1, ..., N) stream is given by \lambda(t)^{j*} = \mu_j + \Sigma_{k = 1}^N\Sigma_{i:\tau_i<t} \alpha_{jk} e^{(-\beta_j * (t-\tau_i))}, where j, k \in (1, ..., N). Here, \alpha_{jk} is the excitement caused by the k^{th} stream on the j^{th}. Therefore, \boldsymbol{\alpha} is an N x N matrix where the diagonals represent the within-stream excitement and the off-diagonals represent the excitement between streams.

Value

A list containing components of the fitted model, see TMB::MakeADFun. Includes

• par, a numeric vector of estimated parameter values;

• objective, the objective function;

• gr, the TMB calculated gradient function; and

• simulate, (where available) a simulation function.

References

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

See Also

show_hawkes

Examples

### ********************** ###
## A Hawkes model
### ********************** ###
data(retweets_niwa, package = "stelfi")
times <- unique(sort(as.numeric(difftime(retweets_niwa, min(retweets_niwa), units = "mins"))))
params <- c(mu = 0.05, alpha = 0.05, beta = 0.1)
fit <- fit_hawkes(times = times, parameters = params)
get_coefs(fit)
### ********************** ###
## A Hawkes model with marks (ETAS-type)
### ********************** ###
data("nz_earthquakes", package = "stelfi")
earthquakes <- nz_earthquakes[order(nz_earthquakes$origintime),]
earthquakes <- earthquakes[!duplicated(earthquakes$origintime), ]
times <- earthquakes$origintime
times <- as.numeric(difftime(times, min(times), units = "hours"))
marks <- earthquakes$magnitude
params <- c(mu = 0.05, alpha = 0.05, beta = 1)
fit <- fit_hawkes(times = times, parameters = params, marks = marks)
get_coefs(fit)


### ********************** ###
## A Hawkes process with a custom background function
### ********************** ###
if(require("hawkesbow")) {
times <- hawkesbow::hawkes(1000, fun = function(y) {1 + 0.5*sin(y)},
M = 1.5, repr = 0.5, family = "exp", rate = 2)$p
## The background function must take a single parameter and
## the time(s) at which it is evaluated
background <- function(params,times) {
A = exp(params[[1]])
B = stats::plogis(params[[2]]) * A
return(A + B  *sin(times))
}
## The background_integral function must take a
## single parameter and the time at which it is evaluated
background_integral <- function(params,x) {
        A = exp(params[[1]])
        B = stats::plogis(params[[2]]) * A
        return((A*x)-B*cos(x))
}
param = list(alpha = 0.5, beta = 1.5)
background_param = list(1,1)
fit <- fit_hawkes_cbf(times = times, parameters = param,
background = background,
background_integral = background_integral,
background_parameters = background_param)
get_coefs(fit)
}


### ********************** ###
## A multivariate Hawkes model
### ********************** ###
data(multi_hawkes, package = "stelfi")
fit <- fit_mhawkes(times = multi_hawkes$times, stream = multi_hawkes$stream,
parameters = list(mu =  c(0.2,0.2),
alpha =  matrix(c(0.5,0.1,0.1,0.5),byrow = TRUE,nrow = 2),
beta = c(0.7,0.7)))
get_coefs(fit)