pypfilt.scenario#

The pypfilt.scenario module reads simulation scenarios from plain-text TOML inputs.

The purpose of this module is to allow users to define and run simulations without writing any Python code, and instead define all of the necessary settings in TOML files.

Note

A scenario will have a separate Instance for each combination of observation model parameter values.

Loading scenarios#

pypfilt.scenario.load_instances(sources)#

Iterate over scenario instances defined in one or more TOML sources.

Parameters:: sources – A list of file-like objects and/or file paths. If sources is not a list, it will be treated as the only item of a list.
Return type:: Iterator[Instance]
Examples:

>>> import pypfilt
>>> import pypfilt.build
>>> import pypfilt.examples.predation
>>> pypfilt.examples.predation.write_example_files()
>>> forecast_times = [1.0, 3.0, 5.0, 7.0, 9.0]
>>> config_file = 'predation.toml'
>>> data_file = 'output.hdf5'
>>> for instance in pypfilt.load_instances(config_file):
...     context = instance.build_context()
...     state = pypfilt.forecast(
...         context, forecast_times, filename=data_file
...     )
>>> # Remove the output file when it is no longer needed.
>>> import os
>>> os.remove(data_file)

class pypfilt.scenario.Instance(scenario_id: str, settings: Dict[str, Any], descriptor: str, source: str | None)#

A single instance of a scenario.

Parameters:

scenario_id (str) – The scenario identifier for this instance.
settings (Dict[str, Any]) – The settings dictionary, which defines all of the simulation components and parameters, including any that are specific to this instance.
descriptor (str) – The identifier descriptor, which describes the observation model parameter values for this specific instance.
source (Optional[str]) – The (optional) TOML input for this specification.

scenario_id: str#: Alias for field number 0

settings: Dict[str, Any]#: Alias for field number 1

descriptor: str#: Alias for field number 2

source: str | None#: Alias for field number 3

build_context(obs_tables=None)#

Return a simulation context for this scenario instance.

This simply calls pypfilt.build.build_context().

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

time_scale()#

Return the time scale for this scenario instance.

Return type:: pypfilt.time.Time

Internal types#

class pypfilt.scenario.Specification(global_settings: Dict[str, Any], scenario_settings: Dict[str, Any], source: str | None)#

A specification that defines any number of scenarios.

Parameters:

global_settings (Dict[str, Any]) – Default settings for all scenarios.
scenario_settings (Dict[str, Any]) – Settings specific to single scenarios. This is a dictionary that maps the setting ID to the settings that are specific to the identified scenario.
source (Optional[str]) – The (optional) TOML input for this specification.

global_settings: Dict[str, Any]#: Alias for field number 0

scenario_settings: Dict[str, Any]#: Alias for field number 1

source: str | None#: Alias for field number 2

class pypfilt.scenario.Scenario(scenario_id: str, settings: Dict[str, Any], source: str | None)#

The definition of a single scenario.

Parameters:

scenario_id (str) – The unique identifier for this scenario.
settings (Dict[str, Any]) – The settings dictionary, which defines all of the simulation components and parameters.
source (Optional[str]) – The (optional) TOML input for this specification.

scenario_id: str#: Alias for field number 0

settings: Dict[str, Any]#: Alias for field number 1

source: str | None#: Alias for field number 2

class pypfilt.scenario.ObsModelParams(unit: str, values: Dict[str, Any], value_format: Dict[str, str], display_names: Dict[str, str])#

Describes the parameter values for an observation model, and how to format the parameter names and values into an instance descriptor.

Parameters:

unit (str) – The observation unit, which is a unique identifier for this observation model and the observations to which it pertains.
values (Dict[str, Any]) – The parameter values for this observation model.
value_format (Dict[str, str]) – The format strings used to convert parameter values into strings.
display_names (Dict[str, str]) – The strings used to represent each parameter in instance descriptors.

unit: str#: Alias for field number 0

values: Dict[str, Any]#: Alias for field number 1

value_format: Dict[str, str]#: Alias for field number 2

display_names: Dict[str, str]#: Alias for field number 3

Internal functions#

pypfilt.scenario.load_toml(source)#

Read TOML content from source and return the parsed dictionary and the TOML input.

Parameters:: source – A file-like object or a file path.
Returns:: A (dict, str) tuple.

pypfilt.scenario.load_specifications(sources)#

Iterate over the scenario specifications in sources.

Parameters:: sources – A list of file-like objects and/or file paths. If sources is not a list, it will be treated as a list containing one item.
Return type:: Iterator[Specification]
Raises:: ValueError – if a source does not define any scenarios.

pypfilt.scenario.scenarios(spec)#

Iterate over the scenarios in the provided specification spec.

Parameters:: spec (Specification) – The scenario specifications.
Return type:: Iterator[Scenario]

pypfilt.scenario.instances(scenario)#

Iterate over the instances of a single scenario.

Parameters:: scenario (Scenario) – The scenario definition.
Return type:: Iterator[Instance]

pypfilt.scenario.observation_model_parameter_combinations(obs_params)#

Iterate over every combination of parameter values for a single observation model.

Each combination is returned as a (unit, values, descriptor) tuple.

Parameters:: obs_params (ObsModelParams) – The observation model parameters definition.
Return type:: Iterator[tuple[str, Dict[str, float | int], str]]

pypfilt.scenario.scenario_observation_model_combinations(scenario)#

Iterate over every combination of parameter values for each observation model.

Each combination is returned as a (values, descriptor) tuple, where values is a dictionary that maps each observation model (identified by observation unit) to the parameter values for that observation model.

Return type:: Iterator[tuple[Dict[str, Any], str]]

pypfilt.scenario.scenario_observation_model_parameters(scenario)#

Return the parameter values for each observation model in a scenario, where each observation model is identified by its observation unit.

Parameters:: scenario (Scenario) – The scenario definition.
Return type:: Dict[str, ObsModelParams]
Raises:: ValueError – if the parameter names are not consistent across the parameter values, the value format strings, and the parameter display names.

pypfilt.scenario.override_dict(defaults, overrides)#

Override a dictionary with values in another dictionary. This will recursively descend into matching nested dictionaries.

Where an override value is a dictionary, the corresponding default value must be a dictionary in order for nested defaults to be propagated. Otherwise, the default value is simply replaced by the override value.

Note

To remove keys from defaults, use the special value DELETE_KEY, as shown below.

Parameters:

defaults (dict) – The original values; note that this dictionary will be modified.
overrides (dict) – The overriding values.

Returns:

The modified defaults dictionary.

Return type:

Dict[Any, Any]

Examples:

>>> from pypfilt.scenario import override_dict
>>> x = {'a': 1, 'b': 2, 'c': {'x': 3, 'y': 4}}
>>> override_dict(x, {'c': {'x': 10}})
{'a': 1, 'b': 2, 'c': {'x': 10, 'y': 4}}

Use the special value DELETE_KEY to delete keys rather than replacing their values:

>>> from pypfilt.scenario import override_dict, DELETE_KEY
>>> x = {'a': 1, 'b': 2, 'c': {'x': 3, 'y': 4}}
>>> override_dict(x, {'c': {'x': DELETE_KEY}})
{'a': 1, 'b': 2, 'c': {'y': 4}}

class pypfilt.scenario.DELETE_KEY#: A special value used to indicate that a dictionary key should be deleted, rather than replaced, when using override_dict().

pypfilt.scenario.as_list(values)#

Return values as a list.

Parameters:: values (Union[list[Any], Any]) – A list of values, or a value that will be returned as the only item of the returned list.
Return type:: list[Any]