message_ix_models.tools.iea.web.IEA_EWEB

class message_ix_models.tools.iea.web.IEA_EWEB(*args, **kwargs)

Bases: ExoDataSource

Provider of exogenous data from the IEA Extended World Energy Balances.

__init__(*args, **kwargs)

Create an instance and prepare info for transform()/get().

The base implementation:

• Sets options—if not already set—by passing kwargs to Options.

• Raises an exception if there are other/unhandled args or kwargs.

• If key is not set, constructs it with:

  • Name name or measure in lower case.

  • Dimensions dims.

  Subclasses may pre-empt this behaviour by setting key statically or dynamically.

A concrete class implementation must:

• Set options, either directly or by calling super().__init__() with or without keyword arguments.

• Set key, either directly or by calling super().__init__(). In the latter case, it may set name, measure, and/or dims to control the behaviour.

• Raise an exception if unrecognized or invalid kwargs are passed.

and may:

• Transform kwargs or options arguments into other values, for instance by mapping certain values to others, applying regular expressions, or other operations.

• Store those values as instance attributes for use in get().

• Log messages that give information that helps to debug exceptions.

It must not perform any time- or memory-intensive operations, such as actually loading or fetching data. Those operations should be in get().

Methods

__init__(*args, **kwargs)	Create an instance and prepare info for transform()/get().
add_tasks(c, *args[, context, strict])	Add tasks to c to provide and transform the data.
get()	Load and process the data.
transform(c, base_key)	Prepare c to transform raw data from base_key.

Attributes

key	Key for the returned Quantity.
use_test_data	True to allow the class to look up and use test data.
where	where keyword argument to path_fallback().
options	Instance of the Options class.

class Options(aggregate: bool = True, interpolate: bool = True, measure: str = '', name: str = '', dims: tuple[str, ...] = ('n', 'y'), provider: str = '', edition: str = '', product: str | list[str] = '', flow: str | list[str] = '', transform: message_ix_models.tools.iea.web.TRANSFORM = <TRANSFORM.A: 1>, regions: str = '')

Bases: BaseOptions

aggregate: bool = True

True if ExoDataSource.transform() should aggregate data on the \(n\) dimension.

dims: tuple[str, ...] = ('n', 'y')

Dimensions for the returned Key/Quantity.

edition: str = ''

one of ‘2021’, ‘2022’, or ‘2023’. See FILES.

flow: str | list[str] = ''

Select only these labels from the ‘FLOW’ dimension.

classmethod from_args(source_id: str | ExoDataSource, *args, **kwargs)

Construct an instance from keyword arguments.

Parameters:

source_id – For backwards-compatibility with prepare_computer().

interpolate: bool = True

True if ExoDataSource.transform() should interpolate data on the \(y\) dimension.

measure: str = ''

Identifier for the primary measure of retrieved/returned data.

name: str = ''

Name for the returned Key/Quantity.

product: str | list[str] = ''

Select only these labels from the ‘PRODUCT’ dimension.

provider: str = ''

Either ‘IEA’ or ‘OECD’. See FILES.

regions: str = ''

Must also be given with the value "R12" if giving transform="B".

transform: TRANSFORM = 1

Either “A” (default) or “B”. See transform().

classmethod add_tasks(c: Computer, *args, context: Context | None = None, strict: bool = True, **kwargs) → tuple

Add tasks to c to provide and transform the data.

The first returned key is key, and will trigger the following tasks:

1. Load or retrieve data by invoking ExoDataSource.get().

2. If BaseOptions.aggregate is True, aggregate on the \(n\) (node) dimension according to Config.regions.

3. If BaseOptions.interpolate is True, interpolate on the \(y\) (year) dimension according to Config.years.

Steps (2) and (3) are added by transform() and may differ in concrete classes.

Other returned keys include further transformations:

• key + "y0_indexed": same as key, but indexed to the values as of the first model period.

Other keys that are created but not returned can be accessed on c:

• key + "message_ix_models.foo.bar.CLASS": the raw data, with a tag from the fully-qualified name of the ExoDataSource class.

To support the loading and transformation of data, add_structure() is first called with c.

Todo

Add option/tasks to index to a particular label on the \(n\) dimension.

Parameters:

• context – Passed to add_structure().

• strict – Passed to add_structure().

Return type:

tuple of Key

get() → AnyQuantity

Load and process the data.

key: Key = <energy:n-y-product-flow:iea>

Key for the returned Quantity. This may either be set statically on a concrete subclass, or created via __init__().

options: Options

Instance of the Options class.

A concrete class that overrides Options should redefine this attribute, to facilitate type checking.

transform(c: Computer, base_key: Key) → Key

Prepare c to transform raw data from base_key.

1. Map IEA COUNTRY codes to ISO 3166-1 alpha-3 codes, where such mapping exists. See get_mapping() and COUNTRY_NAME.

The next steps depend on whether transform="A" or transform="B" was given with the source_kw.

transform="A" (default)

2. Aggregate using “n::groups”—the same as ExoDataSource.transform(). This operates on the \(n\) labels transformed to alpha-3 codes by step (1) above.

transform="B"

2. Compute intermediate quantities using transform_B().

3. Aggregate using the groups returned by get_node_groups_B().

This method does not prepare interpolation or aggregation on \(y\).

use_test_data: bool = False

True to allow the class to look up and use test data. If no test data exists, this setting has no effect. See _where().

where: list['str | Path'] = ['local']

where keyword argument to path_fallback(). See _where().