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 typefield_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)¶
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()
andplot_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 typefield_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.
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.