5.11. pypfilt.examples

The pypfilt.examples module provides an example predator-prey system.

5.11.1. Predator-prey system

5.11.1.1. Models

class pypfilt.examples.predation.LotkaVolterra

An implementation of the (continuous) Lotka-Volterra equations.

init(ctx, vec)

Initialise a matrix of state vectors.

state_size()

Return the size of the state vector.

d_dt(xt, t)

Calculate the derivatives of x(t) and y(t).

update(ctx, t, dt, is_fs, prev, curr)

Perform a single time-step.

describe()

Describe each component of the state vector.

class pypfilt.examples.predation.ObsModel(obs_unit, obs_period)
log_llhd(params, op, time, obs, curr, hist)

Return the log-likelihood \(\mathcal{l}(y_t \mid x_t)\) for the observation \(y_t\) and every particle \(x_t\).

Parameters:
  • ctx – The simulation context.
  • op – The observation model parameters dictionary.
  • time – The current simulation time, \(t\).
  • obs – An observation for the current time-step, \(y_t\).
  • curr – The particle state vectors, \(x_t\).
  • hist – The particle state histories, indexed by observation period.
simulate(params, op, time, period, expect, rng=None)

Return a random sample of \(y_t\) for each particle \(x_t\).

Parameters:
  • ctx – The simulation context.
  • op – The observation model parameters dictionary.
  • time – The simulation time(s), \(t\).
  • period – The duration of the observation period (in days).
  • expected – The expected observation value for each particle \(x_t\).
  • rng – The (optional) random number generator to use.
expect(ctx, op, time, period, prev, curr)

Return the expected observation value \(\mathbb{E}[y_t]\) for every particle \(x_t\), at one or more times \(t\).

Parameters:
  • ctx – The simulation context.
  • op – The observation model parameters dictionary.
  • time – The simulation time(s), \(t\).
  • period – The duration of the observation period (in days).
  • prev – The state vectors at the start of the observation period(s), \(x_t\).
  • curr – The state vectors at the end of the observation period(s).
quantiles(params, op, time, mu, wt, probs)

Return the values \(y_i\) that satisfy:

\[y_i = \inf\left\{ y : p_i \le \sum_i w_i \cdot \mathcal{L}(y_t \le y \mid x_t^i)\right\}\]
Parameters:
  • ctx – The simulation context.
  • op – The observation model parameters dictionary.
  • time – The current simulation time, \(t\).
  • mu – The expected case fraction for each particle, \(\mathbb{E}(y_t)\).
  • wt – The weight associated with each particle, \(w_i\).
  • probs – The probabilities \(p_i\), which must be sorted in ascending order.
from_file(filename, time_scale)

Load observations from a space-delimited text file with column headers defined in the first line.

Parameters:
  • filename – The file to read.
  • time_scale – The simulation time scale.
Returns:

A list of observations, ordered as per the original file, and the underlying data table.
Return type:

Tuple[List[dict], numpy.ndarray]

5.11.1.2. Example files

pypfilt.examples.predation.write_example_files()

Save the following example files to the working directory:

  • The forecast scenario file “predation.toml”;
  • The observations file “predation-counts-x.ssv”; and
  • The observations file “predation-counts-y.ssv”.
pypfilt.examples.predation.example_toml_data()

Return the contents of the example file “predation.toml”.

pypfilt.examples.predation.example_obs_x_data()

Return the contents of the example file “predation-counts-x.ssv”.

pypfilt.examples.predation.example_obs_y_data()

Return the contents of the example file “predation-counts-y.ssv”.

5.11.1.3. Generating forecasts

pypfilt.examples.predation.forecast(data_file)

Run a suite of forecasts against generated observations.

pypfilt.examples.predation.plot(data_file, png=True, pdf=True)

Save the plots produced by plot_params() and plot_forecasts().

This will save the plots to files whose names begin with “predation_params” and “predation_forecasts”.

Parameters:
  • png – Whether to save plots as PNG files.
  • pdf – Whether to save plots as PDF files.
pypfilt.examples.predation.plot_params(param_cints, pdf_file=None, png_file=None)

Plot the parameter posteriors over the estimation run.

pypfilt.examples.predation.plot_forecasts(state_cints, x_obs, y_obs, pdf_file=None, png_file=None)

Plot the population predictions at each forecasting date.

5.11.1.4. Other functions

pypfilt.examples.predation.default_priors()

Define default model prior distributions.

pypfilt.examples.predation.make_params(px_count, seed, obs_sdev, max_days=14)

Define the default simulation parameters for this model.

pypfilt.examples.predation.save_scalar_observations(sim_obs)

Save simulated observations to disk.