mixle.stats.processes.hawkes_process module

Evaluate, estimate, and sample from a univariate Hawkes process with an exponential kernel.

Defines HawkesProcessDistribution, HawkesProcessSampler, HawkesProcessAccumulatorFactory, HawkesProcessAccumulator, HawkesProcessEstimator, and HawkesProcessDataEncoder.

A Hawkes process is a self-exciting temporal point process: every event transiently raises the intensity of future events. With the exponential triggering kernel g(s) = alpha * exp(-beta s) the conditional intensity given the history is

lambda(t) = mu + sum_{t_j < t} alpha * exp(-beta (t - t_j)),

with background rate mu > 0, excitation jump alpha >= 0, and decay rate beta > 0. The branching ratio alpha / beta is the expected number of direct offspring per event; the process is sub-critical (stationary) when alpha < beta.

Data type: each observation is a 1-D array/list of event times, sorted, lying in the fixed window [0, window]. The exact log-likelihood of one realization t_1 < ... < t_n is the standard point-process log-likelihood sum_i log lambda(t_i) - integral_0^window lambda(s) ds:

sum_i log(mu + alpha R_i) - mu*window - (alpha/beta) sum_i (1 - exp(-beta (window - t_i))),

where R_i = sum_{j<i} exp(-beta (t_i - t_j)) obeys the O(n) recursion R_i = exp(-beta (t_i - t_{i-1})) (R_{i-1} + 1) (R_1 = 0).

Fitting retains the weighted realizations and maximizes this exact finite-window likelihood, including the edge-dependent integrated-kernel term. This is not the common edge-free branching approximation: a Poisson boundary fit (alpha=0) and an unconstrained finite-window supercritical fit are both representable.

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

class HawkesProcessStatistics(realizations, weights, window)

Bases: NamedTuple

Versioned weighted event evidence for exact finite-window fitting.

Parameters:

• realizations (tuple[ndarray, ...])

• weights (ndarray)

• window (float)

realizations: tuple[ndarray, ...]

Alias for field number 0

weights: ndarray

Alias for field number 1

window: float

Alias for field number 2

property schema_version: int

Return the serialized-statistic schema version.

class HawkesProcessDistribution(mu, alpha, beta, window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)

Bases: SequenceEncodableProbabilityDistribution

Univariate Hawkes process with an exponential excitation kernel on a fixed window.

Parameters:

• mu (float)

• alpha (float)

• beta (float)

• window (float)

• name (str | None)

• keys (str | None)

• max_events (int)

intensity(t, times, marks=None)

Conditional rate lambda(t) = mu + alpha sum_{t_i < t} exp(-beta (t - t_i)) given the history.

times is the event history; marks is accepted for TemporalPointProcess signature parity (the univariate Hawkes process is unmarked) and is ignored.

Parameters:

• t (float)

• times (Any)

• marks (Any)

Return type:

float

expected_count(t_start, t_end, times, marks=None)

Compensator integral_{t_start}^{t_end} lambda(s) ds of the intensity given the history.

marks is accepted for signature parity and ignored (the univariate process is unmarked).

Parameters:

• t_start (float)

• t_end (float)

• times (Any)

• marks (Any)

Return type:

float

density(x)

Probability density of one realization x (a sequence of event times).

Parameters:

x (Any)

Return type:

float

log_density(x)

Exact log-likelihood of one realization (a strictly increasing event-time sequence in [0, window]).

The conditional intensity is defined over the strict history t_j < t (see the class docstring), so a realization with a tied timestamp pair (t_j == t_i for j != i) is not a valid t_1 < ... < t_n history – like any other malformed ordering, it scores -inf rather than silently letting one of the tied events excite the other.

Parameters:

x (Any)

Return type:

float

seq_log_density(x)

Vectorized exact log-likelihood over a padded (num_realizations, max_len) time matrix.

Parameters:

x (tuple[ndarray, ndarray, float])

Return type:

ndarray

sampler(seed=None)

Return a HawkesProcessSampler (Ogata thinning) for this distribution.

