Pomp Class

class pypomp.core.pomp.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')

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 (PompParameters) – Initial parameter(s) for the model. Accepts: - An existing PompParameters object Vectorized methods (like pfilter) will run in parallel over multiple parameter sets stored inside the PompParameters object.

• 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.

• order (str, optional) – The interpolation order for time-varying covariates (“linear” or “constant”).

Attributes

Pomp.ys: DataFrame

The measurement data frame with observation times as the index.

Pomp.theta

The parameter object for the model.

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(-> 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[, 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 parameters for a continuous-state model 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.