fit_hawkes {stelfi} | R Documentation |
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:
|
model |
A numeric indicator specifying which model to fit:
|
marks |
Optional, a vector of numeric marks, defaults to 1 (i.e., no marks). |
tmb_silent |
Logical, if |
optim_silent |
Logical, if |
... |
Additional arguments to pass to |
background |
A function taking one parameter and an independent variable, returning a scalar. |
background_integral |
The integral of |
background_parameters |
The parameter(s)
for the background function |
background_min |
A function taking one parameter and two points,
returns min of |
stream |
A character vector specifying the stream ID of each observation in |
Details
A univariate Hawkes (Hawkes, AG. 1971) process is a self-exciting temporal point process
with conditional intensity function
. Here
is the constant
baseline rate,
is the instantaneous increase in intensity after an event, and
is the
exponential decay in intensity. The term
describes the historic dependence
and the clustering density of the temporal point process, where the
are the events in
time occurring prior to time
. From this we can derive the following quantities 1)
is the branching ratio, it gives the average number of events triggered by an event, and
2)
gives the rate of decay of the self-excitement.
Including mark information results in the conditional intensity
,
where
is the temporal mark. This model can be fitted with
fit_hawkes()
.
An in-homogenous marked Hawkes process has conditional intensity function
. Here, the
background rate,
, 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 (
) stream is given by
, where
. Here,
is the excitement caused by the
stream on the
. Therefore,
is an
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
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)