mixle.stats.processes.multivariate_hawkes module¶

Multivariate (mutually-exciting) Hawkes process with an exponential kernel.

A D-dimensional Hawkes process over marked events (t, mark) on a fixed window [0, T]. Each mark has a baseline intensity mu_d and an event of mark j excites the intensity of mark d by alpha_{dj} exp(-beta (t - t_k)), so

lambda_d(t) = mu_d + sum_{t_k < t} alpha_{d, mark_k} exp(-beta (t - t_k)),

coupling the dimensions through the D x D excitation matrix alpha (a shared decay beta). The exact log-likelihood sum_n log lambda_{mark_n}(t_n) - sum_d \int_0^T lambda_d is computed in O(n D) by a per-mark excitation recursion, sampling is by multivariate Ogata thinning, and the parameters are fit by direct maximization of this exact finite-window likelihood. The fit does not silently project the excitation matrix into the stationary region: finite-window supercritical models are representable. The process is stationary when the spectral radius of alpha / beta is below 1.

Reference: Hawkes, ‘Spectra of some self-exciting and mutually exciting point processes’, Biometrika (1971).

class MultivariateHawkesProcessStatistics(realizations, weights, dim, window)[source]

Bases: NamedTuple

Versioned weighted marked-event evidence.

Parameters:

realizations (tuple[ndarray, ...])
weights (ndarray)
dim (int)
window (float)

realizations: tuple[ndarray, ...]: Alias for field number 0

weights: ndarray: Alias for field number 1

dim: int: Alias for field number 2

window: float: Alias for field number 3

property schema_version: int: Return the serialized-statistic schema version.

class MultivariateHawkesProcessDistribution(mu, alpha, beta, window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)[source]

Bases: SequenceEncodableProbabilityDistribution

Multivariate Hawkes process: baselines mu (D), excitation alpha (D, D), decay beta.

Parameters:

mu (ndarray)
alpha (ndarray)
beta (float)
window (float)
name (str | None)
keys (str | None)
max_events (int)

intensity(t, times, marks)[source]

Per-mark conditional rate vector (the vector-valued variant of intensity).

Returns lambda(t) of shape (D,) with lambda_k(t) = mu_k + sum_{(t_i, m_i) < t} alpha[k, m_i] exp(-beta (t - t_i)).

Parameters:

t (float)
times (Any)
marks (Any)

Return type:

ndarray

expected_count(t_start, t_end, times, marks)[source]

Per-mark compensator vector (the vector-valued variant of expected_count).

Returns (D,) with the integral of lambda_k over [t_start, t_end] given the history.

Parameters:

t_start (float)
t_end (float)
times (Any)
marks (Any)

Return type:

ndarray

density(x)[source]

Probability density of one realization (a sequence of (time, mark) events).

Parameters:: x (Any)
Return type:: float

log_density(x)[source]

Exact log-likelihood of one realization of marked events sorted by time.

Parameters:: x (Any)
Return type:: float

seq_log_density(x)[source]

Log-likelihood for a list of realizations.

Parameters:: x (list[Any])
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler (multivariate Ogata thinning).

Parameters:: seed (int | None)
Return type:: MultivariateHawkesProcessSampler

estimator(pseudo_count=None)[source]

Return an exact finite-window estimator.

Parameters:: pseudo_count (float | None)
Return type:: MultivariateHawkesProcessEstimator

dist_to_encoder()[source]

Return the data encoder (passes realizations through; the likelihood is per-realization).

Return type:: MultivariateHawkesProcessDataEncoder

class MultivariateHawkesProcessSampler(dist, seed=None)[source]

Bases: DistributionSampler

Draw realizations by multivariate Ogata thinning.

Parameters:

dist (MultivariateHawkesProcessDistribution)
seed (int | None)

sample(size=None, *, batched=True)[source]

Draw one marked-event realization, or size iid realizations.

Parameters:

size (int | None)
batched (bool)

class MultivariateHawkesProcessAccumulator(dim, window, name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Retain validated weighted realizations for exact finite-window MLE.

Parameters:

dim (int)
window (float)
name (str | None)
keys (str | None)

update(x, weight, estimate)[source]

Store one validated weighted realization.

Parameters:

x (Any)
weight (float)
estimate (MultivariateHawkesProcessDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]

Store one validated weighted realization during initialization.

Parameters:

x (Any)
weight (float)
rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)[source]

Store an exactly aligned batch of weighted realizations.

Parameters:

x (list[Any])
weights (ndarray)
estimate (MultivariateHawkesProcessDistribution)

Return type:

None

seq_initialize(x, weights, rng)[source]

Store an aligned batch during initialization.

Parameters:

x (list[Any])
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Merge validated serialized marked-event evidence.

Parameters:: suff_stat (Any)
Return type:: MultivariateHawkesProcessAccumulator

value()[source]

Return owned, versioned marked-event evidence.

Return type:: MultivariateHawkesProcessStatistics

from_value(x)[source]

Replace contents from validated serialized evidence.

Parameters:: x (Any)
Return type:: MultivariateHawkesProcessAccumulator

scale(c)[source]

Scale realization weights by a finite non-negative constant.

Parameters:: c (float)
Return type:: MultivariateHawkesProcessAccumulator

key_merge(stats_dict)[source]

Merge this evidence under its shared parameter key.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

key_replace(stats_dict)[source]

Replace this evidence from its shared parameter key.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

acc_to_encoder()[source]

Return the marked-event encoder used by this accumulator.

Return type:: MultivariateHawkesProcessDataEncoder

class MultivariateHawkesProcessAccumulatorFactory(dim, window, name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for MultivariateHawkesProcessAccumulator.

Parameters:

dim (int)
window (float)
name (str | None)
keys (str | None)

make()[source]

Create a fresh multivariate-Hawkes accumulator.

Return type:: MultivariateHawkesProcessAccumulator

class MultivariateHawkesProcessEstimator(dim, window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)[source]

Bases: ParameterEstimator

Exact weighted finite-window maximum-likelihood estimator.

Parameters:

dim (int)
window (float)
name (str | None)
keys (str | None)
max_events (int)

accumulator_factory()[source]

Return an accumulator factory for branching EM statistics.

Return type:: MultivariateHawkesProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Maximize the exact compensator-aware weighted log-likelihood.

Parameters:

nobs (float | None)
suff_stat (Any)

Return type:

MultivariateHawkesProcessDistribution

class MultivariateHawkesProcessDataEncoder(window, dim)[source]

Bases: DataSequenceEncoder

Validate and pass through realizations of marked events.

Parameters:

window (float)
dim (int)

seq_encode(x)[source]

Validate and normalize marked-event realizations.

Parameters:: x (Sequence[Any])
Return type:: list[Any]

row_count(x)[source]

Return the number of validated encoded realizations.

Parameters:: x (Any)
Return type:: int