Release candidate 0.11.0 (#516)

README.md

@@ -1,7 +1,7 @@
 pyam: analysis & visualization <br /> of integrated-assessment scenarios
 ========================================================================
 
-[![license](https://img.shields.io/badge/License-Apache%202.0-black)](https://github.com/IAMconsortium/pyam/blob/master/LICENSE)
+[![license](https://img.shields.io/badge/License-Apache%202.0-black)](https://github.com/IAMconsortium/pyam/blob/main/LICENSE)
 [![pypi](https://img.shields.io/pypi/v/pyam-iamc.svg)](https://pypi.python.org/pypi/pyam-iamc/)
 [![conda](https://anaconda.org/conda-forge/pyam/badges/version.svg)](https://anaconda.org/conda-forge/pyam)
 [![latest](https://anaconda.org/conda-forge/pyam/badges/latest_release_date.svg)](https://anaconda.org/conda-forge/pyam)
@@ -11,7 +11,7 @@ pyam: analysis & visualization <br /> of integrated-assessment scenarios
 [![python](https://img.shields.io/badge/python-3.7_|_3.8_|_3.9-blue?logo=python&logoColor=white)](https://github.com/IAMconsortium/pyam)
 [![pytest](https://github.com/IAMconsortium/pyam/actions/workflows/pytest.yml/badge.svg)](https://github.com/IAMconsortium/pyam/actions/workflows/pytest.yml)
 [![ReadTheDocs](https://readthedocs.org/projects/pyam-iamc/badge/?version=latest)](https://pyam-iamc.readthedocs.io/en/latest/?badge=latest)
-[![codecov](https://codecov.io/gh/IAMconsortium/pyam/branch/master/graph/badge.svg)](https://codecov.io/gh/IAMconsortium/pyam)
+[![codecov](https://codecov.io/gh/IAMconsortium/pyam/branch/main/graph/badge.svg)](https://codecov.io/gh/IAMconsortium/pyam)
 
 [![doi](https://zenodo.org/badge/113359260.svg)](https://zenodo.org/badge/latestdoi/113359260)
 [![joss](https://joss.theoj.org/papers/10.21105/joss.01095/status.svg)](https://joss.theoj.org/papers/10.21105/joss.01095)

RELEASE_NOTES.md

@@ -1,4 +1,14 @@
-# Next Release
+# Release v0.11.0
+
+## Highlights
+
+- Easily order data in the line plot feature.
+- Add a module for reading data from the [UNFCCC Data Inventory](https://di.unfccc.int/).
+- Improved integration with any [IIASA Scenario Explorer instance](https://data.ece.iiasa.ac.at):
+  read non-default versions from the connected database
+  and obtain the "audit" info (scenario upload/edit timestamp and user).
+- Performance improvements when aggregating or concatenating data.
+- Refactor the entire code base to the [Black code style](https://black.readthedocs.io/).
 
 ## API changes
 

RELEASE_PROCEDURE.md

@@ -9,8 +9,8 @@
 
 ## Steps for publishing a new release
 
-1. Make a release candidate branch (e.g., `rc_v<release version>`)
-   and pull request it into `master` with the following updates:
+1. Make a release candidate branch (e.g., `release/rc_v<release version>`)
+   and pull request it into `main` with the following updates:
    1. If it's the first release in a new year,
       search for `Copyright 2017` and bump the year
    1. Deprecate any stated portion of the API
@@ -26,8 +26,8 @@
   1. Run `make publish-on-testpypi`
      - this should "just work" - if it does not, fix any issues,
        retag (`git tag -d` then `git tag`), and try again
-  1. Once successful, delete the tag, and merge the candidate PR into `master` on Github
-1. Switch to the now-updated master branch: `git checkout master` and `git pull upstream master`
+  1. Once successful, delete the tag, and merge the candidate PR into `main` on Github
+1. Switch to the now-updated main branch: `git checkout main` and `git pull upstream main`
 1. Tag the release number: `git tag v<release version>`, e.g., `git tag v1.2.0`
    - `versioneer` automatically updates the version number based on the tag
    - this is now the official tagged commit
@@ -46,7 +46,7 @@
 1. Confirm that the doc pages are updated on https://pyam-iamc.readthedocs.io/
    - both the **latest** and the **stable** versions point to the new release
    - the new release has been added to the list of available versions
-1. Add a new line "# Next Release" at the top of `RELEASE_NOTES.md` and commit to `master`
+1. Add a new line "# Next Release" at the top of `RELEASE_NOTES.md` and commit to `main`
 1. Announce it on our mailing list: https://groups.io/g/pyam
    - again, copy the rendered HTML from the Github release directly in the email
 

doc/source/api.rst

@@ -19,8 +19,6 @@ and methods.
    api/statistics
    api/timeseries
    api/variables
-   api/string_utils
-
 
 **Notebook logging behaviour**
 

doc/source/examples/plot_bar.py

@@ -14,7 +14,7 @@
 #
 # If you haven't cloned the **pyam** GitHub repository to your machine,
 # you can download the file from
-# https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
+# https://github.com/IAMconsortium/pyam/tree/main/doc/source/tutorials.
 #
 # Make sure to place the data file in the same folder as this script/notebook.
 

doc/source/examples/plot_boxplot.py

@@ -14,7 +14,7 @@
 #
 # If you haven't cloned the **pyam** GitHub repository to your machine,
 # you can download the file from
-# https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
+# https://github.com/IAMconsortium/pyam/tree/main/doc/source/tutorials.
 #
 # Make sure to place the data file in the same folder as this script/notebook.
 

doc/source/examples/plot_pie.py

@@ -14,7 +14,7 @@
 #
 # If you haven't cloned the **pyam** GitHub repository to your machine,
 # you can download the file from
-# https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
+# https://github.com/IAMconsortium/pyam/tree/main/doc/source/tutorials.
 #
 # Make sure to place the data file in the same folder as this script/notebook.
 

doc/source/examples/plot_ranges.py

@@ -14,7 +14,7 @@
 #
 # If you haven't cloned the **pyam** GitHub repository to your machine,
 # you can download the file from
-# https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
+# https://github.com/IAMconsortium/pyam/tree/main/doc/source/tutorials.
 #
 # Make sure to place the data file in the same folder as this script/notebook.
 

doc/source/examples/plot_sankey.py

@@ -24,7 +24,7 @@
 #
 # 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
+# https://github.com/IAMconsortium/pyam/tree/main/doc/source/examples_source
 #
 # Make sure to place the data file in the same folder as this script/notebook.
 

doc/source/examples/plot_stack.py

@@ -14,7 +14,7 @@
 #
 # If you haven't cloned the **pyam** GitHub repository to your machine,
 # you can download the file from
-# https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
+# https://github.com/IAMconsortium/pyam/tree/main/doc/source/tutorials.
 #
 # Make sure to place the data file in the same folder as this script/notebook.
 

doc/source/examples/plot_timeseries.py

@@ -12,7 +12,7 @@
 #
 # If you haven't cloned the **pyam** GitHub repository to your machine,
 # you can download the file from
-# https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials.
+# https://github.com/IAMconsortium/pyam/tree/main/doc/source/tutorials.
 #
 # Make sure to place the data file in the same folder as this script/notebook.
 

doc/source/index.rst

@@ -10,7 +10,7 @@ Release v\ |version|.
 |doi| |joss| |groupsio| |slack|
 
 .. |license| image:: https://img.shields.io/badge/License-Apache%202.0-black
-   :target: https://github.com/IAMconsortium/pyam/blob/master/LICENSE
+   :target: https://github.com/IAMconsortium/pyam/blob/main/LICENSE
 
 .. |pypi| image:: https://img.shields.io/pypi/v/pyam-iamc.svg
    :target: https://pypi.python.org/pypi/pyam-iamc/
@@ -34,7 +34,7 @@ Release v\ |version|.
    :target: https://pyam-iamc.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
 
-.. |codecov| image:: https://codecov.io/gh/IAMconsortium/pyam/branch/master/graph/badge.svg
+.. |codecov| image:: https://codecov.io/gh/IAMconsortium/pyam/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/IAMconsortium/pyam
 
 .. |doi| image:: https://zenodo.org/badge/113359260.svg

pyam/core.py

@@ -1088,7 +1088,7 @@ def convert_unit(
         'HFC236fa', etc., as well as lower-case aliases like 'co2' supported by
         :mod:`pyam`. In this case, *context* must be the name of a specific
         global warming potential (GWP) metric supported by :mod:`iam_units`,
-        e.g. 'AR5GWP100' (optionally prefixed by 'gwp_', e.g. 'gwp_AR5GWP100').
+        e.g. 'AR5GWP100' (optionally prefixed by '\gwp_', e.g. 'gwp_AR5GWP100').
 
         Rows with units other than *current* are not altered.
 
@@ -1607,6 +1607,7 @@ def filter(self, keep=True, inplace=False, **kwargs):
              - arguments for filtering by `datetime.datetime` or np.datetime64
                ('month', 'hour', 'time')
              - 'regexp=True' disables pseudo-regexp syntax in `pattern_match()`
+
         """
         if not isinstance(keep, bool):
             raise ValueError(f"Cannot filter by `keep={keep}`, must be a boolean!")

pyam/unfccc.py

@@ -37,27 +37,29 @@ def read_unfccc(
     IAM model comparison projects. For compatibility with the
     `iam-units <https://github.com/IAMconsortium/units>`_ package
     and the :meth:`convert_unit <IamDataFrame.convert_unit>`,
-    emissions species are formatted to standard text (:code:`CO2`)
-    instead of subscripts (:code:`CO₂`) and the unit ':code:`CO₂ equivalent`'
-    used by UNFCCC is replaced by ':code:`CO2e`'.
+    emissions species are formatted to standard text ('CO2')
+    instead of subscripts ('CO₂') and the unit 'CO₂ equivalent'
+    used by UNFCCC is replaced by 'CO2e'.
 
     Parameters
     ----------
     party_code : str
         ISO3-style code for UNFCCC party (country)
     gases : str or list of str, optional
         Emission species to be queried from the data inventory can be stated
-        as subscript-format (:code:`CO₂`) or simple text (:code:`CO2`)
+        as subscript-format ('CO₂') or simple text ('CO2')
     tier : int or list of int
         Pre-specified groupings of UNFCCC data to a variable naming format
         used in IPCC reports and IAM model comparison projects
     mapping : dict, optional
         Mapping to cast UNFCCC-data columns into IAMC-style variables, e.g.
-        ```
-        {
-            'Emissions|{gas}|Energy': ('1.  Energy', '*', '*', '*')
-        }
-        ```
+
+        .. code-block:: python
+
+            {
+                'Emissions|{gas}|Energy': ('1.  Energy', '*', '*', '*'),
+            }
+
         where the tuple corresponds to filters for the columns
         `['category', 'classification', 'measure', 'gas']`
         and `{<col>}` tags in the key are replaced by the column value.