The Connection class

IIASA’s ixmp scenario explorer infrastructure implements a RestAPI to directly query the database server connected to an explorer instance. See https://software.ene.iiasa.ac.at/ixmp-server for more information.

The pyam package uses this interface to read timeseries data as well as categorization and quantitative indicators. The data is returned as an IamDataFrame. See this tutorial for more information.

class pyam.iiasa.Connection(name=None, creds=None, auth_url='https://db1.ene.iiasa.ac.at/EneAuth/config/v1')[source]

A class to facilitate querying an IIASA Scenario Explorer database API

Parameters
namestr, optional

The name of a database API. See pyam.iiasa.Connection.valid_connections for a list of available APIs.

credsstr, pathlib.Path, list-like, or dict, optional

By default, this function will (try to) read user credentials which were set using pyam.iiasa.set_config(<user>, <password>)(). Alternatively, you can provide a path to a yaml file with entries of ‘username’ and ‘password’.

base_urlstr, custom authentication server URL

Notes

Providing credentials as an ordered container (tuple, list, etc.) or as a dictionary with keys user and password is (still) supported for backwards compatibility. However, this option is NOT RECOMMENDED and will be deprecated in future releases of pyam.

Attributes
current_connection

Currently connected resource (database API connection)

meta_columns

Return the list of meta indicators in the connected resource

valid_connections

Return available resources (database API connections)

Methods

available_metadata()

Deprecated, use Connection.meta_columns

connect(name)

Connect to a specific resource (database API)

index([default])

Return the index of models and scenarios in the connected resource

meta([default])

Return categories and indicators (meta) of scenarios

metadata([default])

Deprecated, use Connection.meta()

models()

List all models in the connected resource

query([default, meta])

Query the connected resource for timeseries data (with filters)

regions([include_synonyms])

List all regions in the connected resource

scenario_list([default])

Deprecated, use Connection.index()

scenarios()

List all scenarios in the connected resource

variables()

List all variables in the connected resource

convert_regions_payload

available_metadata()[source]

Deprecated, use Connection.meta_columns

connect(name)[source]

Connect to a specific resource (database API)

property current_connection

Currently connected resource (database API connection)

index(default=True)[source]

Return the index of models and scenarios in the connected resource

Parameters
defaultbool, optional

If True, return only the default version of a model/scenario. Any model/scenario without a default version is omitted. If False, returns all versions.

meta(default=True)[source]

Return categories and indicators (meta) of scenarios

Parameters
defaultbool, optional

Return only the default version of each scenario. Any (model, scenario) without a default version is omitted. If False, return all versions.

property meta_columns

Return the list of meta indicators in the connected resource

metadata(default=True)[source]

Deprecated, use Connection.meta()

models()[source]

List all models in the connected resource

query(default=True, meta=True, **kwargs)[source]

Query the connected resource for timeseries data (with filters)

Parameters
defaultbool, optional

Return only the default version of each scenario. Any (model, scenario) without a default version is omitted. If False, return all versions.

metabool or list, optional

If True, merge all meta columns indicators (or subset if list is given).

kwargs

Available keyword arguments include

  • model

  • scenario

  • region

  • variable

Returns
IamDataFrame

Examples

You can read from a pyam.iiasa.Connection instance using keyword arguments similar to filtering an IamDataFrame:

Connection.query(model='MESSAGE*', scenario='SSP2*',
                 variable=['Emissions|CO2', 'Primary Energy'])
regions(include_synonyms=False)[source]

List all regions in the connected resource

Parameters
include_synonymsbool

whether to include synonyms (possibly leading to duplicate region names for regions with more than one synonym)

scenario_list(default=True)[source]

Deprecated, use Connection.index()

scenarios()[source]

List all scenarios in the connected resource

property valid_connections

Return available resources (database API connections)

variables()[source]

List all variables in the connected resource

pyam.iiasa.read_iiasa(name, default=True, meta=True, creds=None, base_url='https://db1.ene.iiasa.ac.at/EneAuth/config/v1', **kwargs)[source]

Query an IIASA Scenario Explorer database API and return as IamDataFrame

Parameters
namestr

A valid name of an IIASA scenario explorer instance, see pyam.iiasa.Connection.valid_connections

defaultbool, optional

Return only the default version of each scenario. Any (model, scenario) without a default version is omitted. If False, return all versions.

metabool or list of strings, optional

If True, include all meta categories & quantitative indicators (or subset if list is given).

credsdict

Credentials to access scenario explorer instance and authentication service APIs (username/password)

base_urlstr

Authentication server URL

kwargs

Arguments for pyam.iiasa.Connection.query()