Low-level utilities (util)

Submodules:

click	Click is a simple Python module inspired by the stdlib optparse to make writing command line scripts fun.
context	Context and settings for message_ix_models code.
importlib	A pure Python implementation of import.
scenarioinfo	ScenarioInfo class.

Commonly used:

Context(*args, **kwargs)	Context and settings for message_ix_models code.
ScenarioInfo([scenario])	Information about a Scenario object.
Spec(add, remove, require)	A specification for the structure of a model or variant.

util.click

util.context

Context and settings for message_ix_models code.

class message_ix_models.util.context.Context(*args, **kwargs)

Context and settings for message_ix_models code.

Context is a subclass of dict, so common methods like copy() and setdefault() may be used to handle settings. To be forgiving, it also provides attribute access; context.foo is equivalent to context["foo"].

Context provides additional methods to do common tasks that depend on configurable settings:

clone_to_dest([create])	Return a scenario based on the --dest command-line option.
close_db()
delete()	Hide the current Context from future get_instance() calls.
get_cache_path(*parts)	Return a path to a local cache file.
get_local_path(*parts[, suffix])	Return a path under local_data.
get_platform([reload])	Return a ixmp.Platform from platform_info.
get_scenario()	Return a message_ix.Scenario from scenario_info.
handle_cli_args([url, platform, model_name, ...])	Handle command-line arguments.
only()	Return the only Context instance.
use_defaults(settings)	Update from settings.

clone_to_dest(create=True) → message_ix.core.Scenario

Return a scenario based on the --dest command-line option.

Parameters

create (bool, optional) – If True (the default) and the base scenario does not exist, a bare RES scenario is created. Otherwise, an exception is raised.

Returns

To prevent the scenario from being garbage collected, keep a reference to its Platform:

Return type

Scenario

See also

create_res

To use this method, either decorate a command with common_params():

from message_data.tools.cli import common_params

@click.command()
@common_params("dest")
@click.pass_obj
def foo(context, dest):
    scenario, mp = context.clone_to_dest()

or, store the settings dest_scenario and dest_platform on context:

c = Context.get_instance()

c.dest_scenario = dict(model="foo model", scenario="foo scenario")
scenario_mp = context.clone_to_dest()

The resulting scenario has the indicated model- and scenario names.

If --url (or --platform, --model, --scenario, and optionally --version) are given, the identified scenario is used as a ‘base’ scenario, and is cloned. If --url/--platform and --dest refer to different Platform instances, then this is a two-platform clone.

If no base scenario can be loaded, bare.create_res() is called to generate a base scenario.

delete()

Hide the current Context from future get_instance() calls.

get_cache_path(*parts) → pathlib.Path

Return a path to a local cache file.

classmethod get_instance(index=0) → message_ix_models.util.context.Context

Return a Context instance; by default, the first created.

Parameters

index (int, optional) – Index of the Context instance to return, e.g. -1 for the most recently created.

get_local_path(*parts, suffix=None)

Return a path under local_data.

get_platform(reload=False) → ixmp.core.platform.Platform

Return a ixmp.Platform from platform_info.

When used through the CLI, platform_info is a ‘base’ platform as indicated by the –url or –platform options.

If a Platform has previously been instantiated with get_platform(), the same object is returned unless reload=True.

get_scenario() → message_ix.core.Scenario

Return a message_ix.Scenario from scenario_info.

When used through the CLI, scenario_info is a ‘base’ scenario for an operation, indicated by the --url or --platform/--model/--scenario options.

handle_cli_args(url=None, platform=None, model_name=None, scenario_name=None, version=None, local_data=None, _store_as=('platform_info', 'scenario_info'))

Handle command-line arguments.

May update the data_path, platform_info, scenario_info, and/or url settings.

classmethod only() → message_ix_models.util.context.Context

Return the only Context instance.

Raises

IndexError – If there is more than one instance.

use_defaults(settings)

Update from settings.

util.importlib

util._logging

util.node

util.scenarioinfo

ScenarioInfo class.

class message_ix_models.util.scenarioinfo.ScenarioInfo(scenario=None)

Information about a Scenario object.

Code that prepares data for a target Scenario can accept a ScenarioInfo instance. This avoids the need to load a Scenario, which can be slow under some conditions.

ScenarioInfo objects can also be used (e.g. by apply_spec()) to describe the contents of a Scenario before it is created.

ScenarioInfo objects have the following convenience attributes:

set	Elements of ixmp/message_ix sets.
is_message_macro	True if a MESSAGE-MACRO scenario.
N	Elements of the set 'node'.
Y	Elements of the set 'year' that are >= the first model year.
y0	First model year, if set, else Y[0].
yv_ya	pandas.DataFrame with valid year_vtg, year_act pairs.

Parameters

scenario (message_ix.Scenario) – If given, set is initialized from this existing scenario.

See also

Spec

property N

Elements of the set ‘node’.

property Y

Elements of the set ‘year’ that are >= the first model year.

is_message_macro: bool = False

True if a MESSAGE-MACRO scenario.

par: Dict[str, pandas.core.frame.DataFrame] = {}

Elements of ixmp/message_ix parameters.

set: Dict[str, List] = {}

Elements of ixmp/message_ix sets.

update(other: message_ix_models.util.scenarioinfo.ScenarioInfo)

Update with the set elements of other.

y0: int = -1

First model year, if set, else Y[0].

year_from_codes(codes: List[sdmx.model.Code])

Update using a list of codes.

The following are updated:

• set year

• set cat_year, with the first model year.

• par duration_period

Any existing values are discarded.

After this, the attributes y0 and Y give the first model year and model years, respectively.

Examples

Get a particular code list, create a ScenarioInfo instance, and update using the codes:

>>> years = get_codes("year/A")
>>> info = ScenarioInfo()
>>> info.year_from_codes(years)

Use populated values:

>>> info.y0
2020
>>> info.Y[:3]
[2020, 2030, 2040]
>>> info.Y[-3:]
[2090, 2100, 2110]

property yv_ya

pandas.DataFrame with valid year_vtg, year_act pairs.

class message_ix_models.util.scenarioinfo.Spec(add: message_ix_models.util.scenarioinfo.ScenarioInfo = <factory>, remove: message_ix_models.util.scenarioinfo.ScenarioInfo = <factory>, require: message_ix_models.util.scenarioinfo.ScenarioInfo = <factory>)

A specification for the structure of a model or variant.

A Spec collects 3 ScenarioInfo instances at the attributes add, remove, and require. This is the type that is accepted by apply_spec(); Building models (model.build) describes how a Spec is used to modify a Scenario. A Spec may also be used to express information about the target structure of data to be prepared; like ScenarioInfo, this can happen before the target Scenario exists.

Spec also provides:

• Dictionary-style access, e.g. s["add"] is equivalent to s.add..

• Error checking; setting keys other than add/remove/require results in an error.

• merge(), a helper method.

add: message_ix_models.util.scenarioinfo.ScenarioInfo

Structure to be added to a base scenario.

static merge(a: message_ix_models.util.scenarioinfo.Spec, b: message_ix_models.util.scenarioinfo.Spec) → message_ix_models.util.scenarioinfo.Spec

Merge Specs a and b together.

Returns a new Spec where each member is a union of the respective members of a and b.

remove: message_ix_models.util.scenarioinfo.ScenarioInfo

Structure to be removed from a base scenario.

require: message_ix_models.util.scenarioinfo.ScenarioInfo

Structure that must be present in a base scenario.