Pomp Class¶

class pypomp.Pomp(ys: DataFrame, theta: PompParameters, statenames: tuple[str, ...] | list[str], t0: float, rinit: Callable, rproc: Callable, dmeas: Callable | None = None, rmeas: Callable | None = None, par_trans: ParTrans | None = None, nstep: int | None = None, dt: float | None = None, accumvars: tuple[str, ...] | list[str] | None = None, covars: DataFrame | None = None, validate_logic: bool = True, order: str = 'linear')[source]¶

Bases: PompEstimationMixin, PompAnalysisMixin

Define and fit a partially observed Markov process (POMP) model.

A POMP model describes a time series whose latent state evolves according to a Markov process that is only partially observable through noisy measurements. This class encapsulates the four model components — initial state distribution (rinit), state transition (rproc), measurement density (dmeas), and measurement simulator (rmeas) — and exposes methods for simulation, particle filtering, iterated filtering, and gradient-based training.

Important

The rinit, rproc, dmeas, and rmeas arguments expect user-defined functions with specific argument names and type hints. The Pomp object raises an error at construction time if these functions do not conform to the specification.

rinit: See State Initialization (rinit).
rproc: See State Transition (rproc).
dmeas: See Measurement Density (dmeas).
rmeas: See Measurement Simulator (rmeas).

Parameters:

ys (pd.DataFrame) – Measurement data frame. The index must contain the observation times as numeric values.
theta (PompParameters) – Initial parameter set(s). Pass a PompParameters object with multiple parameter sets to run estimation methods in parallel over multiple starting points.
statenames (list of str) – Names of all latent state variables in the process model.
t0 (float) – Initial time for the model, typically just before the first observation.
rinit (callable) – Initial state simulator. See State Initialization (rinit) for the required signature.
rproc (callable) – State transition simulator for a single time step. See State Transition (rproc) for the required signature.
dmeas (callable or None, optional) – Measurement log-density function. Required for particle filtering and iterated filtering. See Measurement Density (dmeas).
rmeas (callable or None, optional) – Measurement simulator. Required for simulate(). See Measurement Simulator (rmeas).
par_trans (ParTrans or None, optional) – Parameter transformation object mapping between the natural parameter space and the estimation space. Defaults to the identity transformation.
covars (pd.DataFrame or None, optional) – Time-varying covariate data frame. The index must contain numeric covariate times. Interpolated to the integration grid at runtime.
nstep (int or None, optional) – Number of Euler integration steps between consecutive observations. Mutually exclusive with dt.
dt (float or None, optional) – Fixed integration step size. Mutually exclusive with nstep.
accumvars (list of str or None, optional) – Names of accumulator state variables (e.g. incidence counters) that are reset to zero at the start of each observation interval.
validate_logic (bool, optional) – Whether to validate model component function signatures and logic at construction time. Defaults to True.
order (str, optional) – Covariate interpolation method: "linear" (default) or "constant" (left-step).

Examples

Build a minimal SIR-like POMP model:

>>> import pandas as pd
>>> import jax
>>> import pypomp as pp
>>> from pypomp.types import StateDict, ParamDict, TimeFloat, StepSizeFloat, RNGKey, ObservationDict
>>>
>>> def my_rinit(theta_: ParamDict, t0: TimeFloat, key: RNGKey) -> StateDict:
...     return {"S": 990.0, "I": 10.0, "R": 0.0}
>>>
>>> def my_rproc(X_: StateDict, theta_: ParamDict, t: TimeFloat, dt: StepSizeFloat, key: RNGKey) -> StateDict:
...     return X_  # identity placeholder
>>>
>>> def my_dmeas(Y_: ObservationDict, X_: StateDict, theta_: ParamDict, t: TimeFloat) -> float:
...     import jax.numpy as jnp
...     return jnp.array(0.0)
>>>
>>> ys = pd.DataFrame({"cases": [10, 12, 15]}, index=[1.0, 2.0, 3.0])
>>> theta = pp.PompParameters({"beta": 0.5, "gamma": 0.1})
>>> model = pp.Pomp(
...     ys=ys, theta=theta, statenames=["S", "I", "R"], t0=0.0,
...     rinit=my_rinit, rproc=my_rproc, dmeas=my_dmeas, dt=0.1,
... )

See also

pypomp.panel.PanelPomp: Multi-unit panel extension of this class.
pypomp.core.parameters.PompParameters: Parameter container for single-unit models.

Attributes

Pomp.ys: DataFrame¶: The measurement data frame with observation times as the index.

Pomp.theta¶

The current parameter set for the model.

Returns:: The active PompParameters object.
Return type:: PompParameters
Raises:: ValueError – If theta has not been set.

Pomp.canonical_param_names: list[str]¶: Ordered list of parameter names used throughout the model.

Pomp.statenames: list[str]¶: Names of all latent state variables in the process model.

Pomp.t0: float¶: Initial time for the model (typically before the first observation).

Pomp.rinit: _RInit¶: Simulator for the initial state distribution.

Pomp.rproc: _RProc¶: Process model simulator handling state transitions between observation times.

Pomp.dmeas: _DMeas | None¶: Measurement density used to evaluate the likelihood of observations.

Pomp.rmeas: _RMeas | None¶: Measurement simulator used to generate synthetic observations.

Pomp.par_trans: ParTrans¶: Parameter transformation object mapping between natural and estimation spaces.

Pomp.covars: DataFrame | None¶: Time-varying covariates for the model, if applicable.

Pomp.accumvars: list[str] | None¶: Names of accumulator state variables that are reset at each observation time.

Pomp.results_history: ResultsHistory¶: A ResultsHistory object storing the history of results from pfilter(), mif(), and train() calls.

Pomp.fresh_key: Array | None¶: Running a method that accepts a JAX PRNG key will store a fresh, unused key here.

Pomp.metadata: ModelMetadata¶: Environment and version metadata initialized when this instance was built.

Core Algorithmic Methods

`simulate`([key, theta, times, nsim, as_pomp])	Simulate latent states and observations from the POMP model.
`pfilter`(J[, key, theta, thresh, reps, CLL, ...])	Evaluate the log-likelihood via the bootstrap particle filter.
`mif`(J, M, rw_sd[, key, theta, thresh, ...])	Estimate parameters via the Iterated Filtering 2 (IF2) algorithm.
`train`(J, M, eta[, key, theta, optimizer, ...])	Optimize parameters via a differentiable particle filter (MOP).
`dpop_train`(J, M, eta[, optimizer, alpha, ...])	Optimizes model parameters using the DPOP differentiable particle filter and gradient-based methods.
`pmcmc`(J, M, proposal[, dprior, key, theta, ...])	Particle Markov chain Monte Carlo (PMMH) for Bayesian parameter inference.
`abc`(M, probes, scale, epsilon, proposal[, ...])	Approximate Bayesian Computation with a Metropolis-Hastings outer loop.

Results

`results`([index, ignore_nan])	Return a summary DataFrame for one run from the results history.
`traces`()	Return the full trace of log-likelihoods and parameters over all runs.
`CLL`([index, average])	Return conditional log-likelihoods from a particle filter run.
`ESS`([index, average])	Return effective sample sizes from a particle filter run.

Other Supporting Methods

`sample_params`(param_bounds, n, key)	Sample `n` parameter sets uniformly within specified bounds.
`to_struct`()	Export the model to a lightweight JAX-compatible struct.
`prune`([n, refill])	Keep the top `n` parameter sets by log-likelihood.
`time`()	Return a summary of wall-clock execution times for all runs.
`arma`([order, log_ys, suppress_warnings])	Fit an ARIMA benchmark model and return its log-likelihood.
`negbin`([autoregressive, suppress_warnings])	Fit a Negative Binomial benchmark model and return its log-likelihood.
`probe`(probes[, nsim, key, theta])	Assess goodness-of-fit by comparing data probes to simulated probes.
`print_summary`([n])	Print a high-level summary of the model and its estimation history.
`print_metadata`()	Display environment and version metadata for this model instance.
`merge`(*pomp_objs)	Merge multiple `Pomp` objects into a single instance.

Visualization

`plot_traces`([show])	Plot parameter and log-likelihood traces from the results history.
`plot_simulations`(key[, nsim, mode, theta, show])	Plot simulated trajectories alongside the observed data.