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 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’.- base_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 in the connected resource
meta
([default])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
List all scenarios in the connected resource
List all variables in the connected resource
convert_regions_payload
- 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, **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.
- property meta_columns¶
Return the list of meta indicators in the connected resource
- properties(default=True)[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.
- 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 anIamDataFrame
: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)
- property valid_connections¶
Return available resources (database API connections)
- 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).
- credsstr,
pathlib.Path
, list-like, or dict, 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.Usepyam.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()