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)[source] 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)[source] Write object to an Excel spreadsheet
- Parameters
- excel_writerstr, path object or ExcelWriter object
any valid string path,
pathlib.Path
orpandas.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)[source] 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')[source]¶ Read timeseries data and meta-indicators from frictionless Data Package
- Parameters
- pathstring or path object
any valid string path or
pathlib.Path
,
passed todatapackage.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)[source] 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)[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()
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)[source]¶ 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 functionpandas_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 toread_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 functionpandas_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).