bdms.poisson#

Abstract base classes for defining general Poisson point processes on bdms.TreeNode state spaces. Several concrete child classes are included.

These classes are used to define rate-driven processes—such as birth, death, and mutation—for simulations with bdms.TreeNode.evolve.

Example

>>> import bdms

Define a two-state process.

>>> poisson_process = bdms.poisson.DiscreteProcess({"a": 1.0, "b": 2.0})

Sample waiting times for each state.

>>> for state in poisson_process.rates:  
...     print(state, poisson_process.waiting_time_rv(state, 0.0, seed=0))
a 0.6799...
b 0.3399...

Module Contents#

Classes#

Process

Abstract base class for Poisson point processes on bdms.TreeNode

HomogeneousProcess

Abstract base class for homogenous Poisson processes.

ConstantProcess

A process with a specified constant rate (independent of state).

DiscreteProcess

A homogeneous process at each of \(d\) states.

InhomogeneousProcess

Abstract base class for homogenous Poisson processes.
class bdms.poisson.Process(attr='state')#

Bases: abc.ABC

Inheritance diagram of bdms.poisson.Process

Abstract base class for Poisson point processes on bdms.TreeNode attributes.

Parameters:

attr (str) – The name of the bdms.TreeNode attribute to access.

abstract λ(x, t)#

The Poisson intensity \(\lambda(x, t)\) for state \(x\) at time \(t\).

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity at.

  • t (float) – Time to evaluate Poisson intensity at (0.0 corresponds to the root). This only has an effect if the process is time-inhomogeneous.

Returns:

