diff --git a/.gitignore b/.gitignore index fb3ca36b8..0d2e4c44b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ *csv *xlsx *png +*jpg *pdf # Apple file system diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8f458516b..cbf785a85 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -12,8 +12,8 @@ Have a question? Get in touch! .. _Slack: https://slack.com -Interested in Contributing? Welcome to the team! ------------------------------------------------- +Interested in contributing? Join to the team! +--------------------------------------------- The pyam package has been developed with the explicit aim to facilitate open and collaborative analysis of integrated assessment and climate models. diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 934c2f5a1..4667e68ad 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,6 +1,7 @@ # Next Release +- [#277](https://github.com/IAMconsortium/pyam/pull/277) Restructure and extend the docs pages, switch to RTD-supported theme - [#275](https://github.com/IAMconsortium/pyam/pull/275) Completely removes all features related to region plotting, notably `region_plot()` and `read_shapefile()` - [#270](https://github.com/IAMconsortium/pyam/pull/270) Include variables with zeros in `stack_plot` (see [#266](https://github.com/IAMconsortium/pyam/issues/266)) - [#269](https://github.com/IAMconsortium/pyam/pull/269) Ensure append doesn't accidentally swap indexes diff --git a/doc/environment.yml b/doc/environment.yml index 84c31bb91..96d9df1c5 100644 --- a/doc/environment.yml +++ b/doc/environment.yml @@ -15,5 +15,5 @@ dependencies: - pillow==5.4.1 - sphinxcontrib-bibtex - sphinxcontrib-programoutput + - sphinxcontrib-fulltoc - nbsphinx - \ No newline at end of file diff --git a/doc/source/_bib/data.bib b/doc/source/_bib/data.bib new file mode 100644 index 000000000..057a14dc7 --- /dev/null +++ b/doc/source/_bib/data.bib @@ -0,0 +1,12 @@ +@misc{Huppmann:2019:scenario-data, + author = {Huppmann, Daniel and Kriegler, Elmar and Krey, Volker and + Riahi, Keywan and Rogelj, Joeri and Calvin, Katherine and + Humpenoeder, Florian and Popp, Alexander and Rose, Steven K. and + Weyant, John and et al.}, + doi = {10.5281/zenodo.3363345}, + howpublished = {Integrated Assessment Modeling Consortium & International Institute for Applied Systems Analysis}, + publisher = {Integrated Assessment Modeling Consortium & International Institute for Applied Systems Analysis}, + title = {{IAMC 1.5 °C Scenario Explorer and Data hosted by IIASA (release 2.0)}}, + url = {https://data.ene.iiasa.ac.at/iamc-1.5c-explorer}, + year = {2019} +} diff --git a/doc/source/_bib/index.bib b/doc/source/_bib/index.bib new file mode 100644 index 000000000..0c217cd7e --- /dev/null +++ b/doc/source/_bib/index.bib @@ -0,0 +1,11 @@ +@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}}, + journal = {Journal of Open Source Software (JOSS)}, + volume = {4}, + number = {33}, + pages = {1095}, + year = {2019}, + doi = {10.21105/joss.01095}, +} diff --git a/doc/source/refs.bib b/doc/source/_bib/install.bib similarity index 99% rename from doc/source/refs.bib rename to doc/source/_bib/install.bib index 948b7b33b..b8fe07bf4 100644 --- a/doc/source/refs.bib +++ b/doc/source/_bib/install.bib @@ -1,4 +1,3 @@ - @Misc{numpy, author = {Travis Oliphant}, title = {{NumPy}: A guide to {NumPy}}, diff --git a/doc/source/_static/iamc_logo.jpg b/doc/source/_static/iamc_logo.jpg new file mode 100644 index 000000000..87ff43399 Binary files /dev/null and b/doc/source/_static/iamc_logo.jpg differ diff --git a/doc/source/_static/iamc_template.png b/doc/source/_static/iamc_template.png new file mode 100644 index 000000000..f22772845 Binary files /dev/null and b/doc/source/_static/iamc_template.png differ diff --git a/doc/source/_themes/LICENSE b/doc/source/_themes/LICENSE deleted file mode 100644 index 81f4d3059..000000000 --- a/doc/source/_themes/LICENSE +++ /dev/null @@ -1,45 +0,0 @@ -Modifications: - -Copyright (c) 2010 Kenneth Reitz. - - -Original Project: - -Copyright (c) 2010 by Armin Ronacher. - - -Some rights reserved. - -Redistribution and use in source and binary forms of the theme, with or -without modification, are permitted provided that the following conditions -are met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - -* The names of the contributors may not be used to endorse or - promote products derived from this software without specific - prior written permission. - -We kindly ask you to only use these themes in an unmodified manner just -for Flask and Flask-related products, not for unrelated projects. If you -like the visual style and want to use it for your own projects, please -consider making some larger changes to the themes (such as changing -font faces, sizes, colors or margins). - -THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. diff --git a/doc/source/_themes/README.rst b/doc/source/_themes/README.rst deleted file mode 100644 index e8179f969..000000000 --- a/doc/source/_themes/README.rst +++ /dev/null @@ -1,25 +0,0 @@ -krTheme Sphinx Style -==================== - -This repository contains sphinx styles Kenneth Reitz uses in most of -his projects. It is a drivative of Mitsuhiko's themes for Flask and Flask related -projects. To use this style in your Sphinx documentation, follow -this guide: - -1. put this folder as _themes into your docs folder. Alternatively - you can also use git submodules to check out the contents there. - -2. add this to your conf.py: :: - - sys.path.append(os.path.abspath('_themes')) - html_theme_path = ['_themes'] - html_theme = 'kr' - -The following themes exist: - -**kr** - the standard flask documentation theme for large projects - -**kr_small** - small one-page theme. Intended to be used by very small addon libraries. - diff --git a/doc/source/_themes/flask_theme_support.py b/doc/source/_themes/flask_theme_support.py deleted file mode 100644 index 33f47449c..000000000 --- a/doc/source/_themes/flask_theme_support.py +++ /dev/null @@ -1,86 +0,0 @@ -# flasky extensions. flasky pygments style based on tango style -from pygments.style import Style -from pygments.token import Keyword, Name, Comment, String, Error, \ - Number, Operator, Generic, Whitespace, Punctuation, Other, Literal - - -class FlaskyStyle(Style): - background_color = "#f8f8f8" - default_style = "" - - styles = { - # No corresponding class for the following: - #Text: "", # class: '' - Whitespace: "underline #f8f8f8", # class: 'w' - Error: "#a40000 border:#ef2929", # class: 'err' - Other: "#000000", # class 'x' - - Comment: "italic #8f5902", # class: 'c' - Comment.Preproc: "noitalic", # class: 'cp' - - Keyword: "bold #004461", # class: 'k' - Keyword.Constant: "bold #004461", # class: 'kc' - Keyword.Declaration: "bold #004461", # class: 'kd' - Keyword.Namespace: "bold #004461", # class: 'kn' - Keyword.Pseudo: "bold #004461", # class: 'kp' - Keyword.Reserved: "bold #004461", # class: 'kr' - Keyword.Type: "bold #004461", # class: 'kt' - - Operator: "#582800", # class: 'o' - Operator.Word: "bold #004461", # class: 'ow' - like keywords - - Punctuation: "bold #000000", # class: 'p' - - # because special names such as Name.Class, Name.Function, etc. - # are not recognized as such later in the parsing, we choose them - # to look the same as ordinary variables. - Name: "#000000", # class: 'n' - Name.Attribute: "#c4a000", # class: 'na' - to be revised - Name.Builtin: "#004461", # class: 'nb' - Name.Builtin.Pseudo: "#3465a4", # class: 'bp' - Name.Class: "#000000", # class: 'nc' - to be revised - Name.Constant: "#000000", # class: 'no' - to be revised - Name.Decorator: "#888", # class: 'nd' - to be revised - Name.Entity: "#ce5c00", # class: 'ni' - Name.Exception: "bold #cc0000", # class: 'ne' - Name.Function: "#000000", # class: 'nf' - Name.Property: "#000000", # class: 'py' - Name.Label: "#f57900", # class: 'nl' - Name.Namespace: "#000000", # class: 'nn' - to be revised - Name.Other: "#000000", # class: 'nx' - Name.Tag: "bold #004461", # class: 'nt' - like a keyword - Name.Variable: "#000000", # class: 'nv' - to be revised - Name.Variable.Class: "#000000", # class: 'vc' - to be revised - Name.Variable.Global: "#000000", # class: 'vg' - to be revised - Name.Variable.Instance: "#000000", # class: 'vi' - to be revised - - Number: "#990000", # class: 'm' - - Literal: "#000000", # class: 'l' - Literal.Date: "#000000", # class: 'ld' - - String: "#4e9a06", # class: 's' - String.Backtick: "#4e9a06", # class: 'sb' - String.Char: "#4e9a06", # class: 'sc' - String.Doc: "italic #8f5902", # class: 'sd' - like a comment - String.Double: "#4e9a06", # class: 's2' - String.Escape: "#4e9a06", # class: 'se' - String.Heredoc: "#4e9a06", # class: 'sh' - String.Interpol: "#4e9a06", # class: 'si' - String.Other: "#4e9a06", # class: 'sx' - String.Regex: "#4e9a06", # class: 'sr' - String.Single: "#4e9a06", # class: 's1' - String.Symbol: "#4e9a06", # class: 'ss' - - Generic: "#000000", # class: 'g' - Generic.Deleted: "#a40000", # class: 'gd' - Generic.Emph: "italic #000000", # class: 'ge' - Generic.Error: "#ef2929", # class: 'gr' - Generic.Heading: "bold #000080", # class: 'gh' - Generic.Inserted: "#00A000", # class: 'gi' - Generic.Output: "#888", # class: 'go' - Generic.Prompt: "#745334", # class: 'gp' - Generic.Strong: "bold #000000", # class: 'gs' - Generic.Subheading: "bold #800080", # class: 'gu' - Generic.Traceback: "bold #a40000", # class: 'gt' - } diff --git a/doc/source/_themes/kr/layout.html b/doc/source/_themes/kr/layout.html deleted file mode 100644 index bf0b3c78b..000000000 --- a/doc/source/_themes/kr/layout.html +++ /dev/null @@ -1,16 +0,0 @@ -{%- extends "basic/layout.html" %} -{%- block extrahead %} - {{ super() }} - {% if theme_touch_icon %} - - {% endif %} - - -{% endblock %} -{%- block relbar2 %}{% endblock %} -{%- block footer %} -
- © Copyright {{ copyright }}. -
-{%- endblock %} diff --git a/doc/source/_themes/kr/relations.html b/doc/source/_themes/kr/relations.html deleted file mode 100644 index 3bbcde85b..000000000 --- a/doc/source/_themes/kr/relations.html +++ /dev/null @@ -1,19 +0,0 @@ -

