Input/output

DataFrames and xlsx/csv files

A pandas.DataFrame or a path to an xlsx or csv with data in the required structure (i.e., index/columns) can be imported directly by initializing an IamDataFrame - see this tutorial for more information.

Exporting to these formats is implemented via the following functions:

IamDataFrame.as_pandas(meta_cols=True)

Return object as a pandas.DataFrame

Parameters

meta_colslist, default None

join data with all meta columns if True (default) or only with columns in list, or return copy of data if False

IamDataFrame.to_excel(excel_writer, sheet_name='data', iamc_index=False, include_meta=True, **kwargs)

Write object to an Excel spreadsheet

Parameters

excel_writerstr, path object or ExcelWriter object

any valid string path, pathlib.Path or pandas.ExcelWriter

sheet_namestring

name of sheet which will contain timeseries() data

iamc_indexbool, default False

if True, use [‘model’, ‘scenario’, ‘region’, ‘variable’, ‘unit’]; else, use all ‘data’ columns

include_metaboolean or string

if True, write ‘meta’ to an Excel sheet name ‘meta’ (default); if this is a string, use it as sheet name

IamDataFrame.to_csv(path, iamc_index=False, **kwargs)

Write timeseries data of this object to a csv file

Parameters

pathstr or path object

file path or pathlib.Path

iamc_indexbool, default False

if True, use [‘model’, ‘scenario’, ‘region’, ‘variable’, ‘unit’]; else, use all ‘data’ columns

The frictionless Data Package

The pyam package supports reading and writing to the frictionless Data Package.

pyam.read_datapackage(path, data='data', meta='meta')

Read timeseries data and meta-indicators from frictionless Data Package

Parameters

pathstring or path object

any valid string path or pathlib.Path,
passed to datapackage.Package (read the docs)

datastr, optional

resource containing timeseries data in IAMC-compatible format

metastr, optional

(optional) resource containing a table of categorization and quantitative indicators

IamDataFrame.to_datapackage(path)

Write object to a frictionless Data Package

More information: https://frictionlessdata.io

Returns the saved datapackage.Package (read the docs). When adding metadata (descriptors), please follow the template defined by https://github.com/OpenEnergyPlatform/metadata

Parameters

pathstring or path object

any valid string path or pathlib.Path

Connecting to an IIASA Scenario Explorer instance

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.

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

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.

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()

Connecting to other data resources

The package pandas-datareader (read the docs) implements a number of connections to publicly accessible data resources, e.g., the World Bank Open Data Catalog. pyam provides a simple utility function to cast the queried timeseries data directly as an IamDataFrame.

pyam.read_worldbank(model='World Bank', scenario='WDI', **kwargs)

Read data from the World Bank Data Catalogue and return as IamDataFrame

This function is a simple wrapper for the class pandas_datareader.wb.WorldBankReader and the function pandas_datareader.wb.download(). Import the module to retrieve/search the list of indicators (and their id’s), countries, etc.

from pandas_datareader import wb

Parameters

modelstr, optional

The model name to be used for the returned timeseries data.

scenariostr, optional

The scenario name to be used for the returned timeseries data.

kwargs

passed to pandas_datareader.wb.download()

Returns

IamDataFrame

Notes

The function pandas_datareader.wb.download() takes an indicator argument, which can be a string or list of strings. If the indicator passed to read_worldbank() is a dictionary of a World Bank id mapped to a string, the variables in the returned IamDataFrame will be renamed.

The function pandas_datareader.wb.download() does not return a unit, but it can be collected for some indicators using the function pandas_datareader.wb.get_indicators(). In the current implementation, unit is defined as n/a for all data; this can be enhanced later (if there is interest from users).