Sankey diagram

Read in example data and show a summary

This gallery uses a small selection of the data compiled for the IPCC’s Special Report on Global Warming of 1.5°C (SR15). The complete scenario ensemble data is publicly available from the IAMC 1.5°C Scenario Explorer and Data hosted by IIASA.

Please read the License of the IAMC 1.5°C Scenario Explorer before using the full scenario data for scientific analyis or other work.

If you haven’t cloned the pyam GitHub repository to your machine, you can download the data file from

Make sure to place the data file in the same folder as this script/notebook.

import plotly

import pyam

df = pyam.IamDataFrame("sankey_data.csv")
/home/docs/checkouts/ FutureWarning:

The previous implementation of stack is deprecated and will be removed in a future version of pandas. See the What's New notes for pandas 2.1.0 for details. Specify future_stack=True to adopt the new implementation and silence this warning.

<class 'pyam.core.IamDataFrame'>
 * model    : IMAGE 3.0.1 (1)
 * scenario : CD-LINKS_NPi2020_1000 (1)
Timeseries data coordinates:
   region   : World (1)
   variable : Final Energy|Electricity, ... (9)
   unit     : EJ/yr (1)
   year     : 2005, 2010, 2015, 2020, 2025, 2030, 2035, 2040, ... 2100 (15)

A simple Sankey diagram

We show a Sankey diagram of a subset of the energy system in the ‘CD-LINKS_NPi2020_1000’ scenario implemented by the ‘REMIND-MAgPIE 1.7-3.0’ model.

The sankey() function takes a dictionary to define flows, sources and targets:

    variable: (source, target),
sankey_mapping = {
    "Primary Energy|Coal": ("Coal Mining", "Coal Trade & Power Generation"),
    "Primary Energy|Gas": ("Natural Gas Extraction", "Gas Network & Power Generation"),
    "Secondary Energy|Electricity|Non-Biomass Renewables": (
        "Non-Biomass Renewables",
        "Electricity Grid",
    "Secondary Energy|Electricity|Nuclear": ("Nuclear", "Electricity Grid"),
    "Secondary Energy|Electricity|Coal": (
        "Coal Trade & Power Generation",
        "Electricity Grid",
    "Secondary Energy|Electricity|Gas": (
        "Gas Network & Power Generation",
        "Electricity Grid",
    "Final Energy|Electricity": ("Electricity Grid", "Electricity Demand"),
    "Final Energy|Solids|Coal": (
        "Coal Trade & Power Generation",
        "Non-Electricity Coal Demand",
    "Final Energy|Gases": ("Gas Network & Power Generation", "Gas Demand"),

fig = df.filter(year=2050).plot.sankey(mapping=sankey_mapping)
# calling `show()` is necessary to have the thumbnail in the gallery overview
/home/docs/checkouts/ FutureWarning:

Downcasting behavior in `replace` is deprecated and will be removed in a future version. To retain the old behavior, explicitly call `result.infer_objects(copy=False)`. To opt-in to the future behavior, set `pd.set_option('future.no_silent_downcasting', True)`

Total running time of the script: (0 minutes 9.008 seconds)

Gallery generated by Sphinx-Gallery