Release candidate 1.0 (#553)

.github/workflows/pytest-dependency.yml

@@ -23,8 +23,8 @@ jobs:
         python-version: '3.7'
 
     - name: Install specific out-dated version of dependencies
-      # Update the corresponding package requirements when changing
-      # minimum dependency versions
+      # Update the package requirements when changing minimum dependency versions
+      # Please also add a section "Dependency changes" to the release notes
       run: pip install pandas==1.1.1 matplotlib==3.2.0 iam-units==2020.4.21
 
     - name: Install other dependencies and package

README.md

@@ -14,9 +14,10 @@ pyam: analysis & visualization <br /> of integrated-assessment and macro-energy
 [![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)
+[![ORE](https://img.shields.io/badge/ORE-10.12688/openreseurope.13633.1-blue)](https://doi.org/10.12688/openreseurope.13633.1)
 [![joss](https://joss.theoj.org/papers/10.21105/joss.01095/status.svg)](https://joss.theoj.org/papers/10.21105/joss.01095)
-[![groups.io](https://img.shields.io/badge/groups.io-pyam-blue)](https://pyam.groups.io/g/forum)
-[![slack](https://img.shields.io/badge/slack-@pyam-orange.svg?logo=slack)](https://pyam-iamc.slack.com)
+[![groups.io](https://img.shields.io/badge/listserv-groups.io-blue)](https://pyam.groups.io/g/forum)
+[![slack](https://img.shields.io/badge/chat-Slack-orange)](https://pyam-iamc.slack.com)
 
 ****
 
@@ -95,6 +96,35 @@ and Daniel Huppmann ([@danielhuppmann](https://github.com/danielhuppmann/)).
 
 See the complete [list of contributors](AUTHORS.rst).
 
+Scientific publications
+-----------------------
+
+The following manuscripts describe the **pyam** package
+at specific stages of development.
+
+### Release v1.0 (June 2021)
+
+Published to mark the first major release of the **pyam** package.
+
+> Daniel Huppmann, Matthew Gidden, Zebedee Nicholls, Jonas Hörsch, Robin Lamboll,
+Paul Natsuo Kishimoto, Thorsten Burandt, Oliver Fricko, Edward Byers, Jarmo Kikstra,
+Maarten Brinkerink, Maik Budzinski, Florian Maczek, Sebastian Zwickl-Bernhard,
+Lara Welder, Erik Francisco Alvarez Quispe, and Christopher J. Smith.
+*pyam: Analysis and visualisation of integrated assessment and macro-energy scenarios.*
+**Open Research Europe**, 2021.
+doi: [10.12688/openreseurope.13633.1](https://doi.org/10.12688/openreseurope.13633.1)
+
+### Release v0.1.2 (November 2018)
+
+Published following the successful application of **pyam**
+in the IPCC SR15 and the Horizon 2020 CRESCENDO project.
+
+> Matthew Gidden and Daniel Huppmann.
+*pyam: a Python package for the analysis and visualization of models of the interaction
+of climate, human, and environmental systems.*
+**Journal of Open Source Software (JOSS)**, 4(33):1095, 2019.
+doi: [10.21105/joss.01095](https://doi.org/10.21105/joss.01095).
+
 License
 -------
 

RELEASE_PROCEDURE.md

@@ -17,7 +17,8 @@
       (you can find them by searching the code base for "deprecate")
    1. Update `RELEASE_NOTES.md` (see the examples of previous releases)
 	  - replace "# Next Release" with "# Release v<release version>"
-	  - for this new release, add a "## Highlights" section with the most important updates & changes
+	  - add a "## Highlights" section with the most important updates & changes
+      - if applicable, add/review "## Dependency changes" and "## API changes" sections 
       - add a new heading "## Individual Updates" before the PR listing
   1. Confirm that the PR passes all tests and checks
   1. Tag the release number: `git tag v<release version>`, e.g., `git tag v1.2.0`
@@ -40,7 +41,9 @@
    - copy the release summary from `RELEASE_NOTES.md` into the description box
 1. Update on `conda-forge`
    - a PR should automatically be opened by the bot after the Github release
-   - confirm that any new depedencies are added there
+   - confirm that any new depedencies are included,
+     change the minimum dependency version if necessary
+     (compare to ./.github/workflows/pytest-depedency.yml)
    - merge the PR
    - check that the new version is available at https://anaconda.org/conda-forge/pyam
 1. Confirm that the doc pages are updated on https://pyam-iamc.readthedocs.io/

doc/source/_bib/references.bib

@@ -1,7 +1,18 @@
+@Article{Huppmann:2021:pyam-v1.0,
+  author = {Huppmann, Daniel and Gidden, Matthew and Nicholls, Zebedee and
+    Hörsch, Jonas and Lamboll, Robin and Kishimoto, Paul Natsuo and Burandt, Thorsten
+    and Fricko, Oliver and Byers, Edward and Kikstra, Jarmo and Brinkerink, Maarten and
+    Budzinski, Maik and Maczek, Florian and Zwickl-Bernhard, Sebastian and Welder, Lara
+    and Álvarez Quispe, Erik Francisco and Smith, Christopher J.},
+  journal = {Open Research Europe},
+  doi = {10.12688/openreseurope.13633.1},
+  title = {{pyam: Analysis and visualisation of integrated assessment and macro-energy scenarios}},
+  year = 2021,
+}
 @article{Gidden:2019:pyam,
   author = {Gidden, Matthew and Huppmann, Daniel},
   title = {{pyam: a Python package for the analysis and visualization of models
-  of the interaction of climate, human, and environmental Systems}},
+  of the interaction of climate, human, and environmental systems}},
   journal = {Journal of Open Source Software (JOSS)},
   volume = {4},
   number = {33},
@@ -28,11 +39,10 @@ @Misc{numpy
   howpublished = {USA: Trelgol Publishing},
   url = "http://www.numpy.org/",
 }
-
 @Article{matplotlib,
-  Author    = {Hunter, J. D.},
+  Author    = {Hunter, John D.},
   Title     = {Matplotlib: A 2D graphics environment},
-  Journal   = {Computing In Science \& Engineering},
+  Journal   = {Computing in Science \& Engineering},
   Volume    = {9},
   Number    = {3},
   Pages     = {90-95},
@@ -45,6 +55,6 @@ @InProceedings{pandas
   title     = {Data Structures for Statistical Computing in Python},
   booktitle = {Proceedings of the 9th Python in Science Conference},
   pages     = {51-56},
-  year      = 20102,
+  year      = 2012,
   editor    = {Stefan van der Walt and Jarrod Millman},
-}
+}

doc/source/index.rst

@@ -7,7 +7,7 @@ Release v\ |version|.
 
 |black| |python| |pytest| |rtd| |codecov|
 
-|doi| |joss| |groupsio| |slack|
+|doi| |ore| |joss| |groupsio| |slack|
 
 .. |license| image:: https://img.shields.io/badge/License-Apache%202.0-black
    :target: https://github.com/IAMconsortium/pyam/blob/main/LICENSE
@@ -40,19 +40,22 @@ Release v\ |version|.
 .. |doi| image:: https://zenodo.org/badge/113359260.svg
    :target: https://zenodo.org/badge/latestdoi/113359260
 
+.. |ore| image:: https://img.shields.io/badge/ORE-10.12688/openreseurope.13633.1-blue
+   :target: https://doi.org/10.12688/openreseurope.13633.1
+
 .. |joss| image:: https://joss.theoj.org/papers/10.21105/joss.01095/status.svg
    :target: https://joss.theoj.org/papers/10.21105/joss.01095
 
-.. |groupsio| image:: https://img.shields.io/badge/groups.io-pyam-blue
+.. |groupsio| image:: https://img.shields.io/badge/listserv-groups.io-blue
    :target: https://pyam.groups.io/g/forum
 
-.. |slack| image:: https://img.shields.io/badge/slack-@pyam-orange.svg?logo=slack
+.. |slack| image:: https://img.shields.io/badge/chat-Slack-orange.svg
    :target: https://pyam-iamc.slack.com
 
 Overview
 --------
 
-The open-source Python package |pyam| :cite:`Gidden:2019:pyam`
+The open-source Python package |pyam| :cite:`Gidden:2019:pyam,Huppmann:2021:pyam-v1.0`
 provides a suite of tools and functions for analyzing and visualizing
 input data (i.e., assumptions/parametrization) 
 and results (model output) of integrated-assessment models,
@@ -121,6 +124,40 @@ Table of Contents
 
    references
 
+Scientific publications
+-----------------------
+
+The following manuscripts describe the package at specific stages of development.
+
+Release v1.0 (June 2021)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Published to mark the first major release of the |pyam| package.
+
+.. highlights::
+
+  | Daniel Huppmann, Matthew Gidden, Zebedee Nicholls, Jonas Hörsch, Robin Lamboll,
+    Paul Natsuo Kishimoto, Thorsten Burandt, Oliver Fricko, Edward Byers, Jarmo Kikstra,
+    Maarten Brinkerink, Maik Budzinski, Florian Maczek, Sebastian Zwickl-Bernhard,
+    Lara Welder, Erik Francisco Álvarez Quispe, and Christopher J. Smith.
+  | *pyam: Analysis and visualisation of integrated assessment and macro-energy scenarios.*
+  | **Open Research Europe**, 2021.
+    doi: `10.12688/openreseurope.13633.1 <https://doi.org/10.12688/openreseurope.13633.1>`_
+
+Release v0.1.2 (November 2018)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Published following the successful application of **pyam**
+in the IPCC SR15 and the Horizon 2020 CRESCENDO project.
+
+.. highlights::
+
+  | Matthew Gidden and Daniel Huppmann.
+    *pyam: a Python package for the analysis and visualization of models
+    of the interaction of climate, human, and environmental systems.*
+  | **Journal of Open Source Software (JOSS)**, 4(33):1095, 2019.
+    doi: `10.21105/joss.01095 <https://doi.org/10.21105/joss.01095>`_
+
 Copyright & License
 -------------------
 

doc/source/tutorials/ipcc_colors.ipynb

@@ -61,7 +61,7 @@
     "    .filter(variable='Emissions|CO2', region='World', scenario=scenarios)\n",
     ")\n",
     "\n",
-    "df.line_plot(color='scenario')"
+    "df.plot(color='scenario')"
    ]
   },
   {
@@ -119,7 +119,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df.line_plot(color='scenario')"
+    "df.plot(color='scenario')"
    ]
   }
  ],
@@ -139,7 +139,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.8.3"
   }
  },
  "nbformat": 4,

doc/source/tutorials/pyam_first_steps.ipynb

@@ -139,7 +139,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In the following cells, we display the lists of all models, scenarios, regions, and the variables (including units) in the snapshot."
+    "In the following cells, we display the lists of all models, scenarios, regions, and the mapping of variables to  units in the snapshot."
    ]
   },
   {
@@ -175,7 +175,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df.variables(include_units=True)"
+    "df.unit_mapping"
    ]
   },
   {
@@ -660,7 +660,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df.variables(include_units=True)"
+    "df.variable"
    ]
   },
   {

manuscripts/ORE/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+# This file was generated with sphinx-quickstart version 3.5.0
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

manuscripts/ORE/make.bat

@@ -0,0 +1,37 @@
+REM This file was generated with sphinx-quickstart version 3.5.0
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd