6.11. pypfilt.build¶

The pypfilt.build module builds simulation contexts for simulation instances, in preparation for running estimation and forecasting simulations.

6.11.1. Building simulation contexts¶

pypfilt.build.build_context(inst: pypfilt.scenario.Instance, obs_tables=None)¶

Return a simulation context for the provided scenario instance.

Parameters:	inst (Instance) – The scenario instance. obs_tables – The (optional) dictionary of observation tables; when not provided, these will be constructed from each observation file.
Return type:	Context

class pypfilt.build.Context¶

A simulation context, which contains all of the components, data tables, and scenario settings that are required in order to run estimation passes and forecasts.

Parameters:

scenario_id (str) – The scenario identifier for this context.
descriptor (str) – The identifier descriptor, which describes the observation model parameter values for this context.
settings (Dict[str, Any]) – The dictionary of simulation settings.
source (Optional[str]) – The (optional) TOML input for this specification.
data (Dict[str, Any]) – The dictionary of data tables.
component (Dict[str, Any]) – The dictionary of simulation components.
event_handler (Dict[str, list[Callable]]) – The dictionary of event-handler functions.
all_observations (List[dict]) – All of the available observations in a single list.

scenario_id¶: Alias for field number 0

descriptor¶: Alias for field number 1

settings¶: Alias for field number 2

source¶: Alias for field number 3

data¶: Alias for field number 4

component¶: Alias for field number 5

event_handler¶: Alias for field number 6

all_observations¶: Alias for field number 7

get_setting(keys, default=None)¶

Return the setting associated with a sequence of keys, if all keys are present, otherwise return default.

Examples:

>>> from pypfilt.build import Context
>>> ctx = Context(
...     scenario_id='fake_scenario',
...     descriptor='',
...     source=None,
...     settings={'a': 1, 'b': {'c': 2}},
...     data={},
...     component={},
...     event_handler={},
...     all_observations=[],
... )
>>> ctx.get_setting(['a'])
1
>>> ctx.get_setting(['b', 'c'])
2
>>> ctx.get_setting(['b', 'd']) is None
True
>>> ctx.get_setting(['b', 'd'], default=42)
42

install_event_handler(event_name, handler_fn)¶

Register a function that should be called in response to an event.

Parameters:	event_name – The event name. handler_fn – The event-handler function.

call_event_handlers(event_name, *args, **kwargs)¶

Call all event-handler functions associated with an event name.

Parameters:	event_name – The event name. args – Positional arguments to pass to the event handlers. *kwargs – Keyword arguments to pass to the event handlers.
Examples:

>>> from pypfilt.build import Context
>>> ctx = Context(
...     scenario_id='fake_scenario',
...     descriptor='',
...     source=None,
...     settings={},
...     data={},
...     component={},
...     event_handler={},
...     all_observations=[],
... )
>>> event_name = 'my_event'
>>> def my_handler(message):
...     print(message)
>>> ctx.install_event_handler(event_name, my_handler)
>>> ctx.call_event_handlers(event_name, 'Hello world')
Hello world

prior_table()¶

Return the prior distribution table for parameters whose values are not contained in external data files.

Examples:

def draw_new_prior_samples(ctx):
    cfg = settings['sampler']
    prng = ctx.component['random']['prior']
    particles = ctx.settings['filter']['particles']
    prior_table = ctx.prior_table()
    external_samples = ctx.external_prior_samples()
    return ctx.component['sampler'].draw_samples(
        cfg, prng, particles, prior_table, external_samples)

external_prior_samples()¶

Return samples from the prior distribution for parameters whose values are contained in external data files.

Examples:

def draw_new_prior_samples(ctx):
    cfg = settings['sampler']
    prng = ctx.component['random']['prior']
    particles = ctx.settings['filter']['particles']
    prior_table = ctx.prior_table()
    external_samples = ctx.external_prior_samples()
    return ctx.component['sampler'].draw_samples(
        cfg, prng, particles, prior_table, external_samples)

6.11.2. Internal functions¶

pypfilt.build.get_chained(table, keys, default=None)¶

Return the value associated with a sequence of keys, if all keys are present, otherwise return default.

Examples:

>>> from pypfilt.build import get_chained
>>> data = {'a': 1, 'b': {'c': 2}}
>>> get_chained(data, ['a'])
1
>>> get_chained(data, ['b', 'c'])
2
>>> get_chained(data, ['b', 'd']) is None
True
>>> get_chained(data, ['b', 'd'], default=42)
42

pypfilt.build.set_chained(table, keys, value)¶

Create or update the value associated with a sequence of keys, creating missing keys as needed.

Raises:	ValueError – if a key exists but is not a dictionary.
Examples:

>>> from pypfilt.build import get_chained, set_chained
>>> data = {'a': 1, 'b': {'c': 2}}
>>> set_chained(data, ['b', 'c'], 3)
>>> get_chained(data, ['b', 'c'])
3
>>> set_chained(data, ['x', 'y', 'z'], 'Hello')
>>> get_chained(data, ['x', 'y', 'z'])
'Hello'
>>> try:
...     set_chained(data, ['b', 'c', 'd'], 'Invalid keys')
... except ValueError:
...     print('Cannot replace b.c with a dictionary')
Cannot replace b.c with a dictionary
>>> print(data)
{'a': 1, 'b': {'c': 3}, 'x': {'y': {'z': 'Hello'}}}

pypfilt.build.set_chained_default(table, keys, value)¶

Insert a missing value associated with a sequence of keys.

Examples:

>>> from pypfilt.build import get_chained, set_chained_default
>>> data = {'a': 1, 'b': {'c': 2}}
>>> set_chained_default(data, ['b', 'c'], 11)
>>> get_chained(data, ['b', 'c'])
2
>>> set_chained_default(data, ['b', 'f', 'g'], 42)
>>> get_chained(data, ['b', 'f', 'g'])
42
>>> try:
...     set_chained_default(data, ['b', 'c', 'd'], 'Invalid keys')
... except ValueError:
...     print('Cannot replace b.c with a dictionary')
Cannot replace b.c with a dictionary
>>> print(data)
{'a': 1, 'b': {'c': 2, 'f': {'g': 42}}}