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: Optional[str])¶
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: Optional[str]¶
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
- time_scale()¶
Return the time scale for this scenario instance.
- Return type
Internal types¶
- class pypfilt.scenario.Specification(global_settings: Dict[str, Any], scenario_settings: Dict[str, Any], source: Optional[str])¶
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: Optional[str]¶
Alias for field number 2
- class pypfilt.scenario.Scenario(scenario_id: str, settings: Dict[str, Any], source: Optional[str])¶
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: Optional[str]¶
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.
- 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, wherevalues
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
Values in
defaults
can only be replaced, they cannot be removed.- 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}}
- 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]