The ixmp4 data model

The ixmp4 package is a data warehouse for scenario data related to numerical modeling of climate policy, energy systems transition and sustainable development.

This page is based on the section “The pyam data model” [1].

A scenario run

An ixmp4 database contains data for “scenario runs”, which can be one of the following:

  • Input data and quantitative results of an integrated assessment, a macro-energy or an energy systems model (often called a scenario for simplicity).

  • Input data and quantitative results of a (simple) climate model.

  • (Processed) data from a reference source or statistics database, e.g., IEA World Energy Statistics and Balances.

  • Aggregate indicators or timeseries data generated from several runs (e.g. multi-model mean for a specific scenario protocol).

A scenario run is identified by the following index attributes:

  • model name

  • scenario name, e.g., indicating a “scenario protocol”

  • version number to distinguish several implementations of a scenario protocol

  • a run-id for unique identification in the database

A scenario run can have the data types shown below.

The IAMC timeseries data format


The Integrated Assessment Modeling Consortium (IAMC) developed a standardised tabular timeseries format to exchange scenario data related to energy systems modelling, land-use change, demand sectors, and economic indicators in the context of the Sustainable Development Goals. Previous high-level use cases include reports by the Intergovernmental Panel on Climate Change (IPCC) and model comparison exercises within the Energy Modeling Forum (EMF) hosted by Stanford University.

The table below shows a typical example of integrated-assessment scenario data following the IAMC format from the Horizon 2020 CD-LINKS project.


Illustrative example of IAMC-format timeseries data via the IAMC 1.5°C Scenario Explorer ([2])

Supported time domains

The implementation of the IAMC-format timeseries data format in ixmp4 supports three temporal domains:

  • Yearly data: time domain represented as integer values

  • Continuous-time subannual data: using the datetime.datetime format

  • Categorical sub-annual timeslices: using a combination of yearly data (as integer) and a “category” value (as string), e.g., “peak-demand”, “winter-night”

A run can simultaneously have timeseries data for all temporal domains.


The iamc data type is closely related to the data attribute of a pyam.IamDataFrame.
Read the docs for the pyam ‘data’ data model.

Meta indicators

Meta indicators are intended for categorisation and quantitative indicators for each run. Common use cases are the warming category of a scenario (‘Below 1.5°C’, ‘1.5°C with low overshoot’, etc.) and the cumulative CO2 emissions until the end of the century.

The meta indicators can be interpreted as a tabular structure






“1.5°C with low overshoot”

Alternatively, the indicators can be interpreted as a nested dictionary such as

  1: {
    warming-category: "1.5°C with low overshoot",


The meta data type is closely related to the meta attribute of a pyam.IamDataFrame.
Read the docs for the pyam ‘meta’ data model