Merge pull request #26 from iiasa/minor-update-docs

Update documentation for citations and input file formats

CITATION.cff

@@ -37,6 +37,6 @@ identifiers:
   - description: The concept DOI of the work.
     type: doi
     value: 10.5281/zenodo.6624519    
-  - description: The versioned DOI for version 0.1.0 of the work.
+  - description: The versioned DOI for version 0.1.1 of the work.
     type: doi
-    value: 10.5281/zenodo.6624520
+    value: 10.5281/zenodo.6782457

doc/NOTICE.rst

@@ -23,16 +23,17 @@ Read and understand the file ``LICENSE``; in particular, clause 7 (“Disclaimer
 2. Cite the scientific publication
 ==================================
 
-Cite, at minimum, the following manuscript (exact citation TBD.):
+Cite, at minimum, the following manuscript:
 
   | Jarmo S. Kikstra, Zebedee R. J. Nicholls, Christopher J. Smith, Jared Lewis, Robin D. Lamboll, Edward Byers, Marit Sandstad, Malte Meinshausen, Matthew J. Gidden, Joeri Rogelj, Elmar Kriegler, Glen P. Peters, Jan S. Fuglestvedt, Ragnhild B. Skeie, Bjørn H. Samset, Laura Wienpahl, Detlef P. van Vuuren, Kaj-Ivar van der Wijst, Alaa Al Khourdajie, Piers M. Forster, Andy Reisinger, Roberto Schaeffer, and Keywan Riahi
   | "The IPCC Sixth Assessment Report WGIII climate assessment of mitigation pathways: from emissions to global temperatures".
-  | *Geosci. Model Dev.*
-  | (in review)
+  | *Geosci. Model Dev., 15, 9075–9109*
+  | https://doi.org/10.5194/gmd-15-9075-2022
+  | 2022
 
 Additionally, you may cite the source code using the Zenodo reference (DOI: https://doi.org/10.5281/zenodo.6624519).
 
-If you are using the AR6 scenario data (DOI: https://doi.org/10.5281/zenodo.6390767) and the AR6 infiller database (DOI: https://doi.org/10.5281/zenodo.6390767), you should in addition cite those respective sources.
+If you are using the AR6 scenario data (DOI: https://doi.org/10.5281/zenodo.5886911) and the AR6 infiller database (DOI: https://doi.org/10.5281/zenodo.6390767), you should in addition cite those respective sources.
 
 In addition, to provide credit to the climate emulator modelers, please cite literature describing the climate emulator(s) that you use.
 
@@ -41,6 +42,7 @@ Lastly, you may cite the tools that enabled the development of this climate asse
 All these citations are also provided in full in the manuscript mentioned above, if further guidance is required on how to cite specific tools and data.
 
 - **Cite the code via Zenodo**.
-  The `DOI 10.5281/zenodo.6624520 <https://doi.org/10.5281/zenodo.6624519>`_ represents *all* versions of the :mod:`climate-assessment` code, and will always resolve to the latest version.
+  The `DOI 10.5281/zenodo.6624519 <https://doi.org/10.5281/zenodo.6624519>`_ represents *all* versions of the :mod:`climate-assessment` code, and will always resolve to the latest version.
   Zenodo also provides citation export in BibTeX and other formats.
+  If you would like to cite a specific release version, that is possible too and requires using the dedicate URLs, such as `DOI 10.5281/zenodo.6782457 <https://doi.org/10.5281/zenodo.6782457>` for version v0.1.1.
 - Include a link, e.g. in a footnote, to the online documentation at https://climate-assessment.readthedocs.io.

doc/emulator.rst

@@ -168,7 +168,13 @@ Emulator-specific functions
 
 References
 ----------
-Please refer to the following for more detailed use: Nicholls, Z. R. J., Meinshausen, M., Lewis, J., Smith, C. J., Forster, P. M., Fuglestvedt, J. S., Rogelj, J., Kikstra, J. S., Riahi, K., and Byers, E.: Changes in IPCC scenario assessment emulators between SR1.5 and AR6 unravelled (*forthcoming*).
+Please refer to the following for more detailed use:
+
+  | Nicholls, Z. R. J., Meinshausen, M., Lewis, J., Smith, C. J., Forster, P. M., Fuglestvedt, J. S., Rogelj, J., Kikstra, J. S., Riahi, K., and Byers, E.
+  | "Changes in IPCC Scenario Assessment Emulators Between SR1.5 and AR6 Unraveled".
+  | *Geophysical Research Letters*
+  | https://doi.org/10.1029/2022GL099788
+  | 2022
 
 * More information, multiple references, and an interactive online tool: `magicc.org <https://magicc.org/>`_
 

doc/general.rst

@@ -3,12 +3,13 @@
 Description of the workflow
 ***************************
 On this page, you will find a short summary of the main function of this package.
-The workflow is described in detail in the following manuscript (exact citation TBD.):
+The workflow is described in detail in the following manuscript:
 
   | Jarmo S. Kikstra, Zebedee R. J. Nicholls, Christopher J. Smith, Jared Lewis, Robin D. Lamboll, Edward Byers, Marit Sandstad, Malte Meinshausen, Matthew J. Gidden, Joeri Rogelj, Elmar Kriegler, Glen P. Peters, Jan S. Fuglestvedt, Ragnhild B. Skeie, Bjørn H. Samset, Laura Wienpahl, Detlef P. van Vuuren, Kaj-Ivar van der Wijst, Alaa Al Khourdajie, Piers M. Forster, Andy Reisinger, Roberto Schaeffer, and Keywan Riahi
   | "The IPCC Sixth Assessment Report WGIII climate assessment of mitigation pathways: from emissions to global temperatures".
-  | *Geosci. Model Dev.*
-  | (in review)
+  | *Geosci. Model Dev., 15, 9075–9109*
+  | https://doi.org/10.5194/gmd-15-9075-2022
+  | 2022
 
 Integrated assessment models (IAMs) produce emissions pathways as part of larger pathway output coming from the modelling of scenarios.
 These emissions pathways imply a certain temperature development.
@@ -46,7 +47,8 @@ also analyzed in the Reduced Complexity Model Intercomparison Project (RCMIP) Ph
 Expected Input (Step 1)
 =======================
 
-The expected input is in the following format, as either an Excel or CSV file, covering 2015, and then at minimum decadal (up to yearly detail is accepted) timesteps from 2020 to 2100.
+The expected input is in the following format, as either an Excel (.xlsx) or CSV (.csv) file, covering 2015, and then at minimum decadal (up to yearly detail is accepted) timesteps from 2020 to 2100.
+Currently, no meta data from the input data is used or preserved in the workflow.
 At minimum, one needs to report `Emissions|CO2|Energy and Industrial Processes`.
 Emissions baskets or species not in the table below are not considered for the eventual climate assessment, but are automatically infilled.
 In this version, negative values are only allowed as input for CO2.

doc/index.rst

@@ -103,17 +103,17 @@ Acknowledgements
 
 Per good scientific practice, you **must** cite the following publication when you use this package in scientific work.
 
-  | Jarmo S. Kikstra, Zebedee R. J. Nicholls, Christopher J. Smith, Jared Lewis, Robin D. Lamboll, Edward Byers, Marit Sanstad, Malte Meinshausen, Matthew J. Gidden, Joeri Rogelj, Elmar Kriegler, Glen P. Peters, Jan S. Fuglestvedt, Ragnhild B. Skeie, Bjørn H. Samset, Laura Wienpahl, Detlef P. van Vuuren, Kaj-Ivar van der Wijst, Alaa Al Khourdajie, Piers M. Forster, Andy Reisinger, Roberto Schaeffer, and Keywan Riahi
+  | Jarmo S. Kikstra, Zebedee R. J. Nicholls, Christopher J. Smith, Jared Lewis, Robin D. Lamboll, Edward Byers, Marit Sandstad, Malte Meinshausen, Matthew J. Gidden, Joeri Rogelj, Elmar Kriegler, Glen P. Peters, Jan S. Fuglestvedt, Ragnhild B. Skeie, Bjørn H. Samset, Laura Wienpahl, Detlef P. van Vuuren, Kaj-Ivar van der Wijst, Alaa Al Khourdajie, Piers M. Forster, Andy Reisinger, Roberto Schaeffer, and Keywan Riahi
   | "The IPCC Sixth Assessment Report WGIII climate assessment of mitigation pathways: from emissions to global temperatures".
-  | *Geosci. Model Dev.*
-  | (in review)
-
+  | *Geosci. Model Dev., 15, 9075–9109*
+  | https://doi.org/10.5194/gmd-15-9075-2022
+  | 2022
 
 You may additionally also cite the package itself:
 
   | Kikstra, J. S., Nicholls, Z. R. J., Lewis, J., Smith, C. J., Lamboll, R. D., Byers, E., Sandstad, M., Wienpahl, L., and Hackstock, P.:
-  | Climate assessment of long-term emissions pathways: IPCC AR6 WGIII version: Release v0.1.0,
-  | Zenodo, https://doi.org/10.5281/zenodo.6624520, 2022.
+  | Climate assessment of long-term emissions pathways: IPCC AR6 WGIII version,
+  | Zenodo, 10.5281/zenodo.6624519, 2022.
 
 
 For more detail, see :doc:`NOTICE`.

setup.cfg

@@ -10,8 +10,7 @@ long_description = file:README.rst
 url = https://github.com/iiasa/climate-assessment
 project_urls =
     Source = http://github.com/iiasa/climate-assessment
-    # ToDo: Change documentation URL before publishing
-    Documentation = https://iiasa-energy-program-climate-assessment.readthedocs-hosted.com/en/latest/
+    Documentation = https://climate-assessment.readthedocs.io/
     Bug_Reports = https://github.com/iiasa/climate-assessment/issues
 classifiers =
     Development Status :: 3 - Alpha