Add a sankey-example to the plotting gallery (#472)

RELEASE_NOTES.md

@@ -13,9 +13,10 @@ are ordered based on the `run_control()['order']` dictionary by default.
 
 ## Individual updates
 
+- [#472](https://github.com/IAMconsortium/pyam/pull/472) Add a ´sankey()` example to the plotting gallery
 - [#470](https://github.com/IAMconsortium/pyam/pull/470) Add two types of `order` arg to `barplot()`
 - [#467](https://github.com/IAMconsortium/pyam/pull/467) Refactor the GAMS-pyam tutorial to use the gamstransfer module
-- [#466](https://github.com/IAMconsortium/pyam/pull/466) Add a `sankey()`function to create sankey diagrams
+- [#466](https://github.com/IAMconsortium/pyam/pull/466) Add a `sankey()` function to create sankey diagrams
 - [#464](https://github.com/IAMconsortium/pyam/pull/464) Add `order` arg to `stackplot()`
 - [#463](https://github.com/IAMconsortium/pyam/pull/463) Clarification of initialization-error message if file does not exist
 

doc/source/conf.py

@@ -11,14 +11,12 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
-
-# has to go first for environment setup reasons
-import matplotlib
-matplotlib.use('agg')
-
 from datetime import datetime
 import pyam
 
+from sphinx_gallery.sorting import ExplicitOrder
+from plotly.io._sg_scraper import plotly_sg_scraper
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -32,7 +30,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'numpydoc',
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
@@ -41,18 +41,12 @@
     'sphinx.ext.viewcode',
     'sphinxcontrib.bibtex',
     'sphinxcontrib.programoutput',
-    'cloud_sptheme.ext.table_styling',
-    'numpydoc',
     'nbsphinx',
     'sphinx_gallery.gen_gallery',
+    'cloud_sptheme.ext.table_styling',
 ]
 
-sphinx_gallery_conf = {
-    # path to your examples scripts
-    'examples_dirs': '_examples',
-    # path where to save gallery generated examples
-    'gallery_dirs': 'examples'
-}
+autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -330,6 +324,30 @@
         ('https://pandas-datareader.readthedocs.io/en/stable', None)
 }
 
+# Set up the plotting gallery with plotly scraper
+image_scrapers = ('matplotlib', plotly_sg_scraper,)
+
+sphinx_gallery_conf = {
+    'doc_module': ('plotly',),
+    # path to your examples scripts
+    'examples_dirs': 'examples_source',
+    # path where to save gallery generated examples
+    'gallery_dirs': 'examples',
+    'subsection_order':
+        ExplicitOrder(['../examples/plot_timeseries',
+                       '../examples/plot_ranges',
+                       '../examples/plot_stack',
+                       '../examples/plot_bar',
+                       '../examples/plot_boxplot',
+                       '../examples/plot_pie',
+                       '../examples/plot_sankey']),
+    'reference_url': {'plotly': None,},
+    'image_scrapers': image_scrapers,
+}
+
+# Link or path to require.js, set to empty string to disable
+nbsphinx_requirejs_path = ''
+
 # Extend the timeout limit for running notebooks
 nbsphinx_timeout = 120
 

doc/source/_examples/plot_bar.py → doc/source/examples_source/plot_bar.py

@@ -16,7 +16,7 @@
 # you can download the file from
 # https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
 #
-# Make sure to place the file in the same folder as this script/notebook.
+# Make sure to place the data file in the same folder as this script/notebook.
 
 import matplotlib.pyplot as plt
 import pyam
@@ -36,7 +36,9 @@
 data = df.filter(**args, variable='Primary Energy|*', region='World')
 
 data.barplot(stacked=True, title='Primary energy mix')
+plt.legend(loc=1)
 plt.tight_layout()
+plt.show()
 
 ###############################
 # Flip the direction of a stacked bar chart
@@ -45,7 +47,9 @@
 # We can flip that round for a horizontal chart.
 
 data.barplot(stacked=True, orient='h', title='Primary energy mix')
+plt.legend(loc=1)
 plt.tight_layout()
+plt.show()
 
 ###############################
 # Show stacked bar chart by regions
@@ -62,7 +66,9 @@
 
 data.barplot(bars='region', stacked=True,
              title='CO2 emissions by region', cmap='tab20')
+plt.legend(loc=1)
 plt.tight_layout()
+plt.show()
 
 ###############################
 # Add indicators to show net values
@@ -77,4 +83,6 @@
 data.barplot(ax=ax, bars='region', stacked=True,
              title='CO2 emissions by region', cmap='tab20')
 add_net_values_to_barplot(ax)
+plt.legend(loc=1)
 plt.tight_layout()
+plt.show()

doc/source/_examples/plot_boxplot.py → doc/source/examples_source/plot_boxplot.py

@@ -16,7 +16,7 @@
 # you can download the file from
 # https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
 #
-# Make sure to place the file in the same folder as this script/notebook.
+# Make sure to place the data file in the same folder as this script/notebook.
 
 import matplotlib.pyplot as plt
 import pyam
@@ -33,8 +33,8 @@
 data = df.filter(scenario='CD-LINKS_NPi2020_1000',
                  variable='Emissions|CO2', region='World')
 
-fig, ax = plt.subplots()
-data.boxplot(x='year', ax=ax)
+data.boxplot(x='year')
+plt.tight_layout()
 plt.show()
 
 ###############################
@@ -49,9 +49,9 @@
     .filter(region='World', keep=False)
 )
 
-fig, ax = plt.subplots()
-data.boxplot(x='year', by='region', legend=True, ax=ax)
+data.boxplot(x='year', by='region', legend=True)
 
 # We can use matplotlib arguments to make the figure more appealing.
 plt.legend(loc=1)
+plt.tight_layout()
 plt.show()

doc/source/_examples/plot_pie.py → doc/source/examples_source/plot_pie.py

@@ -16,7 +16,7 @@
 # you can download the file from
 # https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
 #
-# Make sure to place the file in the same folder as this script/notebook.
+# Make sure to place the data file in the same folder as this script/notebook.
 
 import matplotlib.pyplot as plt
 import pyam
@@ -34,9 +34,8 @@
                  variable='Primary Energy|*', year=2050,
                  region='World')
 
-fig, ax = plt.subplots()
-data.pie_plot(ax=ax)
-fig.subplots_adjust(right=0.75, left=0.3)
+data.pie_plot()
+plt.tight_layout()
 plt.show()
 
 ###############################
@@ -45,9 +44,8 @@
 #
 # Sometimes a legend is preferable to labels, so we can use that instead.
 
-fig, ax = plt.subplots()
-data.pie_plot(ax=ax, labels=None, legend=True)
-fig.subplots_adjust(right=0.55, left=-0.05)
+data.pie_plot(labels=None, legend=True)
+plt.tight_layout()
 plt.show()
 
 ###############################
@@ -64,3 +62,5 @@
     .filter(region='World', keep=False)
 )
 data.pie_plot(category='region', cmap='tab20')
+plt.tight_layout()
+plt.show()

doc/source/_examples/plot_ranges.py → doc/source/examples_source/plot_ranges.py

@@ -16,7 +16,7 @@
 # you can download the file from
 # https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
 #
-# Make sure to place the file in the same folder as this script/notebook.
+# Make sure to place the data file in the same folder as this script/notebook.
 
 import matplotlib.pyplot as plt
 import pyam
@@ -33,8 +33,8 @@
 data = df.filter(scenario='CD-LINKS*',
                  variable='Emissions|CO2', region='World')
 
-fig, ax = plt.subplots()
-data.line_plot(ax=ax, color='scenario', fill_between=True)
+data.line_plot(color='scenario', fill_between=True)
+plt.tight_layout()
 plt.show()
 
 ###############################
@@ -45,8 +45,8 @@
 # or it can be provided specific arguments as a dictionary:
 # in this illustration, we choose a very low transparency value.
 
-fig, ax = plt.subplots()
-data.line_plot(ax=ax, color='scenario', fill_between=dict(alpha=0.15))
+data.line_plot(color='scenario', fill_between=dict(alpha=0.15))
+plt.tight_layout()
 plt.show()
 
 ###############################
@@ -57,7 +57,7 @@
 # range of data in the final time period using `final_ranges`. Similar to
 # `fill_between` it can either be true or have specific arguments.
 
-fig, ax = plt.subplots()
-data.line_plot(ax=ax, color='scenario', fill_between=True,
+data.line_plot(color='scenario', fill_between=True,
                final_ranges=dict(linewidth=5))
+plt.tight_layout()
 plt.show()

doc/source/examples_source/plot_sankey.py

@@ -0,0 +1,75 @@
+"""
+==============
+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.
+#
+# .. _SR15: http://ipcc.ch/sr15/
+#
+# .. _`IAMC 1.5°C Scenario Explorer and Data hosted by IIASA` : https://data.ene.iiasa.ac.at/iamc-1.5c-explorer
+#
+# .. _License : https://data.ene.iiasa.ac.at/iamc-1.5c-explorer/#/license
+#
+# If you haven't cloned the **pyam** GitHub repository to your machine,
+# you can download the data file from
+# https://github.com/IAMconsortium/pyam/tree/master/doc/source/examples_source
+#
+# Make sure to place the data file in the same folder as this script/notebook.
+
+import pyam
+import plotly
+df = pyam.IamDataFrame('sankey_data.csv')
+df
+
+###############################
+# 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 :meth:`~pyam.figures.sankey` function
+# takes a dictionary to define flows, sources and targets:
+#
+# .. code-block:: python
+#
+#     {
+#         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).sankey(mapping=sankey_mapping)
+# calling `show()` is necessary to have the thumbnail in the gallery overview
+plotly.io.show(fig)

doc/source/_examples/plot_stack.py → doc/source/examples_source/plot_stack.py

@@ -16,7 +16,7 @@
 # you can download the file from
 # https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
 #
-# Make sure to place the file in the same folder as this script/notebook.
+# Make sure to place the data file in the same folder as this script/notebook.
 
 import matplotlib.pyplot as plt
 import pyam
@@ -27,11 +27,13 @@
 # First, we generate a simple stacked line chart
 # of all components of primary energy supply for one scenario.
 
-data = df.filter(model='IMAGE 3.0.1', scenario='CD-LINKS_NPi2020_400',
+model, scenario = 'IMAGE 3.0.1', 'CD-LINKS_NPi2020_400'
+
+data = df.filter(model=model, scenario=scenario,
                  variable='Primary Energy|*', region='World')
 
-fig, ax = plt.subplots()
-data.stackplot(ax=ax)
+data.stackplot(title=scenario)
+plt.legend(loc=1)
 plt.tight_layout()
 plt.show()
 
@@ -41,12 +43,12 @@
 # Here, we show the contribution by region to total CO2 emissions.
 
 data = (
-    df.filter(model='IMAGE 3.0.1', scenario='CD-LINKS_NPi2020_400',
-              variable='Emissions|CO2')
+    df.filter(model=model, scenario=scenario, variable='Emissions|CO2')
     .filter(region='World', keep=False)
 )
 
-fig, ax = plt.subplots()
-data.stackplot(ax=ax, stack='region', cmap='tab20', total=True)
+data.stackplot(stack='region', cmap='tab20',
+               title=scenario, total=True)
+plt.legend(loc=1)
 plt.tight_layout()
 plt.show()

doc/source/_examples/plot_timeseries.py → doc/source/examples_source/plot_timeseries.py

@@ -14,7 +14,7 @@
 # you can download the file from
 # https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
 #
-# Make sure to place the file in the same folder as this script/notebook.
+# Make sure to place the data file in the same folder as this script/notebook.
 
 import pyam
 df = pyam.IamDataFrame('tutorial_data.csv')
@@ -29,9 +29,10 @@
 #
 # Then, also show the data as a wide IAMC-style dataframe.
 
+model, scenario = 'REMIND-MAgPIE 1.7-3.0', 'CD-LINKS_INDCi'
+
 data = (
-    df.filter(model='REMIND-MAgPIE 1.7-3.0', scenario='CD-LINKS_INDCi',
-              variable='Emissions|CO2')
+    df.filter(model=model, scenario=scenario, variable='Emissions|CO2')
     .filter(region='World', keep=False)
 )