Parameters:

seed (int | None)

Return type:

HawkesProcessSampler

estimator(pseudo_count=None)

Return a HawkesProcessEstimator over the same observation window.

Parameters:

pseudo_count (float | None)

Return type:

HawkesProcessEstimator

dist_to_encoder()

Returns a HawkesProcessDataEncoder bound to this window.

Return type:

HawkesProcessDataEncoder

class HawkesProcessSampler(dist, seed=None)

Bases: DistributionSampler

Draw realizations on [0, window] by Ogata’s thinning algorithm.

Parameters:

• dist (HawkesProcessDistribution)

• seed (int | None)

sample(size=None, *, batched=True)

Draw one realization (event-time array) or a list of size realizations.

Parameters:

• size (int | None)

• batched (bool)

Return type:

ndarray | list[ndarray]

class HawkesProcessAccumulator(window, name=None, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Retain validated weighted realizations for exact finite-window MLE.

Parameters:

• window (float)

• name (str | None)

• keys (str | None)

update(x, weight, estimate)

Store one validated weighted realization.

Parameters:

• x (Any)

• weight (float)

• estimate (HawkesProcessDistribution | None)

Return type:

None

initialize(x, weight, rng)

Store one validated weighted realization during initialization.

Parameters:

• x (Any)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Store validated encoded realizations and aligned weights.

Parameters:

• x (tuple[ndarray, ndarray, float])

• weights (ndarray)

• estimate (HawkesProcessDistribution)

Return type:

None

seq_initialize(x, weights, rng)

Store validated encoded realizations during initialization.

Parameters:

• x (tuple[ndarray, ndarray, float])

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge validated serialized Hawkes evidence.

Parameters:

suff_stat (Any)

Return type:

HawkesProcessAccumulator

value()

Return owned, versioned weighted realization evidence.

Return type:

HawkesProcessStatistics

from_value(x)

Restore validated serialized Hawkes evidence.

Parameters:

x (Any)

Return type:

HawkesProcessAccumulator

scale(c)

Scale realization weights by a finite non-negative constant.

Parameters:

c (float)

Return type:

HawkesProcessAccumulator

key_merge(stats_dict)

Merge this evidence under its shared parameter key.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this evidence from its shared parameter key.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return an encoder that pads event-time realizations for this window.

Return type:

HawkesProcessDataEncoder

class HawkesProcessAccumulatorFactory(window, name=None, keys=None)

Bases: StatisticAccumulatorFactory

Factory for HawkesProcessAccumulator.

Parameters:

• window (float)

• name (str | None)

• keys (str | None)

make()

Create an empty Hawkes process accumulator.

Return type:

HawkesProcessAccumulator

class HawkesProcessEstimator(window, name=None, keys=None, max_events=_DEFAULT_MAX_EVENTS)

Bases: ParameterEstimator

Exact weighted finite-window maximum-likelihood estimator.

Parameters:

• window (float)

• name (str | None)

• keys (str | None)

• max_events (int)

accumulator_factory()

Return a factory for Hawkes EM sufficient-statistic accumulators.

Return type:

HawkesProcessAccumulatorFactory

estimate(nobs, suff_stat)

Maximize the exact compensator-aware weighted log-likelihood.

Parameters:

• nobs (float | None)

• suff_stat (Any)

Return type:

HawkesProcessDistribution

class HawkesProcessDataEncoder(window)

Bases: DataSequenceEncoder

Encode realizations (event-time arrays) into a padded (num_realizations, max_len) matrix.

Parameters:

window (float)

seq_encode(x)

Encode event-time realizations as padded times, lengths, and window.

Raises:

ValueError – If any realization has a non-finite, out-of-window, or non-strictly-increasing time (including a tied timestamp pair) – the conditional intensity is only defined over the strict history t_j < t, so t_j == t_i is not a valid history.

Parameters:

x (Sequence[Any])

Return type:

tuple[ndarray, ndarray, float]

row_count(x)

Return the validated number of encoded realizations.

Parameters:

x (Any)

Return type:

int