Module `HawkesPyLib.processes`

Classes

class UnivariateHawkesProcess (kernel: str)

Implements multiple univariate Hawkes process models and allows for the calculation of basic process characteristics.

The following Hawkes process models are implemented:

Hawkes process with single exponential memory kernel ('expo' kernel), defined by the conditional intensity function: $\lambda(t) = \mu + \dfrac{\eta}{\theta} \sum_{t_i < t} e^{(-(t - t_i)/\theta)}$

where $\mu$ (mu) is the constant background intensity, $\eta$ (eta) is the branching ratio and $\theta$ (theta) is the exponential decay parameter.
Hawkes process with P-sum exponential memory kernel ('sum-expo' kernel), defined by the conditional intensity function: $\lambda(t) = \mu + \dfrac{\eta}{P} \sum_{t_i < t} \sum_{k=1}^{P} \dfrac{1}{\theta_k} e^{(-(t - t_i)/\theta_k)}$

where $\mu$ (mu) is the constant background intensity, $\eta$ (eta) is the branching ratio and $\theta_k$ is the k'th exponential decay parameter in (theta_vec).
Hawkes process with approximate power-law kernel ('powlaw' kernel), defined by the conditional intenstiy function: $\lambda(t) = \mu + \sum_{t_i < t} \dfrac{\eta}{Z} \bigg[ \sum_{k=0}^{M-1} a_k^{-(1+\alpha)} e^{(-(t - t_i)/a_k)} \bigg],$

where $\mu$ (mu) is the constant background intensity, $\eta$ (eta) is the branching ratio, $\alpha$ (alpha) is the power-law tail exponent and $\tau_0$ a scale parameter controlling the decay timescale.
Hawkes process with approximate power-law kernel with smooth cutoff ('powlaw-cutoff' kernel), defined by the conditional intenstiy function: $\lambda(t) = \mu + \sum_{t_i < t} \dfrac{\eta}{Z} \bigg[ \sum_{k=0}^{M-1} a_k^{-(1+\alpha)} e^{(-(t - t_i)/a_k)} - S e^{(-(t - t_i)/a_{-1})} \bigg],$

where $\mu$ (mu) is the constant background intensity, $\eta$ (eta) is the branching ratio, $\alpha$ (alpha) is the power-law tail exponent and $\tau_0$ a scale parameter controlling the decay timescale and the location of the smooth cutoff point (i.e. the time duration after each jump at which the intensity reaches a maximum).

The true power-law is approximtated by a sum of $M$ exponential function with power-law weights $a_k = \tau_0 m^k$ . $M$ is the number of exponentials used for the approximation and $m$ is a scale parameter. The power-law approximation holds for times up to $m^{M-1}$ after which the memory kernel decays exponentially. S and Z are scaling factors that ensure that the memory kernel integrates to $\eta$ and that the kernel value at time zero is zero (for the smooth cutoff version). S and Z are computed automatically.

The following main methods are available:

UnivariateHawkesProcess.intensity() evaluates the conditional intensity function $\lambda(t)$ .
UnivariateHawkesProcess.compensator() computes the compensator process $\Lambda(t) = \int_0^t \lambda(u) du$ .
UnivariateHawkesProcess.kernel_values() returns values for the memory kernel.
UnivariateHawkesProcess.compute_logL() computes the log-likelihood function.

The class works by first initlizing with the desired kernel type and secondly by setting the corresponding parameters and arrival times using the set_params() and set_arrival_times() methods.

Args

kernel : str: Type of Hawkes process memory kernel, one of 'expo', 'sum-expo', 'powlaw', 'powlaw-cutoff'

Attributes

mu : float: The background intensity, $\mu > 0$ .
eta : float: The branching ratio, $0 < eta > 1$ .
theta : float: Decay speed of single exponential kernel, $\theta > 0$ . Only set if kernel is set to 'expo'.
theta_vec : np.ndarray, optional: Decay speeds of the P-sum, exponential kernel, $\theta_k > 0$ . Only set if kernel is set to 'sum-expo'.
alpha : float: Tail exponent of the power-law decay, $\alpha > 0$ . Only set if kernel is set to 'powlaw' or 'powlaw-cutoff'.
tau0 : float: Timescale parameter, $\tau_0 > 0$ . Only set if kernel is set to 'powlaw' or 'powlaw-cutoff'.
T : float: End time of the Hawkes process.
timestamps : np.ndarray: 1d array of arrival times.

Subclasses

Methods

def set_params(self, mu: float, eta: float, **kwargs) ‑> None

Set Hawkes process model parameters. Arguments mu and eta are always requiered. The other arguements depend on the chosen kernel and are supplied to **kwargs.

