Quickstart

Simulate a two-type process from known parameters, fit it, read the result, check the fit by time rescaling, and ask what the calibration study measured for this regime. The code on this page runs as written after python -m pip install hawkes-engine; see Installing hawkes-engine for the other ways to install it.

import numpy as np
import hawkes_engine as he
from hawkes_engine.diagnostics import ljung_box

mu = np.array([0.6, 0.9])
alpha = np.array([[0.10, 0.35], [0.20, 0.05]])  # row = target, column = source
beta = np.array([[1.30, 1.70], [1.30, 1.70]])
T = 20000.0

times, types = he.simulate(mu, alpha, beta, T=T, seed=1)
fit = he.fit(times, types, M=2, T=T, seed=1)
print(fit)
print("alpha_hat", fit.alpha.round(3).tolist(), "truth", alpha.tolist())
print("se(alpha)", fit.se["alpha"].round(3).tolist())
print("rho", round(fit.rho, 4), "95% interval", np.round(fit.rho_ci, 4).tolist())

gaps = he.time_rescale(times, types, fit.mu, fit.alpha, fit.beta)
print("KS p", he.ks_test(gaps).pvalue.round(3), "Ljung-Box p", ljung_box(gaps).pvalue.round(3))

answer = he.trust_lookup(N=len(times), rho_hat=fit.rho, beta=fit.beta.min(), T=T)
print(answer.status, answer.cell, round(answer.distance, 2))

On the reference machine (Windows 11, Python 3.12) this prints the following. The digits of the estimates can differ in the last places on another platform.

FitResult(M=2, n_params=10, loglik=-39142.4, rho=0.233095, converged, reliable='reliable')
alpha_hat [[0.123, 0.33], [0.182, 0.053]] truth [[0.1, 0.35], [0.2, 0.05]]
se(alpha) [[0.021, 0.018], [0.019, 0.016]]
rho 0.2331 95% interval [0.2115, 0.2547]
KS p [0.882 0.934] Ljung-Box p [0.729 0.617]
measured M2_N50000_rho0.3028_r0.0_c1.0 0.4

What each field means, and what it does not

simulate returns times (sorted, float64) and types (uint8, values 0..M-1). The generator is the library’s own, so the same seed reproduces the same path on every platform but does not match numpy.random.

fit returns a FitResult:

Field	What it is	What it is not
`mu`, `alpha`, `beta`	Maximum-likelihood estimates. `alpha[i, j]` is the excitation a type-`j` event applies to type `i`.	Not unbiased. The study measured bias in several regimes; see The trust map.
`se`	Square roots of the diagonal of the inverted observed information, in natural units. `None` when the information matrix cannot be inverted.	Not a measure of sampling spread. See the last paragraph below.
`rho`, `rho_ci`	Spectral radius of `alpha / beta` and a delta-method 95% interval.	The interval is first-order and is not valid at a boundary.
`converged`	The optimiser stopped at a point where the gradient is small.	Not a statement about the data.
`bound_hit`	A coordinate stopped on a search bound; the estimate is then a boundary value.
`reliable`	`"reliable"`, `"marginal"` or `"unreliable"`: a conditioning report built from the Hessian condition number, bound hits, `rho`, the alpha-beta correlation and events per parameter.	Not a statement about bias or coverage. A fit with a wild `beta` can carry `"reliable"`. See Limits.

time_rescale maps the events to gaps that are independent Exp(1) if the parameters are right. The Kolmogorov-Smirnov test checks their marginal law and the Ljung-Box test checks their independence. A p-value above 0.05 is the absence of evidence against the model. The parameters were fitted to the same events, so the nominal p-values are not calibrated, and Limits shows a fit the check passes that is far from the truth.

trust_lookup does not look at the fit’s data. It takes the fitted regime (number of events, rho, smallest decay rate, window length) and returns what the H6 study measured at the nearest grid cell, with the distance to that cell. When the regime is outside the measured box it says "unknown". See The trust map.

The standard errors understate sampling spread

The reported standard errors were measured to understate the sampling spread of the estimates: over the twelve two-type cells with at least 2000 events the pooled ratio of mean reported standard error to empirical standard deviation is 0.779 +/- 0.011, and 0.61 for the decay block alone. The finding, its limits and its evidence are on Limits.