an open-source Python package for IAM scenario analysis and visualization
Switch branches/tags
Nothing to show
Clone or download

pyam: a Python toolkit for Integrated Assessment Modeling

The pyam package is still under heavy development; public and private APIs are subject to change.

Questions? Start a discussion on our listserv

Overview and scope

The pyam package provides a range of diagnostic tools and functions for analyzing and working with IAMC-format timeseries data.


  • Summary of models, scenarios, variables, and regions included in a snapshot.
  • Display of timeseries data as pandas.DataFrame with IAMC-specific filtering options.
  • Simple visualization and plotting functions.
  • Diagnostic checks for non-reported variables or timeseries data to identify outliers and potential reporting issues.
  • Categorization of scenarios according to timeseries data or meta-identifiers for further analysis.

The package can be used with timeseries data that follows the data template convention of the Integrated Assessment Modeling Consortium (IAMC). An illustrative example is shown below; see for more information.

model scenario region variable unit 2005 2010 2015
MESSAGE V.4 AMPERE3-Base World Primary Energy EJ/y 454.5 479.6 ...
... ... ... ... ... ... ... ...


A comprehensive tutorial for the basic functions is included in tutorial/pyam_first_steps using a partial snapshot of the IPCC AR5 scenario database.


The documentation pages can be built locally. See the instruction in doc/README.


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


Copyright 2017-2018 IIASA Energy Program

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

Python dependencies

  1. pandas v0.21.0 or higher
  2. matplotlib
  3. seaborn
  4. geopandas (optional)
  5. cartopy (optional)

Documentation Building Depedencies

  1. Sphinx <>_ v1.1.2 or higher
  2. sphinxcontrib.bibtex
  3. sphinxcontrib-fulltoc
  4. sphinx-gallery

Installation instructions

  1. Fork this repository and clone the forked repository (<user>/pyam) to your machine. To fork the repository, look for the fork icon in the top right at iiasa/pyam. Add iiasa/pyam as upstream to your clone.

    We recommend GitKraken for users who prefer a graphical user interface application to work with Github (as opposed to the command line).

Windows Users

  1. Double click on install.bat in the local folder where you cloned your fork.

*nix Users

  1. In a command prompt, execute the following command

    python install