Related Topics

- diff --git a/doc/source/_themes/kr/static/flasky.css_t b/doc/source/_themes/kr/static/flasky.css_t deleted file mode 100644 index 577431050..000000000 --- a/doc/source/_themes/kr/static/flasky.css_t +++ /dev/null @@ -1,445 +0,0 @@ -/* - * flasky.css_t - * ~~~~~~~~~~~~ - * - * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz. - * :license: Flask Design License, see LICENSE for details. - */ - -{% set page_width = '940px' %} -{% set sidebar_width = '220px' %} - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro'; - font-size: 17px; - background-color: white; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - width: {{ page_width }}; - margin: 30px auto 0 auto; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 {{ sidebar_width }}; -} - -div.sphinxsidebar { - width: {{ sidebar_width }}; -} - -hr { - border: 1px solid #B1B4B6; -} - -div.body { - background-color: #ffffff; - color: #3E4349; - padding: 0 30px 0 30px; -} - -img.floatingflask { - padding: 0 0 10px 10px; - float: right; -} - -div.footer { - width: {{ page_width }}; - margin: 20px auto 30px auto; - font-size: 14px; - color: #888; - text-align: right; -} - -div.footer a { - color: #888; -} - -div.related { - display: none; -} - -div.sphinxsidebar a { - color: #444; - text-decoration: none; - border-bottom: 1px dotted #999; -} - -div.sphinxsidebar a:hover { - border-bottom: 1px solid #999; -} - -div.sphinxsidebar { - font-size: 14px; - line-height: 1.5; -} - -div.sphinxsidebarwrapper { - padding: 18px 10px; -} - -div.sphinxsidebarwrapper p.logo { - padding: 0; - margin: -10px 0 0 -20px; - text-align: center; -} - -div.sphinxsidebar h3, -div.sphinxsidebar h4 { - font-family: 'Garamond', 'Georgia', serif; - color: #444; - font-size: 24px; - font-weight: normal; - margin: 0 0 5px 0; - padding: 0; -} - -div.sphinxsidebar h4 { - font-size: 20px; -} - -div.sphinxsidebar h3 a { - color: #444; -} - -div.sphinxsidebar p.logo a, -div.sphinxsidebar h3 a, -div.sphinxsidebar p.logo a:hover, -div.sphinxsidebar h3 a:hover { - border: none; -} - -div.sphinxsidebar p { - color: #555; - margin: 10px 0; -} - -div.sphinxsidebar ul { - margin: 10px 0; - padding: 0; - color: #000; -} - -div.sphinxsidebar input { - border: 1px solid #ccc; - font-family: 'Georgia', serif; - font-size: 1em; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #004B6B; - text-decoration: underline; -} - -a:hover { - color: #6D4100; - text-decoration: underline; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - margin: 30px 0px 10px 0px; - padding: 0; -} - -div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } -div.body h2 { font-size: 180%; } -div.body h3 { font-size: 150%; } -div.body h4 { font-size: 130%; } -div.body h5 { font-size: 100%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #ddd; - padding: 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - color: #444; - background: #eaeaea; -} - -div.body p, div.body dd, div.body li { - line-height: 1.4em; -} - -div.admonition { - background: #fafafa; - margin: 20px -30px; - padding: 10px 30px; - border-top: 1px solid #ccc; - border-bottom: 1px solid #ccc; -} - -div.admonition tt.xref, div.admonition a tt { - border-bottom: 1px solid #fafafa; -} - -dd div.admonition { - margin-left: -60px; - padding-left: 60px; -} - -div.admonition p.admonition-title { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - font-size: 24px; - margin: 0 0 10px 0; - padding: 0; - line-height: 1; -} - -div.admonition p.last { - margin-bottom: 0; -} - -div.highlight { - background-color: white; -} - -dt:target, .highlight { - background: #FAF3E8; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre, tt { - font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.9em; -} - -img.screenshot { -} - -tt.descname, tt.descclassname { - font-size: 0.95em; -} - -tt.descname { - padding-right: 0.08em; -} - -img.screenshot { - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils { - border: 1px solid #888; - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils td, table.docutils th { - border: 1px solid #888; - padding: 0.25em 0.7em; -} - -table.field-list, table.footnote { - border: none; - -moz-box-shadow: none; - -webkit-box-shadow: none; - box-shadow: none; -} - -table.footnote { - margin: 15px 0; - width: 100%; - border: 1px solid #eee; - background: #fdfdfd; - font-size: 0.9em; -} - -table.footnote + table.footnote { - margin-top: -15px; - border-top: none; -} - -table.field-list th { - padding: 0 0.8em 0 0; -} - -table.field-list td { - padding: 0; -} - -table.footnote td.label { - width: 0px; - padding: 0.3em 0 0.3em 0.5em; -} - -table.footnote td { - padding: 0.3em 0.5em; -} - -dl { - margin: 0; - padding: 0; -} - -dl dd { - margin-left: 30px; -} - -blockquote { - margin: 0 0 0 30px; - padding: 0; -} - -ul, ol { - margin: 10px 0 10px 30px; - padding: 0; -} - -pre { - background: #eee; - padding: 7px 30px; - margin: 15px -30px; - line-height: 1.3em; -} - -dl pre, blockquote pre, li pre { - margin-left: -60px; - padding-left: 60px; -} - -dl dl pre { - margin-left: -90px; - padding-left: 90px; -} - -tt { - background-color: #ecf0f3; - color: #222; - /* padding: 1px 2px; */ -} - -tt.xref, a tt { - background-color: #FBFBFB; - border-bottom: 1px solid white; -} - -a.reference { - text-decoration: none; - border-bottom: 1px dotted #004B6B; -} - -a.reference:hover { - border-bottom: 1px solid #6D4100; -} - -a.footnote-reference { - text-decoration: none; - font-size: 0.7em; - vertical-align: top; - border-bottom: 1px dotted #004B6B; -} - -a.footnote-reference:hover { - border-bottom: 1px solid #6D4100; -} - -a:hover tt { - background: #EEE; -} - - -@media screen and (max-width: 600px) { - - div.sphinxsidebar { - display: none; - } - - div.document { - width: 100%; - - } - - div.documentwrapper { - margin-left: 0; - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - } - - div.bodywrapper { - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - margin-left: 0; - } - - ul { - margin-left: 0; - } - - .document { - width: auto; - } - - .footer { - width: auto; - } - - .bodywrapper { - margin: 0; - } - - .footer { - width: auto; - } - - .github { - display: none; - } - -} - -/* misc. */ - -.revsys-inline { - display: none!important; -} \ No newline at end of file diff --git a/doc/source/_themes/kr/static/small_flask.css b/doc/source/_themes/kr/static/small_flask.css deleted file mode 100644 index 8d55e95fb..000000000 --- a/doc/source/_themes/kr/static/small_flask.css +++ /dev/null @@ -1,90 +0,0 @@ -/* - * small_flask.css_t - * ~~~~~~~~~~~~~~~~~ - * - * :copyright: Copyright 2010 by Armin Ronacher. - * :license: Flask Design License, see LICENSE for details. - */ - -body { - margin: 0; - padding: 20px 30px; -} - -div.documentwrapper { - float: none; - background: white; -} - -div.sphinxsidebar { - display: block; - float: none; - width: 102.5%; - margin: 50px -30px -20px -30px; - padding: 10px 20px; - background: #333; - color: white; -} - -div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, -div.sphinxsidebar h3 a { - color: white; -} - -div.sphinxsidebar a { - color: #aaa; -} - -div.sphinxsidebar p.logo { - display: none; -} - -div.document { - width: 100%; - margin: 0; -} - -div.related { - display: block; - margin: 0; - padding: 10px 0 20px 0; -} - -div.related ul, -div.related ul li { - margin: 0; - padding: 0; -} - -div.footer { - display: none; -} - -div.bodywrapper { - margin: 0; -} - -div.body { - min-height: 0; - padding: 0; -} - -.rtd_doc_footer { - display: none; -} - -.document { - width: auto; -} - -.footer { - width: auto; -} - -.footer { - width: auto; -} - -.github { - display: none; -} \ No newline at end of file diff --git a/doc/source/_themes/kr/theme.conf b/doc/source/_themes/kr/theme.conf deleted file mode 100644 index 307a1f0d6..000000000 --- a/doc/source/_themes/kr/theme.conf +++ /dev/null @@ -1,7 +0,0 @@ -[theme] -inherit = basic -stylesheet = flasky.css -pygments_style = flask_theme_support.FlaskyStyle - -[options] -touch_icon = diff --git a/doc/source/_themes/kr_small/layout.html b/doc/source/_themes/kr_small/layout.html deleted file mode 100644 index aa1716aaf..000000000 --- a/doc/source/_themes/kr_small/layout.html +++ /dev/null @@ -1,22 +0,0 @@ -{% extends "basic/layout.html" %} -{% block header %} - {{ super() }} - {% if pagename == 'index' %} -
- {% endif %} -{% endblock %} -{% block footer %} - {% if pagename == 'index' %} -
- {% endif %} -{% endblock %} -{# do not display relbars #} -{% block relbar1 %}{% endblock %} -{% block relbar2 %} - {% if theme_github_fork %} - Fork me on GitHub - {% endif %} -{% endblock %} -{% block sidebar1 %}{% endblock %} -{% block sidebar2 %}{% endblock %} diff --git a/doc/source/_themes/kr_small/static/flasky.css_t b/doc/source/_themes/kr_small/static/flasky.css_t deleted file mode 100644 index fe2141c56..000000000 --- a/doc/source/_themes/kr_small/static/flasky.css_t +++ /dev/null @@ -1,287 +0,0 @@ -/* - * flasky.css_t - * ~~~~~~~~~~~~ - * - * Sphinx stylesheet -- flasky theme based on nature theme. - * - * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: 'Georgia', serif; - font-size: 17px; - color: #000; - background: white; - margin: 0; - padding: 0; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 40px auto 0 auto; - width: 700px; -} - -hr { - border: 1px solid #B1B4B6; -} - -div.body { - background-color: #ffffff; - color: #3E4349; - padding: 0 30px 30px 30px; -} - -img.floatingflask { - padding: 0 0 10px 10px; - float: right; -} - -div.footer { - text-align: right; - color: #888; - padding: 10px; - font-size: 14px; - width: 650px; - margin: 0 auto 40px auto; -} - -div.footer a { - color: #888; - text-decoration: underline; -} - -div.related { - line-height: 32px; - color: #888; -} - -div.related ul { - padding: 0 0 0 10px; -} - -div.related a { - color: #444; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #004B6B; - text-decoration: underline; -} - -a:hover { - color: #6D4100; - text-decoration: underline; -} - -div.body { - padding-bottom: 40px; /* saved for footer */ -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - margin: 30px 0px 10px 0px; - padding: 0; -} - -{% if theme_index_logo %} -div.indexwrapper h1 { - text-indent: -999999px; - background: url({{ theme_index_logo }}) no-repeat center center; - height: {{ theme_index_logo_height }}; -} -{% endif %} - -div.body h2 { font-size: 180%; } -div.body h3 { font-size: 150%; } -div.body h4 { font-size: 130%; } -div.body h5 { font-size: 100%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: white; - padding: 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - color: #444; - background: #eaeaea; -} - -div.body p, div.body dd, div.body li { - line-height: 1.4em; -} - -div.admonition { - background: #fafafa; - margin: 20px -30px; - padding: 10px 30px; - border-top: 1px solid #ccc; - border-bottom: 1px solid #ccc; -} - -div.admonition p.admonition-title { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - font-size: 24px; - margin: 0 0 10px 0; - padding: 0; - line-height: 1; -} - -div.admonition p.last { - margin-bottom: 0; -} - -div.highlight{ - background-color: white; -} - -dt:target, .highlight { - background: #FAF3E8; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre, tt { - font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.85em; -} - -img.screenshot { -} - -tt.descname, tt.descclassname { - font-size: 0.95em; -} - -tt.descname { - padding-right: 0.08em; -} - -img.screenshot { - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils { - border: 1px solid #888; - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils td, table.docutils th { - border: 1px solid #888; - padding: 0.25em 0.7em; -} - -table.field-list, table.footnote { - border: none; - -moz-box-shadow: none; - -webkit-box-shadow: none; - box-shadow: none; -} - -table.footnote { - margin: 15px 0; - width: 100%; - border: 1px solid #eee; -} - -table.field-list th { - padding: 0 0.8em 0 0; -} - -table.field-list td { - padding: 0; -} - -table.footnote td { - padding: 0.5em; -} - -dl { - margin: 0; - padding: 0; -} - -dl dd { - margin-left: 30px; -} - -pre { - padding: 0; - margin: 15px -30px; - padding: 8px; - line-height: 1.3em; - padding: 7px 30px; - background: #eee; - border-radius: 2px; - -moz-border-radius: 2px; - -webkit-border-radius: 2px; -} - -dl pre { - margin-left: -60px; - padding-left: 60px; -} - -tt { - background-color: #ecf0f3; - color: #222; - /* padding: 1px 2px; */ -} - -tt.xref, a tt { - background-color: #FBFBFB; -} - -a:hover tt { - background: #EEE; -} diff --git a/doc/source/_themes/kr_small/theme.conf b/doc/source/_themes/kr_small/theme.conf deleted file mode 100644 index 542b46251..000000000 --- a/doc/source/_themes/kr_small/theme.conf +++ /dev/null @@ -1,10 +0,0 @@ -[theme] -inherit = basic -stylesheet = flasky.css -nosidebar = true -pygments_style = flask_theme_support.FlaskyStyle - -[options] -index_logo = '' -index_logo_height = 120px -github_fork = '' diff --git a/doc/source/conf.py b/doc/source/conf.py index be4aa634a..88c3ac99f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -12,9 +12,8 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys -import os -import shlex +from datetime import datetime +import pyam # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -31,6 +30,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinxcontrib.fulltoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', @@ -69,7 +69,8 @@ # General information about the project. project = u'pyam' -copyright = u'2018, Matthew Gidden & Daniel Huppmann' +year = datetime.now().year +copyright = '{}, Matthew Gidden & Daniel Huppmann'.format(year) author = u'Matthew Gidden & Daniel Huppmann' # The version info for the project you're documenting, acts as replacement for @@ -77,7 +78,6 @@ # built documents. # # The short X.Y version. -import pyam version = pyam.__version__ # The full version, including alpha/beta/rc tags. release = pyam.__version__ @@ -131,19 +131,23 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -#html_theme = 'cloud' - -sys.path.append(os.path.abspath('_themes')) -html_theme_path = ['_themes'] -html_theme = 'kr' +html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + 'logo': 'logo.svg', + 'logo_name': True, + 'description': 'analysis & visualization of integrated-assessment scenarios', + 'sidebar_width': '225px', + 'github_button': True, + 'github_user': 'iamconsortium', + 'github_repo': 'pyam', +} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = ['_templates'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -154,7 +158,7 @@ # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = '_static/logo.svg' +#html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 @@ -180,7 +184,9 @@ #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + '**': ['about.html', 'navigation.html', 'searchbox.html'] +} # Additional templates that should be rendered to pages, maps page names to # template names. @@ -227,7 +233,7 @@ #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'pyamdoc' +htmlhelp_basename = 'pyam-docs' # -- Options for LaTeX output --------------------------------------------- @@ -313,3 +319,15 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'https://docs.python.org/': None} + + +# prolog for all rst files +rst_prolog = """ + +.. |pyam| replace:: :class:`pyam` + +.. |br| raw:: html + +
+ +""" diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 000000000..4d7098a15 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,4 @@ +Support and Contributing +======================== + +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/data.rst b/doc/source/data.rst index 44faf9c96..5912e724b 100644 --- a/doc/source/data.rst +++ b/doc/source/data.rst @@ -1,53 +1,128 @@ - Data Model ----------- +========== + +Scenario data following the IAMC format +--------------------------------------- + +.. figure:: _static/iamc_logo.jpg + :width: 120px + :align: right + + `IAMC website`_ + +.. _`IAMC Website`: http://www.globalchange.umd.edu/iamc/ + +Over the past decade, the Integrated Assessment Modeling Consortium (IAMC) +developed a standardised tabular timeseries format to exchange scenario data. +Previous high-level use cases include reports by the *Intergovernmental Panel +on Climate Change* (`IPCC`_) and model comparison exercises +within the *Energy Modeling Forum* (`EMF`_) hosted by Stanford University. + +The table below shows a typical example of integrated-assessment scenario data +following the IAMC format from the `CD-LINKS`_ project. +The |pyam| package is geared for analysis and visualization of any scenario +data provided in this structure. + +.. figure:: _static/iamc_template.png + + Illustrative example of IAMC-format timeseries data |br| + via the `IAMC 1.5°C Scenario Explorer`_ (:cite:`Huppmann:2019:scenario-data`) + +.. _`IAMC 1.5°C Scenario Explorer`: https://data.ene.iiasa.ac.at/iamc-1.5c-explorer + +Refer to `data.ene.iiasa.ac.at/database`_ for more information on the +IAMC format and a full list of previous use cases. + +.. _`IPCC`: https://www.ipcc.ch + +.. _`EMF`: https://emf.stanford.edu + +.. _`CD-LINKS`: https://www.cd-links.org + +.. _`data.ene.iiasa.ac.at/database`: https://data.ene.iiasa.ac.at/database -IAMC-style Data -^^^^^^^^^^^^^^^ +The :code:`variable` column +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -An illustrative example of IAMC-style data is shown below; -see https://data.ene.iiasa.ac.at/database for more information. +The :code:`variable` column implements a "semi-hierarchical" structure +using the :code:`|` character (*pipe*, not l or i) to indicate the *depth*. -============ ============= ========== ============== ======== ======== ======== ======== -**Model** **Scenario** **Region** **Variable** **Unit** **2005** **2010** **2015** -============ ============= ========== ============== ======== ======== ======== ======== -MESSAGE V.4 AMPERE3-Base World Primary Energy EJ/y 454.5 479.6 ... -... ... ... ... ... ... ... ... -============ ============= ========== ============== ======== ======== ======== ======== +Semi-hierarchical means that a hierarchy can be imposed, e.g., one can enforce +that the sum of :code:`Emissions|CO2|Energy` and :code:`Emissions|CO2|Other` +must be equal to :code:`Emissions|CO2` +(if there are no other :code:`Emissions|CO2|…` variables). +However, this is not mandatory, e.g., the sum of :code:`Primary Energy|Coal`, +:code:`Primary Energy|Gas` and :code:`Primary Energy|Fossil` should not be equal +to :code:`Primary Energy` because this would double-count fossil fuels. +Refer to the variable list in the documentation pages of the +`IAMC 1.5°C Scenario Explorer`_ to see the full list of variables used in the +recent *IPCC Special Report on Global Warming of 1.5 ºC* (`SR15`_). -``pyam.IamDataFrame`` -^^^^^^^^^^^^^^^^^^^^^ +.. _`SR15`: https://www.ipcc.ch/sr15/ -A ``pyam.IamDataFrame`` is a wrapper for two ``pandas.DataFrame`` instances: +The :code:`year` column +~~~~~~~~~~~~~~~~~~~~~~~ - - `data`: The data table is a dataframe containing the timeseries data in - "long format". It has the columns ``pyam.LONG_IDX = ['model', 'scenario', - 'region', 'unit', 'year', 'value']``. +In its original design, the IAMC data format (see above) assumed that the +temporal dimension of any scenario data was restricted to full years +represented as integer values. - - `meta`: The meta table is a dataframe containing categorisation and - descriptive indicators. It has the index ``pyam.META_IDX = ['model', - 'scenario']``. +Two additional use cases are currently supported by :code:`pyam` in development +mode (beta): + + - using representative sub-annual timesteps + + - using continuous time via :class:`pandas.datetime`, replacing the name of + the :code:`year` column by :code:`time` + +Please reach out to the developers to get more information on this +ongoing work. + +The :class:`pyam.IamDataFrame` class +------------------------------------ + +A :class:`pyam.IamDataFrame` instance is a wrapper for +two :class:`pandas.DataFrame` instances (read the `docs`_): + + - :code:`data`: The data table is a dataframe containing the timeseries data + in "long format". It has the columns of the long data format :code:`['model', + 'scenario', 'region', 'unit', 'year', 'value']`. + + - :code:`meta`: The meta table is a dataframe containing categorisation and + descriptive indicators. It has the index :code:`pyam.META_IDX = ['model', + 'scenario']`. The standard output format is the IAMC-style "wide format", see the example above. This format can be accessed using :meth:`pyam.IamDataFrame.timeseries`, -which returns a ``pandas.DataFrame`` with the index ``pyam.IAMC_IDX = ['model', -'scenario', 'region', 'variable', 'unit']`` and the years as columns. +which returns a :class:`pandas.DataFrame` with the index :code:`pyam.IAMC_IDX = +['model', 'scenario', 'region', 'variable', 'unit']` and the years as columns. + +.. _`docs`: https://pandas.pydata.org/pandas-docs/stable/reference/frame.html Filtering -^^^^^^^^^ - -The `pyam` package provides two methods for filtering timeseries data: - -An existing IamDataFrame can be filtered using -:meth:`pyam.IamDataFrame.filter(col=...) `, where `col` can be any column of the -`data` table (i.e., ``['model', 'scenario', 'region', 'unit', 'year']``) or any -column of the `meta` table. The returned object is a new ``pyam.IamDataFrame`` -instance. - -A ``pandas.DataFrame`` with columns or index ``['model', 'scenario']`` can be -filtered by any `meta` columns from a ``pyam.IamDataFrame`` using -:func:`pyam.filter_by_meta(data, df, col=..., join_meta=False) `. The returned -object is a ``pandas.DataFrame`` downselected to those models-and-scenarios where -the `meta` column satisfies the criteria given by `col=...` . -Optionally, the `meta` columns are joined to the returned dataframe. +--------- + +The |pyam| package provides two methods for filtering scenario data: + +An existing `class`:IamDataFrame can be filtered using +:meth:`pyam.IamDataFrame.filter(col=...) `, +where :code:`col` can be any column of the +:code:`data` table (i.e., `['model', 'scenario', 'region', 'unit', 'year']`) +or any column of the :code:`meta` table. The returned object is +a new :class:`pyam.IamDataFrame` instance. + +A :class:`pandas.DataFrame` with columns or index :code:`['model', 'scenario']` +can be filtered by any :code:`meta` columns from a :code:`pyam.IamDataFrame` +using :func:`pyam.filter_by_meta(data, df, col=..., join_meta=False) `. +The returned object is a :class:`pandas.DataFrame` down-selected to those +models-and-scenarios where the :code:`meta` column satisfies the criteria given +by :code:`col=...` . +Optionally, the :code:`meta` columns are joined to the returned dataframe. + +References +---------- + +.. bibliography:: _bib/data.bib + :style: plain + :cited: diff --git a/doc/source/index.rst b/doc/source/index.rst index e3d6e8981..b435097f2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,10 +1,6 @@ **pyam**: analysis and visualization of integrated-assessment scenarios ======================================================================= -.. |br| raw:: html - -
- Release v\ |version|. |pypi| |conda| |license| |latest| @@ -44,53 +40,60 @@ Release v\ |version|. .. |doi| image:: https://zenodo.org/badge/113359260.svg :target: https://zenodo.org/badge/latestdoi/113359260 -The **pyam** Python package provides a suite of diagnostic tools and functions -for analyzing and visualizing input data and scenario results -of your favorite integrated-assessment model(s). +Overview +-------- -The source code for **pyam** is available on `Github`_. +The open-source Python package |pyam| :cite:`Gidden:2019:pyam` +provides a suite of tools and functions for analyzing and visualizing +input data (i.e., assumptions/parametrization) +and results (model output) of integrated-assessment scenarios. -.. _`Github`: - https://github.com/IAMconsortium/pyam +Key features: +~~~~~~~~~~~~~ -Overview --------- + - Simple analysis of timeseries data in the IAMC format (more about it `here`_) + with an interface similar in feel and style to the widely + used `pandas.DataFrame`_ + - Advanced visualization and plotting function (see the `gallery`_) + - Diagnostic checks for scripted validation of scenario data and results + +The source code for |pyam| is available on `Github`_. -Some of the **pyam** features include: - - Easily filter and manipulate data in the `IAMC`_ timeseries format - - An interface similar in feel and style to `pandas.DataFrame`_ - - Advanced visualization and plotting functions. - - Diagnostic checks for non-reported variables or timeseries values - to analyze and validate scenario data. - - Categorization of scenarios according to timeseries data - or metadata for further analysis. +.. _`here`: + data.html -.. _`IAMC`: - https://data.ene.iiasa.ac.at/database +.. _`gallery`: + examples/index.html .. _`pandas.DataFrame`: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html -After installing, check out our tutorials or our plotting gallery to get -started. +.. _`Github`: + https://github.com/IAMconsortium/pyam -Documentation -------------- +Table of Contents +----------------- .. toctree:: - :maxdepth: 1 + :maxdepth: 2 install + contributing data tutorials examples/index api -.. include:: ../../CONTRIBUTING.rst - License ------- -:code:`pyam` is available under the open source `Apache License`_. +|pyam| is available under the open source `Apache License`_. .. _Apache License: http://www.apache.org/licenses/LICENSE-2.0.html + +Scientific reference +-------------------- + +.. bibliography:: _bib/index.bib + :style: plain + :all: diff --git a/doc/source/install.rst b/doc/source/install.rst index a1f92fe5c..925dc2724 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -1,45 +1,44 @@ .. _install: -Install -******* +Installation +============ -The most basic installation of :code:`pyam` is trivial. +Via your favourite Python Package Manager +----------------------------------------- -Via Conda -~~~~~~~~~ +Conda +~~~~~ .. code-block:: bash conda install -c conda-forge pyam -Via Pip -~~~~~~~ - -:code:`pyam` can also be installed via pip. +Pip +~~~ .. code-block:: bash pip install pyam-iamc -From Source -~~~~~~~~~~~ +Installing From Source +---------------------- -:code:`pyam` can also be installed from source. +|pyam| can also be installed from source. .. code-block:: bash pip install -e git+https://github.com/IAMconsortium/pyam.git#egg=pyam -Depedencies -~~~~~~~~~~~ +Dependencies +------------ Like any software project, we stand on the shoulders of giants. Our particular giants include :code:`numpy` :cite:`numpy`, :code:`matplotlib` :cite:`matplotlib`, and :code:`pandas` :cite:`pandas`. Explicit requirements are fully enumerated below. -The required depedencies for :code:`pyam` are: +The required depedencies for |pyam| are: .. program-output:: python -c 'import sys; sys.path.append("../.."); import setup; print("\n".join([r for r in setup.REQUIREMENTS]))' @@ -50,8 +49,8 @@ The depedencies for building this documentation are: :literal: References -~~~~~~~~~~ +---------- -.. bibliography:: refs.bib +.. bibliography:: _bib/install.bib :style: plain - :all: + :cited: