Pomp Class

class pypomp.core.pomp.Pomp(ys: DataFrame, theta: Mapping[str, int | float | number | Array] | Sequence[Mapping[str, int | float | number | Array]] | pypomp.core.parameters.PompParameters | None, 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)

Bases: object

A class representing a Partially Observed Markov Process (POMP) model.

This class provides a structured way to define and work with POMP models, which are used for modeling time series data where the underlying state process is only partially observed. The class encapsulates the model components including the initial state distribution, process model, and measurement model.

In particular, the class provides methods for:

• Simulation of the model

• Particle filtering

• Iterated filtering

• Model training using a differentiable particle filter

⚠️ IMPORTANT: Defining Model Components

The rinit, rproc, dmeas, and rmeas arguments expect user-defined functions. You MUST read the documentation for each argument to understand the required argument names, type hints, and return types. The Pomp object will fail to initialize if these functions do not strictly adhere to the specifications.

• State initialization simulator (rinit): See State Initialization (rinit).

• State transition simulator (rproc): See State Transition (rproc).

• Measurement density (dmeas): See Measurement Density (dmeas).

• Measurement simulator (rmeas): See Measurement Simulator (rmeas).

Parameters:

• ys (pd.DataFrame) – The measurement data frame. The row index must contain the observation times.

• theta (ThetaInput) – Initial parameter(s) for the model. Accepts: - A single dictionary: dict[str, Numeric] - A list of dictionaries: list[dict[str, Numeric]] - An existing PompParameters object Numeric values (e.g. jax.Array, int) are automatically coerced to standard Python floats for internal storage. Vectorized methods (like pfilter) will run in parallel over list/PompParameters inputs.

• statenames (list[str]) – List of all latent state variable names.

• t0 (float) – The initial time for the model (typically before the first observation).

• rinit (Callable) – Initial state simulator function.

• rproc (Callable) – Process simulator function (defining a single time step).

• dmeas (Callable, optional) – Measurement density function (log-likelihood).

• rmeas (Callable, optional) – Measurement simulator function.

• par_trans (ParTrans, optional) – Parameter transformation object used to move parameters between the natural space and the estimation space. Defaults to the identity transformation.

• covars (pd.DataFrame, optional) – Time-varying covariates. The row index must contain the covariate times.

• nstep (int, optional) – The number of integration steps to take between observations. Passed automatically to the RProc component. Must be None if dt is provided.

• dt (float, optional) – Fixed time step size for the process model. Passed automatically to the RProc component. Must be None if nstep is provided.

• accumvars (tuple[str, ...], optional) – Names of accumulator state variables (e.g., incidence tracking). These are reset to 0 at the start of each observation interval.

• validate_logic (bool, optional) – Whether to validate the logic of the model components.

Attributes

ys	The measurement data frame with observation times as the index.
theta
canonical_param_names	Ordered list of parameter names used throughout the model.
statenames	Names of all latent state variables in the process model.
t0	Initial time for the model (typically before the first observation).
rinit	Simulator for the initial state distribution.
rproc	Process model simulator handling state transitions between observation times.
dmeas	Measurement density used to evaluate the likelihood of observations.
rmeas	Measurement simulator used to generate synthetic observations.
par_trans	Parameter transformation object mapping between natural and estimation spaces.
covars	Time-varying covariates for the model, if applicable.
accumvars	Names of accumulator state variables that are reset at each observation time.
results_history	History of results from pfilter, mif, and train calls.
fresh_key	Running a method that takes a key will store a fresh, unused key here.
metadata	Environment and version metadata initialized when this instance was built.

Core Algorithmic Methods

simulate(-> tuple[~pandas.DataFrame, ...)	Simulates the latent state and measurement processes of the POMP model.
pfilter(J[, key, theta, thresh, reps, CLL, ...])	Evaluates the likelihood of the model via the particle filter (bootstrap filter).
mif(J, M, rw_sd, a[, key, theta, thresh, ...])	Estimates model parameters by maximizing the marginal likelihood via the Iterated Filtering (IF2) algorithm.
train(J, M, eta[, key, theta, optimizer, ...])	Optimizes model parameters using a differentiable particle filter and gradient-based methods.
dpop_train(J, M, eta[, optimizer, alpha, ...])	Optimizes model parameters using the DPOP differentiable particle filter and gradient-based methods.

Supporting Methods

sample_params(param_bounds, n, key)	Samples multiple sets of parameters from independent uniform distributions.
prune([n, refill])	Filters the current set of parameter replicates to keep only the top n performers based on their most recent log-likelihood estimates.
results([index, ignore_nan])	Returns a DataFrame with the results of the method run at the given index in the model's history.
traces()	Returns a DataFrame with the full trace of log-likelihoods and parameters from the entire result history.
CLL([index, average])	Returns a tidy DataFrame with the conditional log-likelihoods of the method run at the given index.
ESS([index, average])	Returns a tidy DataFrame with the effective sample size of the method run at the given index.
time()	Return a DataFrame summarizing the execution times of methods run.
arma([order, log_ys, suppress_warnings])	Fits an independent ARIMA model to the observation data and returns the estimated log-likelihood.
negbin([autoregressive, suppress_warnings])	Fits a Negative Binomial model to the observation data and returns the log-likelihood.
probe(probes[, nsim, key, theta])	Evaluates model diagnostics by comparing 'probes' (summary statistics) of real data against simulated data.
print_summary([n])	Prints a high-level summary of the POMP model instance and its estimation history.
print_metadata()	Displays technical metadata regarding the creation and runtime environment of this Pomp instance.
plot_traces([show])	Plot the parameter and log-likelihood traces from the entire result history.
plot_simulations(key[, nsim, mode, theta, show])	Generates an interactive plot comparing simulated trajectories from the model against the actual observed data.
merge(*pomp_objs)	Merges multiple Pomp objects into a single instance by combining their parameter replicates and results histories.