mixle.process module¶

mixle.process — temporal / point-process families.

The objects that model event-time data: self-exciting Hawkes processes, inhomogeneous Poisson, the birth-death process, and the Chinese-restaurant process. The univariate event-time families share the TemporalPointProcess capability (intensity / expected_count). A re-export namespace pulling these out of stats/leaf so the temporal models are findable in one place (docs/ARCHITECTURE.md).

class HawkesProcessDistribution(mu, alpha, beta, window, name=None, keys=None)[source]

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)

intensity(t, times, marks=None)[source]

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)[source]

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)[source]

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

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

log_density(x)[source]

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

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

seq_log_density(x)[source]

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)[source]

Return a HawkesProcessSampler (Ogata thinning) for this distribution.

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

estimator(pseudo_count=None)[source]

Return a HawkesProcessEstimator over the same observation window.

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

dist_to_encoder()[source]

Returns a HawkesProcessDataEncoder bound to this window.

Return type:: HawkesProcessDataEncoder

class PowerLawHawkesDistribution(mu, A, c, p, window, *, alpha=0.0, mark_dist=None, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Marked power-law-kernel Hawkes process on a fixed window [0, window].

A realization is (times, marks) – a sorted event-time array and a matching mark array (use zeros, or omit, for the unmarked process). mu > 0 is the background rate, A >= 0 the productivity, alpha the mark sensitivity, and c > 0, p > 1 the Omori-Utsu kernel scale and exponent.

intensity(t, times, marks=None)[source]

The conditional rate lambda(t) given the catalogue so far – the instantaneous forecast.

Parameters:: t (float)
Return type:: float

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

Expected number of events in [t_start, t_end] given the catalogue – the window forecast.

Parameters:

t_start (float)
t_end (float)

Return type:

float

branching_ratio(mean_mark=0.0)[source]

Expected direct offspring per event A c/(p-1) e^{alpha * mean_mark} – criticality (<1 stable).

Parameters:: mean_mark (float)
Return type:: float

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Return type:: float

log_density(x)[source]

Exact log-likelihood of one realization on [0, window].

Return type:: float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

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

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

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

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: PowerLawHawkesDataEncoder

class MultivariateHawkesProcessDistribution(mu, alpha, beta, window, name=None, keys=None)[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)

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 a branching-EM estimator over the same window and dimension.

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 InhomogeneousPoissonProcessDistribution(rates, t_max=None, edges=None, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Inhomogeneous Poisson process with piecewise-constant intensity on a fixed window.

Parameters:

rates (Sequence[float] | ndarray)
t_max (float | None)
edges (Sequence[float] | ndarray | None)
name (str | None)
keys (str | None)

intensity(t, times=None, marks=None)[source]

Conditional rate lambda(t) = rates[bin containing t].

The inhomogeneous Poisson process is not self-exciting, so the rate depends only on t. times/marks are accepted for TemporalPointProcess signature parity and ignored. Raises ValueError for t outside the support [edges[0], edges[-1]].

Parameters:

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

Return type:

float

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

Compensator integral_{t_start}^{t_end} lambda(s) ds – the piecewise-rate integral.

Computed as sum_b rate_b * width(overlap([t_start, t_end], bin_b)). times/marks are accepted for signature parity and ignored. With t_start=edges[0], t_end=edges[-1] this returns the full integral sum_b rate_b width_b used by log_density.

Parameters:

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

Return type:

float

density(x)[source]

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

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

log_density(x)[source]

Log-likelihood of one realization: sum_b n_b log rate_b - sum_b rate_b width_b.

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

seq_log_density(x)[source]

Vectorized log-likelihood for a (num_realizations, num_bins) matrix of per-bin counts.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return an InhomogeneousPoissonProcessSampler for this distribution.

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

estimator(pseudo_count=None)[source]

Return an InhomogeneousPoissonProcessEstimator over the same bin edges.

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

dist_to_encoder()[source]

Returns an InhomogeneousPoissonProcessDataEncoder bound to these bin edges.

Return type:: InhomogeneousPoissonProcessDataEncoder

class RenewalProcessDistribution(interarrival, window, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Renewal process with i.i.d. inter-arrivals interarrival observed on [0, window].

Parameters:

interarrival (Any)
window (float)
name (str | None)
keys (str | None)

log_density(x)[source]

Exact log-likelihood of one realization (observed gaps + censored survival).

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

seq_log_density(x)[source]

Vectorized log-likelihood for encoded realizations (flattened gaps + per-realization survival).

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

sampler(seed=None)[source]

Return a sampler that draws gaps until the cumulative time exceeds window.

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

estimator(pseudo_count=None)[source]

Return an estimator that fits the inter-arrival distribution to the observed gaps.

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

dist_to_encoder()[source]

Return the data encoder (delegates gap encoding to the inter-arrival encoder).

Return type:: RenewalProcessDataEncoder

class BirthDeathSamplingDistribution(birth_rate, death_rate, sampling_rate=0.0, initial_population=1, horizon=10.0, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

General linear birth-death-sampling process (fossilized birth-death is the sampling_rate>0 case).

Parameters:

birth_rate (float)
death_rate (float)
sampling_rate (float)
initial_population (int)
horizon (float)
name (str | None)
keys (str | None)

density(x)[source]

Probability density of one trajectory (see log_density).

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

log_density(x)[source]

Log-likelihood of one fully-observed trajectory (n0, T, events).

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

seq_log_density(x)[source]

Vectorized log-likelihood for an (N, 5) array of per-trajectory sufficient statistics.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a BirthDeathSamplingSampler for this distribution.

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

estimator(pseudo_count=None)[source]

Return a BirthDeathSamplingEstimator (closed-form rate MLE).

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

dist_to_encoder()[source]

Returns a BirthDeathSamplingDataEncoder object.

Return type:: BirthDeathSamplingDataEncoder

class ChineseRestaurantProcessDistribution(alpha, n, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

CRP distribution over partitions of n items with concentration alpha > 0.

Parameters:

alpha (float)
n (int)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability of the partition encoded by label vector x.

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

log_density(x)[source]

Return the Ewens log-probability of the partition that label vector x induces.

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

seq_log_density(x)[source]

Return the Ewens log-probability for a list of partition label vectors.

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

sampler(seed=None)[source]

Return a sampler that draws partitions by the sequential CRP rule.

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

estimator(pseudo_count=None)[source]

Return a maximum-likelihood estimator for the concentration alpha at fixed n.

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

dist_to_encoder()[source]

Return the data encoder (passes label vectors through).

Return type:: ChineseRestaurantProcessDataEncoder