pypfilt.examples¶
The pypfilt.examples
module includes a chaotic dynamical system, a predator-prey system, a Gaussian random walk, and several epidemic SIR models.
Dynamical systems models¶
- class pypfilt.examples.lorenz.Lorenz63¶
The Lorenz-63 system:
\[\begin{split}\frac{dx}{dt} &= \sigma (y - x) \\ \frac{dy}{dt} &= x (\rho - z) - y \\ \frac{dz}{dt} &= xy - \beta z \\ x_t &= [\sigma, \rho, \beta, x, y, z]^T\end{split}\]This system exhibits chaotic behaviour in the neighbourhood of \(\sigma = 10\), \(\rho = 28\), \(\beta = \frac{8}{3}\).
- field_types(ctx)¶
Define the state vector \([\sigma, \rho, \beta, x, y, z]^T\).
- d_dt(time, xt, ctx, is_forecast)¶
The right-hand side of the ODE system.
- Parameters
time – The current time.
xt – The particle state vectors.
ctx – The simulation context.
is_forecast – True if this is a forecasting simulation.
- can_smooth()¶
Indicate which state vector fields can be smoothed.
- class pypfilt.examples.lorenz.ObsLorenz63(obs_unit, settings)¶
An observation model for the Lorenz-63 system:
\[y_t \sim N(\mu = x_t, \sigma = 1.5)\]The observation unit must be the name of a field in the state vector. For example, the observation unit must be
"y"
to observe \(y(t)\):[observations.y] model = "pypfilt.examples.lorenz.ObsLorenz63"
- pypfilt.examples.lorenz.lorenz63_simulate_toml()¶
A scenario for the
Lorenz63
model, which can be used for simulating observations.- Returns
The scenario definition, represented as a TOML string.
- Return type
str
- pypfilt.examples.lorenz.lorenz63_forecast_toml()¶
A scenario for the
Lorenz63
model, which can be used for forecasting.- Returns
The scenario definition, represented as a TOML string.
- Return type
str
Predator-prey system¶
Models¶
- class pypfilt.examples.predation.LotkaVolterra¶
An implementation of the (continuous) Lotka-Volterra equations.
- 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(time, xt, ctx, is_forecast)¶
Calculate the derivatives of x(t) and y(t).
- 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()
).Note
Models should only implement this method if the state vector contains parameters that can be smoothed.
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”.
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.
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.
Gaussian random walk¶
Models¶
- class pypfilt.examples.simple.GaussianWalk¶
A Gaussian random walk.
\[\begin{split}x_t &= x_{t-1} + X_t \\ X_t &\sim N(\mu = 0, \sigma = 1)\end{split}\]The initial values \(x_0\) are defined by the prior distribution for
"x"
:[prior] x = { name = "uniform", args.loc = 10.0, args.scale = 10.0 }
- 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, time_step, is_fs, prev, curr)¶
Perform a single time-step.
- class pypfilt.examples.simple.GaussianObs(obs_unit, settings)¶
A Gaussian observation model for the GaussianWalk model.
\[\mathcal{L}(y_t \mid x_t) \sim N(\mu = x_t, \sigma = s)\]The observation model has one parameter: the standard deviation \(s\), whose value is defined by the
"parameters.sdev"
setting:[observations.x] model = "pypfilt.examples.simple.GaussianObs" parameters.sdev = 0.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.
Epidemic SIR models¶
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_step, 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_step, 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_step, 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(time, xt, ctx, is_forecast)¶
The right-hand side of the system.
- 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_step, 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
- 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)¶
Return the observation distribution for each particle.
Example files¶
- pypfilt.examples.sir.sir_toml_data()¶
Return the contents of the example file “sir.toml”.