Release candidate 0.10.0 (#478)

NOTICE.md

@@ -1,4 +1,4 @@
-   Copyright 2017-2020 IIASA and the pyam developer team
+   Copyright 2017-2021 IIASA and the pyam developer team
 
    The **pyam** package is licensed under
    the Apache License, Version 2.0 (the "License");

README.md

@@ -85,7 +85,7 @@ See the complete [list of contributors](AUTHORS.rst).
 License
 -------
 
-Copyright 2017-2020 IIASA and the pyam developer team
+Copyright 2017-2021 IIASA and the pyam developer team
 
 The **pyam** package is licensed
 under the Apache License, Version 2.0 (the "License");

RELEASE_NOTES.md

@@ -1,4 +1,11 @@
-# Next Release
+# Release v0.10.0
+
+## Highlights
+
+ - Refactor the plotting library for better UX and consistency with **pandas**,
+   **matplotlib** and **seaborn**.
+ - Add a `sankey()` feature to the plotting library.
+ - Rework the documentation and tutorials.
 
 ## API changes
 
@@ -18,7 +25,7 @@ are ordered based on the `run_control()['order']` dictionary by default.
 
 - [#475](https://github.com/IAMconsortium/pyam/pull/475) Add a scatter plot example to the gallery
 - [#473](https://github.com/IAMconsortium/pyam/pull/473) Refactor to plotting API following pandas/matplotlib implementation
-- [#472](https://github.com/IAMconsortium/pyam/pull/472) Add a ´sankey()` example to the plotting gallery
+- [#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

doc/source/conf.py

@@ -65,7 +65,7 @@
 # General information about the project.
 project = u'pyam'
 year = datetime.now().year
-copyright = '{}, IIASA and the pyam developer team'.format(year)
+copyright = '2017-{}, IIASA and the pyam developer team'.format(year)
 author = u'pyam developer team'
 
 # The version info for the project you're documenting, acts as replacement for

doc/source/examples/plot_bar.py

@@ -77,12 +77,12 @@
 # Sometimes, stacked bar charts have negative entries.
 # In that case, it helps to add a line showing the net value.
 
-from pyam.plotting import add_net_values_to_barplot
+from pyam.plotting import add_net_values_to_bar_plot
 
 fig, ax = plt.subplots()
 data.plot.bar(ax=ax, bars='region', stacked=True,
               title='CO2 emissions by region', cmap='tab20')
-add_net_values_to_barplot(ax)
+add_net_values_to_bar_plot(ax)
 plt.legend(loc=1)
 plt.tight_layout()
 plt.show()

doc/source/tutorials/GAMS_to_pyam.ipynb

@@ -20,8 +20,11 @@
     "1. Manually install the GAMS API,\n",
     "   follow one of the options in [this description](https://www.gams.com/latest/docs/API_PY_TUTORIAL.html).\n",
     "   \n",
-    "   > **TL;DR**: seach for the folder `api_38` in the GAMS installation folder on your machine\n",
-    "     and run `python setup.py install`.\n",
+    "   > **TL;DR**: seach for the folder \"api_38\" in the GAMS installation folder on your machine\n",
+    "   > and run\n",
+    "   > ```\n",
+    "   > python setup.py install\n",
+    "   > ```\n",
     "\n",
     "2. Install the **schema** package via\n",
     "   ```\n",
@@ -36,7 +39,7 @@
     "**Developers note:**\n",
     "Running this notebook on CI and RTD is a challenge\n",
     "due to the need to download and install the GAMS API.  \n",
-    "For the time being, this notebook is not executed by `nbsphinx`\n",
+    "For the time being, this notebook is not executed by **nbsphinx**\n",
     "and has to be saved with output."
    ]
   },

doc/source/tutorials/aggregating_downscaling_consistency.ipynb

@@ -7,7 +7,7 @@
     "# Aggregating and downscaling timeseries data\n",
     "\n",
     "The **pyam** package offers many tools to facilitate processing of scenario data.\n",
-    "In this notebook, we illustrate methods to aggregate and downscale timeseries data of an `IamDataFrame` across regions and sectors, as well as checking consistency of given data along these dimensions.\n",
+    "In this notebook, we illustrate methods to aggregate and downscale timeseries data of an **IamDataFrame** across regions and sectors, as well as checking consistency of given data along these dimensions.\n",
     "\n",
     "In this tutorial, we show how to make the most of **pyam** to compute such aggregate timeseries data, and to check that a scenario ensemble (or just a single scenario) is complete and that timeseries data \"add up\" across regions and along the variable tree (i.e., that the sum of values of the subcategories such as `Primary Energy|*` are identical to the values of the category `Primary Energy`).\n",
     "\n",
@@ -71,7 +71,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df.regions()"
+    "df.region"
    ]
   },
   {
@@ -80,7 +80,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df.variables()"
+    "df.variable"
    ]
   },
   {
@@ -107,7 +107,7 @@
    "source": [
     "Next, we are going to use the [aggregate()](https://pyam-iamc.readthedocs.io/en/stable/api/iamdataframe.html#pyam.IamDataFrame.aggregate) function to compute the total `Primary Energy` from its components (wind and coal) in each region (including `World`).\n",
     "\n",
-    "The function returns an `IamDataFrame`, so we can use [timeseries()](https://pyam-iamc.readthedocs.io/en/stable/api/iamdataframe.html#pyam.IamDataFrame.timeseries) to display the resulting data."
+    "The function returns an **IamDataFrame**, so we can use [timeseries()](https://pyam-iamc.readthedocs.io/en/stable/api/iamdataframe.html#pyam.IamDataFrame.timeseries) to display the resulting data."
    ]
   },
   {
@@ -123,7 +123,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If we are interested in **use case 1**, we could use the argument `append=True` to directly add the computed aggregate to the `IamDataFrame`.\n",
+    "If we are interested in **use case 1**, we could use the argument `append=True` to directly add the computed aggregate to the **IamDataFrame** instance.\n",
     "\n",
     "However, in this tutorial, the data already includes the total primary energy demand. Therefore, we illustrate **use case 2** and apply the [check_aggregate()](https://pyam-iamc.readthedocs.io/en/stable/api/iamdataframe.html#pyam.IamDataFrame.check_aggregate) function to  verify whether a given variable is the sum of its sectoral components\n",
     "(i.e., `Primary Energy` should be equal to `Primary Energy|Coal` plus `Primary Energy|Wind`).\n",
@@ -259,7 +259,7 @@
     "\n",
     "0. The carbon price data across the regions\n",
     "1. A (failing) validation that the regional aggretion (without weights) matches the reported prices at the `World` level\n",
-    "2. The emissions-weighted average of carbon prices returned as a new `IamDataFrame`"
+    "2. The emissions-weighted average of carbon prices returned as a new **IamDataFrame**"
    ]
   },
   {
@@ -389,7 +389,7 @@
     "This feature of the **pyam** package currently only supports \"consistency\"\n",
     "in the sense of a strictly hierarchical variable tree\n",
     "(with subcategories summing up to the category value including components, discussed above)\n",
-    "and that all the regions sum to the ``World`` region.  \n",
+    "and that all the regions sum to the 'World' region.  \n",
     "See [this issue](https://github.com/IAMconsortium/pyam/issues/106) for more information.\n",
     "\n",
     "</div>\n",

doc/source/tutorials/data_table_formats.ipynb

@@ -12,7 +12,7 @@
     "([IAMC](https://www.iamconsortium.org/));\n",
     "[read the docs](https://pyam-iamc.readthedocs.io/en/stable/data.html) for more information.\n",
     "\n",
-    "Alas, to make using the package as easy as possible, iniatilizing an `IamDataFrame` will accept a variety of different table formats\n",
+    "Alas, to make using the package as easy as possible, iniatilizing an **IamDataFrame** will accept a variety of different table formats\n",
     "and allows specifying missing columns via keyword arguments.\n",
     "This way, a user can import their data into **pyam** as easily as possible without needing to worry (more than necessary) about manipulating the original, raw timeseries data.\n",
     "\n",
@@ -23,18 +23,18 @@
     "\n",
     "The first section shows the standard [pandas.DataFrame](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html) (a.k.a. table) used in the **pyam** test suite.\n",
     "The following sections shows modifications of this dataframe\n",
-    "and the necessary (if any) additional specifications to initialize an `IamDataFrame`.\n",
+    "and the necessary (if any) additional specifications to initialize an **IamDataFrame**.\n",
     "The last cell of each section uses the [equals()](https://pyam-iamc.readthedocs.io/en/stable/api/iamdataframe.html#pyam.IamDataFrame.equals) function\n",
-    "to assert that the `IamDataFrame` in that section is identical to the object in the first section.\n",
+    "to assert that the **IamDataFrame** in that section is identical to the object in the first section.\n",
     "\n",
-    "It does not matter whether an `IamDataFrame` is initialized from a [pandas.DataFrame](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html)\n",
+    "It does not matter whether an **IamDataFrame** is initialized from a [pandas.DataFrame](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html)\n",
     "or a path to a `xslsx`/`csv` file with the data in the given format.\n",
     "For simplicity, this tutorial only uses dataframes.\n",
     "\n",
     "<div class=\"alert alert-info\">\n",
     "\n",
     "The default columns (a.k.a. index or dimensions) of the IAMC data format are  \n",
-    "`pyam.IAMC_IDX = ['model', 'scenario', 'region', 'variable', 'unit']`.  \n",
+    "`pyam.IAMC_IDX = ['model', 'scenario', 'region', 'variable', 'unit']`.<br />\n",
     "The last section of this tutorial illustrates the use of additional, custom columns.\n",
     "\n",
     "</div>"
@@ -58,7 +58,7 @@
     "\n",
     "The first cell creates a \"simple dataframe\" in the standard *wide* IAMC format.\n",
     "\n",
-    "It then casts that dataframe to an `IamDataFrame`\n",
+    "It then casts that dataframe to an **IamDataFrame**\n",
     "and uses the [timeseries()](https://pyam-iamc.readthedocs.io/en/stable/api/iamdataframe.html#pyam.IamDataFrame.timeseries) function\n",
     "to again show the data in the standard format."
    ]
@@ -398,7 +398,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Postscriptum: custom data columns in an `IamDataFrame`\n",
+    "## Postscriptum: custom data columns in an IamDataFrame\n",
     "\n",
     "This final section illustrates the behaviour of **pyam** when working with non-standard columns.\n",
     "\n",

doc/source/tutorials/iiasa_dbs.ipynb

@@ -137,7 +137,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ax = df.scatter(\n",
+    "ax = df.plot.scatter(\n",
     "    x='Primary Energy|Coal', \n",
     "    y='Emissions|CO2', \n",
     "    color='category',\n",
@@ -213,8 +213,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A number of different categorization and quantitative indicators are available for model/scenario combinations.\n",
-    "These are usually called `meta` indicators in **pyam**.\n",
+    "A number of different categorization and quantitative indicators are available for model/scenario combinations.  \n",
+    "These are usually called 'meta' indicators in **pyam**.\n",
     "\n",
     "We queried the meta-indicator \"category\" in the above example, but there are many more.\n",
     "You can get a list with the following command:"