Key Concepts¶

TODO: provide high-level explanations of the various components (e.g., simulation models, observation models, lookup tables and where they are stored, summary tables) and how they all fit together.

Scenario definitions¶

High-level overview of the TOML, how we allow for inheritance and overriding on a per-scenario basis.

Simulation models¶

Prior distributions¶

Observations¶

Observation models¶

Particle filter¶

TODO: explain how the particle filter combines all of the above to estimate the posterior distribution.

Particle filter events¶

The particle filter triggers a number of events. Other components, such as simulation models and observation models, can receive notification of these events by registering an event-handler with the simulation context (see install_event_handler()).

The available particle filter events are:

'log_llhd'
This event is triggered when the likelihood of an observation has been calculated for each particle. It is triggered for each observation, so it will be triggered multiple times in a single time-step if there is more than one observation for that time-step. The event-handler arguments are:
- obs: the observation dictionary;
- obs_llhd: the observation log-likelihood for each particle (one-dimensional array); and
- weights: the weight of each particle (one-dimensional array).
'before_reweight'
This event is triggered before particle weights are updated. The event-handler arguments are:
- event: BeforeReweight
'before_resample'
This event is triggered before the particles are resampled, but after their weights have been updated. The event-handler arguments are:
- ctx: the simulation context (Context);
- time: the current time;
- particles: the current particle state vectors.
'before_regularisation'
This event is triggered before the post-regularisation step (only if post-regularisation is enabled). The event-handler arguments are:
- ctx: the simulation context (Context); and
- particles: the current particle state vectors.
'after_regularisation'
This event is triggered after the post-regularisation step (only if post-regularisation is enabled). The event-handler arguments are:
- ctx: the simulation context (Context); and
- particles: the current particle state vectors.
'after_resample'
This event is triggered after the particles are resampled (including post-regularisation, if enabled). The event-handler arguments are:
- ctx: the simulation context (Context);
- time: the current time;
- particles: the current particle state vectors.
'resampled' This event is triggered after the particles are resampled (including post-regularisation, if enabled). The event-handler arguments are:
- event: Resampled

Time scales¶

Lookup (input) tables¶

Summary (output) tables¶

Summary monitors¶

Particle filter settings¶

Other simulation settings¶

Simulation contexts¶

For every estimation and forecasting simulation, pypfilt builds a simulation context from the scenario instance. This context object contains all of the components, data tables, and scenario settings that define the simulation.

Common uses of a simulation context ctx include:

Retrieving the unique scenario ID:

print('The scenario ID is {}'.format(ctx.scenario_id))

Retrieving a scenario setting with ctx.get_setting():

particle_count = ctx.get_setting(['filter', 'particles'])
sim_start = ctx.get_setting(['time', 'sim_start'])

Retrieving sample values from the model prior distribution:
```
x_init = ctx.data['prior']['x']
```
Retrieving the simulation model component:
```
model = ctx.component['model']
```
Retrieving the simulation time-scale component:
```
time_scale = ctx.component['time']
```
Retrieving the simulation model PRNG:
```
rnd = ctx.component['random']['model']
```
Retrieving the observation model for some observation unit obs_unit:
```
obs_model = ctx.component['obs'][obs_unit]
```

Retrieving time-varying inputs from a lookup table:

alpha = ctx.component['lookup']['alpha_table'].lookup(time)

Adding and calling event handlers.