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
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, **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
- 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 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://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.
- 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.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()
- 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 xlsx or csv.
- namestr
- Name of an IIASA Scenario Explorer database instance.
- 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.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()
- filestr or