6.10. pypfilt.examples

The pypfilt.examples module provides an example predator-prey system, a Gaussian random walk, and several epidemic SIR models.

6.10.1. Predator-prey system

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

field_types(ctx)

Return a list of (field_name, field_dtype, field_shape) tuples that define the state vector.

The third element, field_shape, is optional and contains the shape of this field if it forms an array of type field_dtype.

These tuples must be in the same order as the state vector itself.

Parameters:ctx – The simulation context.
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.

can_smooth()

Return the set of field names in the state vector that can be smoothed by the post-regularised particle filter (see post_regularise()).

class pypfilt.examples.predation.ObsModel(obs_unit, settings)
distribution(ctx, snapshot, ixs=None)

Return a frozen scipy.stats distribution that defines the observation model for each particle.

Parameters:
  • ctx – The simulation context.
  • snapshot (Snapshot) – The current particle states.
  • ixs – Sampling indices for the shape parameters (optional).

6.10.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”;
  • The observations file “predation-counts-y.ssv”;
  • The forecast scenario file “predation-datetime.toml”;
  • The observations file “predation-counts-x-datetime.ssv”; and
  • The observations file “predation-counts-y-datetime.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”.

pypfilt.examples.predation.example_toml_datetime_data()

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

pypfilt.examples.predation.example_obs_x_datetime_data()

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

pypfilt.examples.predation.example_obs_y_datetime_data()

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

6.10.1.3. Generating forecasts

pypfilt.examples.predation.forecast(data_file)

Run a suite of forecasts against generated observations, using a scalar time scale.

Parameters:date_file – The name of the output HDF5 file.
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.

6.10.1.4. Other functions

pypfilt.examples.predation.default_priors()

Define default model prior distributions.

pypfilt.examples.predation.predation_instance(toml_file)

Return an instance of the predation scenario from the specified TOML file.

pypfilt.examples.predation.predation_scalar_instance()

Return an instance of the predation scenario using a scalar time scale.

pypfilt.examples.predation.predation_datetime_instance()

Return an instance of the predation scenario using a datetime time scale.

pypfilt.examples.predation.apply_ground_truth_prior(instance)

Define the predation model prior distribution for fixed ground truth.

pypfilt.examples.predation.save_scalar_observations(obs_tables, x_obs_file, y_obs_file)

Save simulated observations to disk.

6.10.2. Gaussian random walk

6.10.2.1. Models

class pypfilt.examples.simple.GaussianWalk

A Gaussian random walk.

init(ctx, vec)

Initialise a matrix of state vectors.

Parameters:
  • ctx – The simulation context.
  • vec – An uninitialised \(P \times S\) matrix of state vectors, for \(P\) particles and state vectors of length \(S\) (as defined by field_types()).
field_types(ctx)

Return a list of (field_name, field_dtype, field_shape) tuples that define the state vector.

The third element, field_shape, is optional and contains the shape of this field if it forms an array of type field_dtype.

These tuples must be in the same order as the state vector itself.

Parameters:ctx – The simulation context.
update(ctx, t, dt, is_fs, prev, curr)

Perform a single time-step.

can_smooth()

Return the set of field names in the state vector that can be smoothed by the post-regularised particle filter (see post_regularise()).

class pypfilt.examples.simple.GaussianObs(obs_unit, settings)

A Gaussian observation model for the GaussianWalk model.

distribution(ctx, snapshot, ixs=None)

Return a frozen scipy.stats distribution that defines the observation model for each particle.

Parameters:
  • ctx – The simulation context.
  • snapshot (Snapshot) – The current particle states.
  • ixs – Sampling indices for the shape parameters (optional).

6.10.2.2. Support functions

pypfilt.examples.simple.gaussian_walk_toml_data()

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

pypfilt.examples.simple.gaussian_walk_instance()

Return an instance of the simple example scenario.

6.10.3. Epidemic SIR models

6.10.3.1. Models

class pypfilt.examples.sir.SirCtmc

A continuous-time Markov chain implementation of the SIR model.

The model settings must include the following keys:

  • population_size: The number of individuals in the population.
field_types(ctx)

Define the state vector structure.

can_smooth()

The fields that can be smoothed by the post-regularisation filter.

init(ctx, vec)

Initialise the state vectors.

update(ctx, time, dt, is_forecast, prev, curr)

Update the state vectors to account for all events that occur up to, and including, time.

active_particles(vec, stop_time)

Return a Boolean array that identifies the particles whose most recent event occurred no later than stop_time.

select_next_event(ctx, vec, stop_time)

Calculate the next event time and event type for each active particle.

class pypfilt.examples.sir.SirDtmc

A discrete-time Markov chain implementation of the SIR model.

The model settings must include the following keys:

  • population_size: The number of individuals in the population.
field_types(ctx)

Define the state vector structure.

can_smooth()

The fields that can be smoothed by the post-regularisation filter.

init(ctx, vec)

Initialise the state vectors.

update(ctx, time, dt, is_forecast, prev, curr)

Update the state vectors.

class pypfilt.examples.sir.SirOdeEuler

An ordinary differential equation implementation of the SIR model, which uses the forward Euler method.

The model settings must include the following keys:

  • population_size: The number of individuals in the population.
field_types(ctx)

Define the state vector structure.

can_smooth()

The fields that can be smoothed by the post-regularisation filter.

init(ctx, vec)

Initialise the state vectors.

update(ctx, time, dt, is_forecast, prev, curr)

Update the state vectors.

class pypfilt.examples.sir.SirOdeRk

An ordinary differential equation implementation of the SIR model, which uses the explicit Runge-Kutta method of order 5(4).

The model settings must include the following keys:

  • population_size: The number of individuals in the population.
field_types(ctx)

Define the state vector structure.

can_smooth()

The fields that can be smoothed by the post-regularisation filter.

init(ctx, vec)

Initialise the state vectors.

d_dt(t, xt, population)

The right-hand side of the system.

update(ctx, time, dt, is_forecast, prev, curr)

Update the state vectors.

class pypfilt.examples.sir.SirSde

A stochastic differential equation implementation of the SIR model.

The model settings must include the following keys:

  • population_size: The number of individuals in the population.
field_types(ctx)

Define the state vector structure.

can_smooth()

The fields that can be smoothed by the post-regularisation filter.

init(ctx, vec)

Initialise the state vectors.

update(ctx, time, dt, is_forecast, prev, curr)

Update the state vectors.

class pypfilt.examples.sir.SirObs(obs_unit, settings)

A binomial observation model for the example SIR models.

\[ \begin{align}\begin{aligned}\mathcal{L}(y_t \mid x_t) &\sim B(n, p)\\n &= S(t-\Delta) - S(t)\end{aligned}\end{align} \]
Parameters:
  • obs_unit – A descriptive name for the data.
  • settings – The observation model settings dictionary.

The settings dictionary should contain the following keys:

  • observation_period: The observation period \(\Delta\).

For example, for daily observations that capture 80% of new infections:

[observations.cases]
model = "pypfilt.examples.sir.SirObs"
observation_period = 1
parameters.p = 0.8
descriptor.format.p = "0.2f"
descriptor.name.p = "p"
new_infections(ctx, snapshot)

Return the number of new infections \(S(t-\Delta) - S(t)\) that occurred during the observation period \(\Delta\) for each particle.

distribution(ctx, snapshot, ixs=None)

Return the observation distribution for each particle.

6.10.3.2. Example files

pypfilt.examples.sir.sir_toml_data()

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