The Poisson intensity \(\lambda(x, t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

abstract Λ(x, t, Δt)#

Evaluate the Poisson intensity measure of state \(x\) and time interval \([t, t+Δt)\), defined as.

\[\Lambda(x, t, Δt) = \int_{t}^{t+Δt} \lambda(x, s)ds,\]

This is needed for sampling waiting times and evaluating the log probability density function of waiting times.

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity measure at.

  • t (float) – Start time.

  • Δt (float) – Time interval duration.

Returns:

The Poisson intensity measure \(\Lambda(x, t, \Delta t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

abstract Λ_inv(x, t, τ)#

Evaluate the inverse function wrt \(\Delta t\) of Process.Λ(), \(\Lambda_t^{-1}(x, t, \tau)\), such that \(\Lambda_t^{-1}(x, t, \Lambda(x, t, t+\Delta t)) = \Delta t\). This is needed for sampling waiting times. Note that \(\Lambda_t^{-1}\) is well-defined iff \(\lambda(x, t) > 0\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Start time of the interval.

  • τ (float) – Poisson intensity measure of the interval.

Returns:

The inverse Poisson intensity measure \(\Lambda_t^{-1}(x, t, \tau)\).

Return type:

numpy.typing.NDArray[numpy.float64]

waiting_time_rv(x, t, rate_multiplier=1.0, seed=None)#

Sample the waiting time \(\Delta t\) until the first event, given the process on state \(x\) starting at time \(t\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Time at which to start waiting.

  • rate_multiplier (float) – A constant by which to multiply the Poisson intensity

  • seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Returns:

Waiting time \(\Delta t\).

Return type:

numpy.typing.NDArray[numpy.float64]

class bdms.poisson.HomogeneousProcess(attr='state')#

Bases: Process

Inheritance diagram of bdms.poisson.HomogeneousProcess

Abstract base class for homogenous Poisson processes.

Parameters:

attr (str) –

abstract λ_homogeneous(x)#

Evaluate homogeneous Poisson intensity \(\lambda(x)\) for state \(x\).

Parameters:

x (Hashable | Sequence[Hashable] | numpy.typing.NDArray[Any]) – State to evaluate Poisson intensity at.

Returns:

The Poisson intensity \(\lambda(x)\).

Return type:

numpy.typing.NDArray[numpy.float64]

λ(x, t)#

The Poisson intensity \(\lambda(x, t)\) for state \(x\) at time \(t\).

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity at.

  • t (float) – Time to evaluate Poisson intensity at (0.0 corresponds to the root). This only has an effect if the process is time-inhomogeneous.

Returns:

The Poisson intensity \(\lambda(x, t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

Λ(x, t, Δt)#

Evaluate the Poisson intensity measure of state \(x\) and time interval \([t, t+Δt)\), defined as.

\[\Lambda(x, t, Δt) = \int_{t}^{t+Δt} \lambda(x, s)ds,\]

This is needed for sampling waiting times and evaluating the log probability density function of waiting times.

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity measure at.

  • t (float) – Start time.

  • Δt (float) – Time interval duration.

Returns:

The Poisson intensity measure \(\Lambda(x, t, \Delta t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

Λ_inv(x, t, τ)#

Evaluate the inverse function wrt \(\Delta t\) of Process.Λ(), \(\Lambda_t^{-1}(x, t, \tau)\), such that \(\Lambda_t^{-1}(x, t, \Lambda(x, t, t+\Delta t)) = \Delta t\). This is needed for sampling waiting times. Note that \(\Lambda_t^{-1}\) is well-defined iff \(\lambda(x, t) > 0\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Start time of the interval.

  • τ (float) – Poisson intensity measure of the interval.

Returns:

The inverse Poisson intensity measure \(\Lambda_t^{-1}(x, t, \tau)\).

Return type:

numpy.typing.NDArray[numpy.float64]

waiting_time_rv(x, t, rate_multiplier=1.0, seed=None)#

Sample the waiting time \(\Delta t\) until the first event, given the process on state \(x\) starting at time \(t\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Time at which to start waiting.

  • rate_multiplier (float) – A constant by which to multiply the Poisson intensity

  • seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Returns:

Waiting time \(\Delta t\).

Return type:

numpy.typing.NDArray[numpy.float64]

class bdms.poisson.ConstantProcess(value=1.0)#

Bases: HomogeneousProcess

Inheritance diagram of bdms.poisson.ConstantProcess

A process with a specified constant rate (independent of state).

Parameters:

value (float) – Constant rate.

λ_homogeneous(x)#

Evaluate homogeneous Poisson intensity \(\lambda(x)\) for state \(x\).

Parameters:

x (Hashable | Sequence[Hashable] | numpy.typing.NDArray[Any]) – State to evaluate Poisson intensity at.

Returns:

The Poisson intensity \(\lambda(x)\).

Return type:

numpy.typing.NDArray[numpy.float64]

λ(x, t)#

The Poisson intensity \(\lambda(x, t)\) for state \(x\) at time \(t\).

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity at.

  • t (float) – Time to evaluate Poisson intensity at (0.0 corresponds to the root). This only has an effect if the process is time-inhomogeneous.

Returns:

The Poisson intensity \(\lambda(x, t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

Λ(x, t, Δt)#

Evaluate the Poisson intensity measure of state \(x\) and time interval \([t, t+Δt)\), defined as.

\[\Lambda(x, t, Δt) = \int_{t}^{t+Δt} \lambda(x, s)ds,\]

This is needed for sampling waiting times and evaluating the log probability density function of waiting times.

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity measure at.

  • t (float) – Start time.

  • Δt (float) – Time interval duration.

Returns:

The Poisson intensity measure \(\Lambda(x, t, \Delta t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

Λ_inv(x, t, τ)#

Evaluate the inverse function wrt \(\Delta t\) of Process.Λ(), \(\Lambda_t^{-1}(x, t, \tau)\), such that \(\Lambda_t^{-1}(x, t, \Lambda(x, t, t+\Delta t)) = \Delta t\). This is needed for sampling waiting times. Note that \(\Lambda_t^{-1}\) is well-defined iff \(\lambda(x, t) > 0\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Start time of the interval.

  • τ (float) – Poisson intensity measure of the interval.

Returns:

The inverse Poisson intensity measure \(\Lambda_t^{-1}(x, t, \tau)\).

Return type:

numpy.typing.NDArray[numpy.float64]

waiting_time_rv(x, t, rate_multiplier=1.0, seed=None)#

Sample the waiting time \(\Delta t\) until the first event, given the process on state \(x\) starting at time \(t\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Time at which to start waiting.

  • rate_multiplier (float) – A constant by which to multiply the Poisson intensity

  • seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Returns:

Waiting time \(\Delta t\).

Return type:

numpy.typing.NDArray[numpy.float64]

class bdms.poisson.DiscreteProcess(rates, attr='state')#

Bases: HomogeneousProcess

Inheritance diagram of bdms.poisson.DiscreteProcess

A homogeneous process at each of \(d\) states.

Parameters:
λ_homogeneous(x)#

Evaluate homogeneous Poisson intensity \(\lambda(x)\) for state \(x\).

Parameters:

x (Hashable | Sequence[Hashable] | numpy.typing.NDArray[Any]) – State to evaluate Poisson intensity at.

Returns:

The Poisson intensity \(\lambda(x)\).

Return type:

numpy.typing.NDArray[numpy.float64]

λ(x, t)#

The Poisson intensity \(\lambda(x, t)\) for state \(x\) at time \(t\).

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity at.

  • t (float) – Time to evaluate Poisson intensity at (0.0 corresponds to the root). This only has an effect if the process is time-inhomogeneous.

Returns:

The Poisson intensity \(\lambda(x, t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

Λ(x, t, Δt)#

Evaluate the Poisson intensity measure of state \(x\) and time interval \([t, t+Δt)\), defined as.

\[\Lambda(x, t, Δt) = \int_{t}^{t+Δt} \lambda(x, s)ds,\]

This is needed for sampling waiting times and evaluating the log probability density function of waiting times.

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity measure at.

  • t (float) – Start time.

  • Δt (float) – Time interval duration.

Returns:

The Poisson intensity measure \(\Lambda(x, t, \Delta t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

Λ_inv(x, t, τ)#

Evaluate the inverse function wrt \(\Delta t\) of Process.Λ(), \(\Lambda_t^{-1}(x, t, \tau)\), such that \(\Lambda_t^{-1}(x, t, \Lambda(x, t, t+\Delta t)) = \Delta t\). This is needed for sampling waiting times. Note that \(\Lambda_t^{-1}\) is well-defined iff \(\lambda(x, t) > 0\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Start time of the interval.

  • τ (float) – Poisson intensity measure of the interval.

Returns:

The inverse Poisson intensity measure \(\Lambda_t^{-1}(x, t, \tau)\).

Return type:

numpy.typing.NDArray[numpy.float64]

waiting_time_rv(x, t, rate_multiplier=1.0, seed=None)#

Sample the waiting time \(\Delta t\) until the first event, given the process on state \(x\) starting at time \(t\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Time at which to start waiting.

  • rate_multiplier (float) – A constant by which to multiply the Poisson intensity

  • seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Returns:

Waiting time \(\Delta t\).

Return type:

numpy.typing.NDArray[numpy.float64]

class bdms.poisson.InhomogeneousProcess(attr='state', quad_kwargs={}, root_kwargs={})#

Bases: Process

Inheritance diagram of bdms.poisson.InhomogeneousProcess

Abstract base class for homogenous Poisson processes.

Default implementations of Λ() and Λ_inv() use quadrature and root-finding, respectively. You may wish to override these methods in a child clasee for better performance, if analytical forms are available.

Parameters:
abstract λ_inhomogeneous(x, t)#

Evaluate inhomogeneous Poisson intensity \(\lambda(x, t)\) given state \(x\).

Parameters:

  • x (Hashable) – Attribute value to evaluate Poisson intensity at.

  • t (float) – Time at which to evaluate Poisson intensity.

Returns:

The Poisson intensity \(\lambda(x, t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

λ(x, t)#

The Poisson intensity \(\lambda(x, t)\) for state \(x\) at time \(t\).

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity at.

  • t (float) – Time to evaluate Poisson intensity at (0.0 corresponds to the root). This only has an effect if the process is time-inhomogeneous.

Returns:

The Poisson intensity \(\lambda(x, t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

Λ(x, t, Δt)#

Evaluate the Poisson intensity measure of state \(x\) and time interval \([t, t+Δt)\), defined as.

\[\Lambda(x, t, Δt) = \int_{t}^{t+Δt} \lambda(x, s)ds,\]

This is needed for sampling waiting times and evaluating the log probability density function of waiting times.

Parameters:

  • x (Hashable) – State to evaluate Poisson intensity measure at.

  • t (float) – Start time.

  • Δt (float) – Time interval duration.

Returns:

The Poisson intensity measure \(\Lambda(x, t, \Delta t)\).

Return type:

numpy.typing.NDArray[numpy.float64]

Λ_inv(x, t, τ)#

Evaluate the inverse function wrt \(\Delta t\) of Process.Λ(), \(\Lambda_t^{-1}(x, t, \tau)\), such that \(\Lambda_t^{-1}(x, t, \Lambda(x, t, t+\Delta t)) = \Delta t\). This is needed for sampling waiting times. Note that \(\Lambda_t^{-1}\) is well-defined iff \(\lambda(x, t) > 0\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Start time of the interval.

  • τ (float) – Poisson intensity measure of the interval.

Returns:

The inverse Poisson intensity measure \(\Lambda_t^{-1}(x, t, \tau)\).

Return type:

numpy.typing.NDArray[numpy.float64]

waiting_time_rv(x, t, rate_multiplier=1.0, seed=None)#

Sample the waiting time \(\Delta t\) until the first event, given the process on state \(x\) starting at time \(t\).

Parameters:

  • x (Hashable) – State.

  • t (float) – Time at which to start waiting.

  • rate_multiplier (float) – A constant by which to multiply the Poisson intensity

  • seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Returns:

Waiting time \(\Delta t\).

Return type:

numpy.typing.NDArray[numpy.float64]