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, with_metadata=None)

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

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