Paper (#139)

* initial commit for paper

* rm tabs

* Add scatter plot example

* better figure captions

* Editorial suggestions for paper draft (#143)

* rewrite first paragraph and remove reference to AR5

* rename bib tag

* add reference to IPCC notebooks

* minor editorial changes

* harmonize naming convention for IPCC SR15 and IAMC 1.5°C Scenario Data

* add crescendo acknowledgement

paper/paper.bib

@@ -0,0 +1,74 @@
+
+@article{rogelj_paris_2016,
+	title = {Paris {Agreement} climate proposals need a boost to keep warming well below 2 °{C}},
+	volume = {534},
+	copyright = {2016 Nature Publishing Group},
+	issn = {1476-4687},
+	url = {https://www.nature.com/articles/nature18307},
+	doi = {10.1038/nature18307},
+	abstract = {The Paris climate agreement aims at holding global warming to well below 2 degrees Celsius and to “pursue efforts” to limit it to 1.5 degrees Celsius. To accomplish this, countries have submitted Intended Nationally Determined Contributions (INDCs) outlining their post-2020 climate action. Here we assess the effect of current INDCs on reducing aggregate greenhouse gas emissions, its implications for achieving the temperature objective of the Paris climate agreement, and potential options for overachievement. The INDCs collectively lower greenhouse gas emissions compared to where current policies stand, but still imply a median warming of 2.6–3.1 degrees Celsius by 2100. More can be achieved, because the agreement stipulates that targets for reducing greenhouse gas emissions are strengthened over time, both in ambition and scope. Substantial enhancement or over-delivery on current INDCs by additional national, sub-national and non-state actions is required to maintain a reasonable chance of meeting the target of keeping warming well below 2 degrees Celsius.},
+	language = {en},
+	number = {7609},
+	urldate = {2018-11-19},
+	journal = {Nature},
+	author = {Rogelj, Joeri and den Elzen, Michel and Höhne, Niklas and Fransen, Taryn and Fekete, Hanna and Winkler, Harald and Schaeffer, Roberto and Sha, Fu and Riahi, Keywan and Meinshausen, Malte},
+	month = jun,
+	year = {2016},
+	pages = {631--639}
+}	
+
+@article{gidden_global_2018,
+	title = {Global emissions pathways under different socioeconomic scenarios for use in {CMIP}6: a dataset of harmonized emissions trajectories through the end of the century},
+	volume = {2018},
+	url = {https://www.geosci-model-dev-discuss.net/gmd-2018-266/},
+	doi = {10.5194/gmd-2018-266},
+	journal = {Geoscientific Model Development Discussions},
+	author = {Gidden, M. J. and Riahi, K. and Smith, S. J. and Fujimori, S. and Luderer, G. and Kriegler, E. and van Vuuren, D. P. and van den Berg, M. and Feng, L. and Klein, D. and Calvin, K. and Doelman, J. C. and Frank, S. and Fricko, O. and Harmsen, M. and Hasegawa, T. and Havlik, P. and Hilaire, J. and Hoesly, R. and Horing, J. and Popp, A. and Stehfest, E. and Takahashi, K.},
+	year = {2018},
+	pages = {1--42}
+}
+
+@article{oneill_scenario_2016,
+	title = {The {Scenario} {Model} {Intercomparison} {Project} ({ScenarioMIP}) for {CMIP}6},
+	volume = {9},
+	issn = {1991-9603},
+	url = {https://www.geosci-model-dev.net/9/3461/2016/},
+	doi = {10.5194/gmd-9-3461-2016},
+	abstract = {Projections of future climate change play a fundamental role in improving understanding of the climate system as well as characterizing societal risks and response options. The Scenario Model Intercomparison Project (ScenarioMIP) is the primary activity within Phase 6 of the Coupled Model Intercomparison Project (CMIP6) that will provide multi-model climate projections based on alternative scenarios of future emissions and land use changes produced with integrated assessment models. In this paper, we describe ScenarioMIP's objectives, experimental design, and its relation to other activities within CMIP6. The ScenarioMIP design is one component of a larger scenario process that aims to facilitate a wide range of integrated studies across the climate science, integrated assessment modeling, and impacts, adaptation, and vulnerability communities, and will form an important part of the evidence base in the forthcoming Intergovernmental Panel on Climate Change (IPCC) assessments. At the same time, it will provide the basis for investigating a number of targeted science and policy questions that are especially relevant to scenario-based analysis, including the role of specific forcings such as land use and aerosols, the effect of a peak and decline in forcing, the consequences of scenarios that limit warming to below 2 °C, the relative contributions to uncertainty from scenarios, climate models, and internal variability, and long-term climate system outcomes beyond the 21st century. To serve this wide range of scientific communities and address these questions, a design has been identified consisting of eight alternative 21st century scenarios plus one large initial condition ensemble and a set of long-term extensions, divided into two tiers defined by relative priority. Some of these scenarios will also provide a basis for variants planned to be run in other CMIP6-Endorsed MIPs to investigate questions related to specific forcings. Harmonized, spatially explicit emissions and land use scenarios generated with integrated assessment models will be provided to participating climate modeling groups by late 2016, with the climate model simulations run within the 2017–2018 time frame, and output from the climate model projections made available and analyses performed over the 2018–2020 period.},
+	number = {9},
+	urldate = {2018-04-26},
+	journal = {Geosci. Model Dev.},
+	author = {O'Neill, B. C. and Tebaldi, C. and van Vuuren, D. P. and Eyring, V. and Friedlingstein, P. and Hurtt, G. and Knutti, R. and Kriegler, E. and Lamarque, J.-F. and Lowe, J. and Meehl, G. A. and Moss, R. and Riahi, K. and Sanderson, B. M.},
+	month = sep,
+	year = {2016},
+	pages = {3461--3482}
+}
+
+@article{huppmann_ncc_2018,
+	title = {A new scenario resource for integrated 1.5 °{C} research},
+	issn = {1758-6798},
+	url = {https://doi.org/10.1038/s41558-018-0317-4},
+	doi = {10.1038/s41558-018-0317-4},
+	abstract = {Scenarios have supported assessments of the IPCC for decades. A new scenario ensemble and a suite of visualization and analysis tools is now made available alongside the IPCC 1.5 °C Special Report to improve transparency and re-use of scenario data across research communities.},
+	journal = {Nature Climate Change},
+	author = {Huppmann, Daniel and Rogelj, Joeri and Kriegler, Elmar and Krey, Volker and Riahi, Keywan},
+	month = oct,
+	year = {2018}
+}
+
+@article{pyam_2018,
+         title={pyam: analysis and visualization of assessment models},
+	 DOI={10.5281/zenodo.1491662},
+	 publisher={Zenodo},
+	 author={Matthew J. Gidden and Daniel Huppmann},
+	 year={2018},
+	 month={Oct}
+}
+
+@misc{huppmann_notebooks_2018,
+     author = {Huppmann, Daniel and Rogelj, Joeri and Kriegler, Elmar and Mundaca, Luis and Forster, Piers and Kobayashi, Shigeki and Séferian, Roland and Vilariño, María Virginia},
+     title = {{Scenario analysis notebooks for the IPCC Special Report on Global Warming of 1.5°C}},
+	 DOI={10.5281/zenodo.1470489},
+	 publisher={Zenodo},
+     year = {2018}
+}

paper/paper.md

@@ -0,0 +1,149 @@
+---
+title: 'pyam: a Python Package for the Analysis and Visualization of Assessment Models'
+authors:
+    - name: Matthew J. Gidden
+            orcid: 0000-0003-0687-414X
+            affiliation: 1
+    - name: Daniel Huppmann
+            orcid: 0000-0002-7729-7389
+            affiliation: 1
+date: 20 November 2018
+output: pdf_document
+bibliography: paper.bib
+tags:
+    - Python
+    - Visualization
+    - Integrated Assessment Models
+    - Simple Climate Models
+    - Climate Change
+    - Greenhouse Gases
+affiliations:
+    - name: International Institute for Applied Systems Analysis, Schlossplatz 1, A-2361 Laxenburg, Austria
+            index: 1
+---
+
+# Summary
+
+Quantitative model-based scenarios of the human and earth systems
+play a critical role in the scientific analysis of climate change mitigation
+options and sustainable development policies.
+Perhaps the most visible among these projects is the assessment of pathways
+from Integrated Assessment Models (IAM) and other numerical frameworks by
+the Intergovernmental Panel on Climate Change (IPCC) in its periodical reports.
+For the recent *Special Report on Global Warming of 1.5 °C*
+[(SR15)](http://www.ipcc.ch/report/sr15/),
+a scenario ensemble underpinning the quantitative assessment was compiled
+and released to facilitate transparency of the assessment and replicability
+of the findings in the report [@huppmann_ncc_2018].
+
+Additionally, IAM scenarios serve as one of the main
+drivers of the Coupled Model Intercomparison Project Phase 6
+[(CMIP6)](https://www.wcrp-climate.org/wgcm-cmip/wgcm-cmip6)
+[@oneill_scenario_2016; @gidden_global_2018], which informs the global
+scientific basis for climate change. IAMs are not only limited to global
+analyses, but also are critical for country-specific policy assessments both
+domestically as well as in the global context [@rogelj_paris_2016]. While great
+strides have been made to make IAM scenario data publicly available among these
+different projects, limited effort has been applied so far
+to develop open tools for their exploration, analysis, and visualization.
+
+Here we present a new tool which aims to fill the current gaps in the IAM
+toolbox: an open-source analysis and visualization library named __pyam__
+[@pyam_2018]. __pyam__ has been designed since its inception following known
+best practices in scientific software development, including automatic
+documentation, unit testing, and continuous integration. At its core, __pyam__
+is a tool that enables researchers to easily explore, categorize, and
+visualize scenario data such as the scenario ensembles assessed by the IPCC.
+Such exploration is enabled via a __pandas.DataFrame__-style interface using a
+composition design pattern while maintaining sidecar metadata in a single
+__pyam.IamDataFrame__ object. 
+
+Critically, __pyam__ provides a common mechanism by which scenario data analysis
+is performed. This allows to easily share such analysis for greater transparency
+and reproducibility, through, e.g., Jupyter notebooks. In fact, it is already an
+integral tool used by scientists leading the data analysis of both the IPCC
+SR15 as well as the ScenarioMIP contribution to CMIP6. The Jupyter notebooks
+generating the categorization and assessment in the SR15, including figures and
+tables printed in the report, are based on __pyam__ and have been publicly
+released under an open-source license [@huppmann_notebooks_2018].
+
+A large suite of examples is available via the __pyam__
+[website](https://data.ene.iiasa.ac.at/software/pyam/). Here, we provide a small
+vignette below for interacting with and visualizing the recent SR15 dataset.
+
+
+```python
+import pyam
+
+# read all data for three variables at the global ('World') level
+# from the *IAMC 1.5 °C Scenario Data*, the database underpinning the IPCC SR15
+df = pyam.read_iiasa_iamc15(
+    model='*', scenario='*',
+    variable=['Emissions|CO2', 'Primary Energy|Coal', 
+              'AR5 climate diagnostics|Temperature|Global Mean|MAGICC6|MED'], 
+    region='World'
+)
+
+# Categorize these data by their Global Mean Temperature values in 2100
+df.categorize(
+    'Temperature', 'Below 1.5C',
+    criteria={'AR5 climate diagnostics|Temperature|Global Mean|MAGICC6|MED': 
+             {'up': 1.5, 'year': 2100}},
+    color='cornflowerblue'
+)
+
+df.categorize(
+    'Temperature', 'Below 2C',
+    criteria={'AR5 climate diagnostics|Temperature|Global Mean|MAGICC6|MED': 
+             {'lo': 1.5, 'up': 2, 'year': 2100}},
+    color='forestgreen'
+)
+
+df.categorize(
+    'Temperature', 'Above 2C',
+    criteria={'AR5 climate diagnostics|Temperature|Global Mean|MAGICC6|MED': 
+             {'lo': 2, 'year': 2100}},
+    color='magenta'
+)
+
+# Temperature data can be plotted directly based on these categories,
+# shading areas between lowest and highest values for each category,
+# and providing minimum/maximum ranges of final-year data
+(df
+ .filter(variable='*Temperature*')
+ .line_plot(color='Temperature', legend=True, 
+            alpha=0.5, fill_between=True, 
+            final_ranges=dict(linewidth=4))
+)
+
+# Separately, the other data can be plotted using the temperatue categories.
+(df
+ .filter(region='World')
+ .scatter(x='Primary Energy|Coal', y='Emissions|CO2', 
+          color='Temperature', alpha=0.5, legend=True)
+)
+```
+
+Executing the above code snippet results in the following figures. 
+
+![A classic AR5-style line plot, showing various temperature categories, their scenario ranges, and end-of-century outcome ranges.](line.png)
+
+![A scatter plot showing scenario values of primary energy from coal vs. CO2 emissions colored based on end-of-centure temperate outcomes](scatter.png).
+
+The __pyam__ user community already spans three continents and multiple
+scientific domains. New features, e.g., integration with simple climate models,
+are envisioned for future releases in order to further expand the usability and
+relevance of the tool. By standardizing analysis and visualization work flows in
+assessment modeling, modelers can more keenly focus on their core competency:
+developing and performing large-scale models of the interlinked human,
+environment, and climate systems.
+
+# Acknowledgments
+
+This project has received funding from the European Union’s Horizon 2020
+research and innovation programme under grant agreement No 641816 (CRESCENDO)
+for visualization development. We acknowledge further funding by the European
+Union’s Horizon 2020 research and innovation programme under grant agreement
+no. 642147 (‘CD-LINKS’ project) supporting aspects of IPCC analysis.
+
+# References