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

3.1. Scenario definitions¶

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

3.2. Simulation models¶

3.3. Prior distributions¶

3.4. Observations¶

3.5. Observation models¶

3.6. Particle filter¶

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

3.7. 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_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;
- step_date: the current time;
- particles: the current particle states.
'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; and
- particles: the current particle states.
'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; and
- particles: the current particle states.
'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;
- step_date: the current time;
- particles: the current particle states.

3.8. Time scales¶

3.9. Lookup (input) tables¶

3.10. Summary (output) tables¶

3.11. Summary monitors¶

3.12. Particle filter settings¶

3.13. Other simulation settings¶

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