Skip to content
Switch branches/tags

Latest commit


* Add a unit_mapping dictionary (and a test)

* Make black

* Add to release notes

* Add a deprecation warning, fix a docstring

* Update historical UNFCCC emissions to make api-tests pass

Git stats


Failed to load latest commit information.
Latest commit message
Commit time

pyam: analysis & visualization
of integrated-assessment and macro-energy scenarios

license pypi conda latest

Code style: black python pytest ReadTheDocs codecov

doi joss slack

Overview and scope

The open-source Python package pyam provides a suite of tools and functions for analyzing and visualizing input data (i.e., assumptions/parametrization) and results (model output) of integrated-assessment models, macro-energy scenarios, energy systems analysis, and sectoral studies.

The comprehensive documentation is hosted on Read the Docs!

Key features

  • Simple analysis of scenario timeseries data with an interface similar in feel & style to the widely used pandas.DataFrame
  • Advanced visualization and plotting functions (see the gallery)
  • Scripted validation and processing of scenario data and results

Timeseries types & data formats

Yearly data

The pyam package was initially developed to work with the IAMC template, a timeseries format for yearly data developed and used by the Integrated Assessment Modeling Consortium (IAMC).

model scenario region variable unit 2005 2010 2015
MESSAGE CD-LINKS 400 World Primary Energy EJ/y 462.5 500.7 ...
... ... ... ... ... ... ... ...

An illustration of the IAMC template using a scenario from the CD-LINKS project
via the The IAMC 1.5°C Scenario Explorer

Subannual time resolution

The package also supports timeseries data with a sub-annual time resolution:

  • Continuous-time data using the Python datetime format
  • "Representative timeslices" (e.g., "winter-night", "summer-day") using the pyam extra-columns feature

Read the docs for more information about the pyam data model or look at the data-table tutorial to see how to cast from a variety of timeseries formats to a pyam.IamDataFrame.


An introduction to the basic functions is shown in the "first-steps" notebook.

All tutorials are available in rendered format (i.e., with output) as part of the online documentation. The source code of the tutorials notebooks is available in the folder doc/source/tutorials of this repository.


The comprehensive documentation is hosted on Read the Docs.

The documentation pages can be built locally, refer to the instruction in doc/README.

Authors & Contributors

This package was initiated and is currently maintained by Matthew Gidden (@gidden) and Daniel Huppmann (@danielhuppmann).

See the complete list of contributors.


Copyright 2017-2021 IIASA and the pyam developer team

The pyam package is licensed under the Apache License, Version 2.0 (the "License");
see LICENSE and NOTICE for details.


For basic instructions, please read the docs!

To install from source (including all dependencies) after cloning this repository, simply run

pip install --editable .[tests,optional-io-formats,tutorials]

To check that the package was installed correctly, run

pytest tests