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