Input/output file formats¶

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, optional: 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_writerpath-like, file-like, or ExcelWriter object: File path as string or pathlib.Path, or existing pandas.ExcelWriter.
sheet_namestr, optional: Name of sheet which will contain IamDataFrame.timeseries() data.
iamc_indexbool, optional: If True, use [‘model’, ‘scenario’, ‘region’, ‘variable’, ‘unit’]; else, use all dimensions. See IamDataFrame.timeseries() for details.
include_metabool or str, optional: If True, write meta to a sheet ‘meta’ (default); if this is a string, use it as sheet name.
**kwargs: Passed to pandas.ExcelWriter (if excel_writer is path-like)

IamDataFrame.to_csv(path=None, iamc_index=False, **kwargs)[source]

Write IamDataFrame.timeseries() to a comma-separated values (csv) file

Parameters:

pathstr, path or file-like, optional: File path as string or pathlib.Path, or file-like object. If None, the result is returned as a csv-formatted string. See pandas.DataFrame.to_csv() for details.
iamc_indexbool, optional: If True, use [‘model’, ‘scenario’, ‘region’, ‘variable’, ‘unit’]; else, use all dimensions. See IamDataFrame.timeseries() for details.
**kwargs: Passed to pandas.DataFrame.to_csv().

Integration with netcdf files¶

NetCDF is a powerful file format that can efficiently store multiple scientific variables sharing the same dimensions. In climate science, data such as temperature, precipitation and radiation can be stored in four dimensions: a time dimension and three spatial dimensions (latitude, longitude, altitude).

The pyam package supports reading and writing to netcdf files that have the following structure:

Timeseries data are stored such that each variable (in the sense of the IAMC format) is a separate netcdf-data-variable with the dimensions time, model, scenario and region. The unit is given as an attribute of the data variable. The long_name attribute is used as the variable in the IamDataFrame. The time dimension can be either a datetime format or given as years (integer).
Meta indicators are stored as netcdf-data-variables with the dimensions model and scenario.

Read more about The pyam data model. The exclude attribute is not written to netcdf files.

pyam.read_netcdf(path)[source]¶

Read timeseries data and meta indicators from a netCDF file

Parameters:

pathpathlib.Path or file-like object: Scenario data file in netCDF format.

Returns:

IamDataFrame

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