Args

mu : float: The background intensity, $\mu > 0$ .
eta : float: The branching ratio, $0 < \eta > 1$ .
theta : float: Decay speed of single exponential kernel, $\theta$ > 0. Must be set if kernel is set to 'expo'.
theta_vec : np.ndarray, optional: Decay speed of P-sum, exponential kernel, theta_k > 0. Must be set if kernel is set to 'sum-expo'.
alpha : float: Tail index of the power-law decay, $\alpha > 0$ . Must be set if kernel is set to 'powlaw' or 'powlaw-cutoff'.
tau0 : float: Timescale parameter, $\tau_0 > 0$ . Must be set if kernel is set to 'powlaw' or 'powlaw-cutoff'.
m : float, optional: Scale parameter of the power-law weights, m > 0. Must be set if kernel is set to 'powlaw' or 'powlaw-cutoff'.
M : int, optional: Number of weighted exponential kernels used in the approximate power-law kernel.

Must be set if kernel is set to 'powlaw' or 'powlaw-cutoff'.

def set_arrival_times(self, timestamps: numpy.ndarray, T: float) ‑> None

Set arrival times of the process.

Args

timestamps : np.ndarray: 1d array of arrival times of the process. Arrival times must be positive and ordered.
T : float: End time of the process. T must be larger or equal to the last arrival time.

def get_params(self) ‑> tuple

Returns the model parameters:

Returns

tuple: Tuple of parameter values such as:

If kernel set to 'expo':

mu (float), eta (float), theta (float)

If kernel set to 'sum-expo':

mu (float), eta (float), theta_vec (np.ndarray)

If kernel set to 'powlaw' or 'powlaw-cutoff':

mu (float), eta (float), alpha (float), tau0 (float), m (float), M (int)

def intensity(self, step_size: float) ‑> numpy.ndarray

Evaluates the intensity function $\lambda(t)$ on a grid of equidistant timestamps over the closed interval [0, T] with step size step_size.

Note

Additionally to the equidistant time grid the intensity is evaluated at each simulated arrival time.
If the process end time T is not perfectly divisible by the step size the 'effective' step size deviates slightly from the given one.

Args

step_size : float: Step size of the time grid.

Returns

np.ndarray: 2d array of timestamps (column 0) and corresponding intensity values (column 1)

def compensator(self)

Computes the compensator of the process at the set timestamps given the set parameter values. The compensator of a point process is defined as the integral of the conditional intensity: $\Lambda(t) = \int_0^t \lambda(u) du$

Tip

If the set arrival times are a realization of the Hawkes process specified by the set parameters, the resulting compensator will be a Poisson process with unit intensity (assuming a large enough sample size).

Returns

np.ndarray: 1d array of timestamps (the compensator)

def kernel_values(self, times: numpy.ndarray) ‑> numpy.ndarray

Returns the value of the memory kernel at given time values.

The single exponential memory kernel:

$g(t) = \dfrac{\eta}{\theta} e^{(-t/\theta)}$

The P-sum exponential memory kernel:

$g(t) = \dfrac{\eta}{P} \sum_{k=1}^{P} \dfrac{1}{\theta_k} e^{(-t/\theta_k)}$

The approximate power-law memory kernel:

$g(t) = \dfrac{\eta}{Z} \bigg[ \sum_{k=0}^{M-1} a_k^{-(1+\alpha)} e^{(-(t - t_i)/a_k)} \bigg]$

And the approximate power-law kernel with smooth cutoff :

$g(t) = \dfrac{\eta}{Z} \bigg[ \sum_{k=0}^{M-1} a_k^{-(1+\alpha)} e^{(-(t - t_i)/a_k)} - S e^{(-(t - t_i)/a_{-1})} \bigg]$

Args

times : np.ndarray: 1d array of time values for which to compute the value of the memory kernel.

Returns

np.ndarray: 1d array containing the values of the memory kernel value at the given time(s).

def compute_logL(self)

Computes the log-likelihood function given the process parameters, arrival times and process end time T.

The log-likelihood function of a Hawkes process is given by: $logL(t_1,..., t_n) = -\int_0^T \lambda(t) du + \sum_{t=1}^n log(\lambda(t_i))$

Returns

float: The log-likelihood value

def ic(self, type: str) ‑> float

Calculates one of the following information criteria given the set parameters and arrival times:

'aic': Akaike information criteria
'bic': Baysian information criteria
'hq': Hannan-Quinn information criteria

Args

type : str: Which information criterion to return, must be one of: 'aic', 'bic', 'hq'

Returns

float: The information criterions value