nstat.extras.spatial.hawkes_bridge

Multivariate Hawkes process bridge via tick (optional).

Lazy bridge to the Hawkes estimators of tick (Bacry et al. 2018, JMLR 18; BSD-3) for self / mutually-exciting temporal point processes — functional-connectivity and triggering-kernel estimation for a multi-electrode ensemble.

Install

pip install nstat-toolbox[hawkes]

The fitted \(C \times C\) triggering matrix is the cell-averaged continuous triggering kernel: a propagating kernel \(\varphi(\tau, r) = \psi(\tau)\,\delta(r - v\tau)\) gives off-diagonal entries peaked at \(\tau \approx \|r_{cc'}\|/\|v\|\), the signature of a traveling wave at speed \(v\). This bridge is intentionally thin: it wraps tick’s exponential-kernel MLE and returns plain NumPy.

Note

Estimating inhibition (negative triggering) is hard and the exponential-kernel MLE here assumes excitation; see Bonnet (2023) for the inhibition-kernel difficulty. Confidence: high for excitatory exponential kernels; lower for inhibition.

Functions

bartlett_spectrum(triggering_matrix, ...[, ...])

Bartlett (frequency × wave-vector) spectrum of a Hawkes triggering kernel.

fit_hawkes_exp(event_times[, decay, ...])

Fit a multivariate Hawkes process with exponential kernels via tick.

Classes

HawkesFit(baseline, adjacency, decays, ...)

Fitted multivariate Hawkes parameters (plain NumPy).
class nstat.extras.spatial.hawkes_bridge.HawkesFit(baseline, adjacency, decays, n_channels)[source]

Bases: object

Fitted multivariate Hawkes parameters (plain NumPy).

Variables:

  • baseline (numpy.ndarray) – (C,) background rates \(\mu_c\).

  • adjacency (numpy.ndarray) – (C, C) branching / triggering matrix (integrated kernel norms) — entry [c, c'] is the expected number of events in channel c triggered by one event in channel c'.

  • decays (numpy.ndarray) – The exponential decay(s) used in the parametric kernel.

  • n_channels (int) – Number of channels C.

Parameters:
baseline: ndarray
adjacency: ndarray
decays: ndarray
n_channels: int
nstat.extras.spatial.hawkes_bridge.fit_hawkes_exp(event_times, decay=1.0, *, penalty='l2', C=1000.0, max_iter=200)[source]

Fit a multivariate Hawkes process with exponential kernels via tick.

Parameters:

  • event_times – Sequence of length C — one increasing 1-D array of event times (seconds) per channel.

  • decay (float | ndarray) – Exponential decay \(\beta\) (scalar, shared across channels).

  • penalty (str) – Regularization passed to tick ("l2" default; "l1" for sparse connectivity à la ADM4).

  • C (float) – Inverse regularization strength (tick convention).

  • max_iter (int) – Solver iterations.

Return type:

HawkesFit

Raises:

ImportError – If tick is not installed (with the [hawkes] install hint).

nstat.extras.spatial.hawkes_bridge.bartlett_spectrum(triggering_matrix, electrode_positions, freq_grid, wave_vector_grid, *, decay=1.0, return_complex=False)[source]

Bartlett (frequency × wave-vector) spectrum of a Hawkes triggering kernel.

Implements the §8.4 Bartlett spectrum of Daley & Vere-Jones (2003) for a multivariate Hawkes process whose pairwise triggering kernel is \(\varphi_{cc'}(\tau) = A_{cc'} \beta\,e^{-\beta\tau}\,1_{\tau\ge 0}\) (the parametric form returned by fit_hawkes_exp()). The spectral density at frequency \(f\) and wave vector \(\mathbf{k}\) is

\[S(f, \mathbf{k}) = \frac{1}{\beta + i\,2\pi f}\, \sum_{c,c'} A_{cc'}\,e^{-i\,\mathbf{k}\cdot(\mathbf{r}_c - \mathbf{r}_{c'})}.\]

A coherent propagating component \(A_{cc'} \propto \exp(-\beta\,\mathbf{r}_{cc'}\!\cdot\!\mathbf{v}/\|\mathbf{v}\|^2)\) produces a ridge \(|\mathbf{k}\,\|\mathbf{v}\|| = 2\pi f\) whose direction is \(\hat{\mathbf{v}}\) (Bacry-Mastromatteo-Muzy 2015).

Parameters:

  • triggering_matrix (ndarray) – (C, C) adjacency / integrated triggering matrix (e.g. HawkesFit.adjacency).

  • electrode_positions (ndarray) – (C, 2) planar electrode coordinates.

  • freq_grid (ndarray) – (Nf,) frequencies in Hz.

  • wave_vector_grid (ndarray) – (Nk, 2) wave vectors in rad / (position-unit). Speed is recovered as 2*pi*f / |k| with units position-unit / s.

  • decay (float | ndarray) – Exponential decay \(\beta\) (scalar) or per-pair (C, C) array of decays. Negative entries raise ValueError.

  • return_complex (bool) – If False (default), return the real, non-negative power \(|S(f, \mathbf{k})|^2\). If True, return the complex spectrum so callers can take phases / cross-spectra.

Returns:

(Nf, Nk) power (real, float) if return_complex=False, else (Nf, Nk) complex spectrum.

Return type:

np.ndarray

Raises:

ValueError – On shape mismatch or negative decay.

Warns:

UserWarning – If the adjacency matrix has spectral radius \(\ge 1\) (the Hawkes process is not stationary; the Bartlett formula assumes stationarity).

References

Daley DJ, Vere-Jones D (2003). An Introduction to the Theory of Point Processes, Vol. I, §8.4. Bacry E, Mastromatteo I, Muzy J-F (2015). Hawkes processes in finance. Market Microstructure and Liquidity 1(1):1550005. Hansen NR, Reynaud-Bouret P, Rivoirard V (2015). Lasso and probabilistic inequalities for multivariate point processes. Bernoulli 21(1):83.