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://api.manager.ece.iiasa.ac.at')[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 or pathlib.Path, optional: By default, the class will search for user credentials which were set using pyam.iiasa.set_config(). Alternatively, you can provide a path to a yaml file with entries of ‘username’ and ‘password’.
auth_urlstr, optional: custom authentication server URL

Notes

Credentials (username & password) are not required to access any public Scenario Explorer instances (i.e., with Guest login).

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

`connect`(name)	Connect to a specific resource (database API)
`index`([default])	Return the index of models and scenarios
`meta`([default, run_id])	Return categories and indicators (meta) of scenarios
`models`()	List all models in the connected resource
`properties`([default])	Return the audit properties of scenarios
`query`([default, meta])	Query the connected resource for timeseries data (with filters)
`regions`([include_synonyms])	List all regions in the connected resource
`scenarios`()	List all scenarios in the connected resource
`variables`()	List all variables in the connected resource

convert_regions_payload

connect(name)[source]¶: Connect to a specific resource (database API)

property current_connection¶: Currently connected resource (database API connection)

index(default=True, **kwargs)[source]¶

Return the index of models and scenarios

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.
kwargs: Arguments to filer by model and scenario, * can be used as wildcard.

meta(default=True, run_id=False, **kwargs)[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.
run_idbool, optional: Include “run id” column
kwargs: Arguments to filer by model and scenario, * can be used as wildcard

property meta_columns¶: Return the list of meta indicators in the connected resource

models()[source]¶: List all models in the connected resource

properties(default=True, **kwargs)[source]¶

Return the audit properties 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.
kwargs: Arguments to filer by model and scenario, * can be used as wildcard

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)

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://api.manager.ece.iiasa.ac.at', **kwargs)[source]

Query an IIASA Scenario Explorer database API and return as IamDataFrame

Parameters:

namestr: Name of an IIASA Scenario Explorer database 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).
credsstr or pathlib.Path, optional: Credentials (username & password) are not required to access any public Scenario Explorer instances (i.e., with Guest login).

See pyam.iiasa.Connection for details.

Use pyam.iiasa.set_config() to set credentials for accessing private/restricted Scenario Explorer instances.
base_urlstr: Authentication server URL
kwargs: Arguments for pyam.iiasa.Connection.query()

pyam.iiasa.lazy_read_iiasa(file, name, default=True, meta=True, creds=None, base_url='https://api.manager.ece.iiasa.ac.at', **kwargs)[source]

Try to load data from a local cache, failing that, loads it from the internet.

Check if the file in a given location is an up-to-date version of an IIASA database. If so, load it. If not, load data from the IIASA scenario explorer database API and save to that location. Does not check that the previously read version is a complete instance of the database, so if the initial load applies a filter, you will read only data that passes the same filter as well as any additional filter you apply.

Parameters:

filestr or pathlib.Path: The location to test for valid data and save the data if not up-to-date. Must be either xls, xlsx or csv.
namestr: Name of an IIASA Scenario Explorer database 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).
credsstr or pathlib.Path, optional: Credentials (username & password) are not required to access any public Scenario Explorer instances (i.e., with Guest login).

See pyam.iiasa.Connection for details.

Use pyam.iiasa.set_config() to set credentials for accessing private/restricted Scenario Explorer instances.
base_urlstr: Authentication server URL
kwargs: Arguments for pyam.iiasa.Connection.query()

pyam.iiasa.set_config(user, password, file=None)[source]¶: Save username and password for the IIASA API connection to a file