Merge 713d980 into 412ff2a

CONTRIBUTING.rst

@@ -12,8 +12,8 @@ Have a question? Get in touch!
 .. _Slack: https://slack.com
 
 
-Interested in contributing? Join to the team!
----------------------------------------------
+Interested in contributing? Join the team!
+------------------------------------------
 
 The pyam package has been developed with the explicit aim to facilitate
 open and collaborative analysis of integrated assessment and climate models.

doc/source/tutorials.rst

@@ -8,7 +8,7 @@ Tutorials
    :maxdepth: 1
 
    tutorials/pyam_first_steps.ipynb
-   tutorials/aggregating_downscaling_consistency.ipynb.ipynb
+   tutorials/aggregating_downscaling_consistency.ipynb
    tutorials/ipcc_colors.ipynb
    tutorials/iiasa_dbs.ipynb
    tutorials/aggregating_variables_and_plotting_with_negative_values.ipynb

doc/source/tutorials/aggregating_downscaling_consistency.ipynb

@@ -334,17 +334,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 4. Checking complete internal consistency of a scenario (ensemble)\n",
+    "## 4. Checking the internal consistency of a scenario (ensemble)\n",
     "\n",
     "The previous sections illustrated two functions to validate specific variables across their sectors (sub-categories) or regional disaggregation.\n",
     "These two functions are combined in the [check_internal_consistency()](https://pyam-iamc.readthedocs.io/en/stable/api.html#pyam.IamDataFrame.check_internal_consistency) feature.\n",
     "\n",
-    "<div class=\"alert alert-block alert-warning\">\n",
-    "    This feature of the <b>pyam</b> package currently only supports \"consistency\"\n",
-    "    in the sense of a strictly hierarchical variable tree\n",
-    "    (with subcategories summing up to the category value including components, discussed above)\n",
-    "    and that all the regions sum to the <b>World</b> region.\n",
-    "    See <a href=\"https://github.com/IAMconsortium/pyam/issues/106\">this issue</a> for more information.\n",
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "This feature of the **pyam** package currently only supports \"consistency\"\n",
+    "in the sense of a strictly hierarchical variable tree\n",
+    "(with subcategories summing up to the category value including components, discussed above)\n",
+    "and that all the regions sum to the ``World`` region.  \n",
+    "See [this issue](https://github.com/IAMconsortium/pyam/issues/106) for more information.\n",
+    "\n",
     "</div>\n",
     "\n",
     "If we have an internally consistent scenario ensemble (or single scenario), the function will return `None`; otherwise, it will return a concatenation of [pandas.DataFrames](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html) indicating all detected inconsistencies.\n",
@@ -414,9 +416,11 @@
     "The output of this function reports both types of illustrative inconsistencies in the scenario constructed for this section.\n",
     "The log also shows that the other two variables (coal and wind) cannot be assessed because they have no subcategories.\n",
     "\n",
-    "<div class=\"alert alert-block alert-info\">\n",
-    "    In practice, it would now be up to the user to determine\n",
-    "    the cause of the inconsistency (or confirm that this is expected for some reason).\n",
+    "<div class=\"alert alert-info\">\n",
+    "    \n",
+    "In practice, it would now be up to the user to determine\n",
+    "the cause of the inconsistency (or confirm that this is expected for some reason).\n",
+    "\n",
     "</div>"
    ]
   }

doc/source/tutorials/iiasa_dbs.ipynb

@@ -6,7 +6,8 @@
    "source": [
     "# Read Directly from IIASA Data Resources\n",
     "\n",
-    "IIASA's new [scenario explorer](https://data.ene.iiasa.ac.at/iamc-1.5c-explorer/#/workspaces) is not only a great resource on its own, but it also allows the underlying datasets to be directly queried. `pyam`  takes advantage of this ability to allow you to easily pull data and work with it."
+    "IIASA's new [scenario explorer](https://data.ene.iiasa.ac.at/iamc-1.5c-explorer/#/workspaces) is not only a great resource on its own, but it also allows the underlying datasets to be directly queried.\n",
+    "**pyam** takes advantage of this ability to allow you to easily pull data and work with it."
    ]
   },
   {
@@ -194,7 +195,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A number of different kinds of indicators are available for model/scenario combinations. We queried the `category` metadata in the above example, but there are many more. You can see them with"
+    "A number of different kinds of indicators are available for model/scenario combinations.\n",
+    "We queried the \"category\" metadata in the above example, but there are many more. You can see them with"
    ]
   },
   {
@@ -210,7 +212,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can directly query the `Connection`, which will give you a `pd.DataFrame`"
+    "You can directly query the `Connection`, which will give you a [pandas.DataFrame](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html)."
    ]
   },
   {

doc/source/tutorials/ipcc_colors.ipynb

@@ -40,7 +40,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We use the scenario ensemble from the **first-steps tutorial** ([link](https://github.com/IAMconsortium/pyam/blob/master/doc/source/tutorials/pyam_first_steps.ipynb)).\n",
+    "## Display scenario data with default colours\n",
+    "\n",
+    "We use the scenario ensemble from the **first-steps tutorial** (here on\n",
+    "[GitHub](https://github.com/IAMconsortium/pyam/blob/master/doc/source/tutorials/pyam_first_steps.ipynb)\n",
+    "and on [read the docs](https://pyam-iamc.readthedocs.io/en/stable/tutorials/pyam_first_steps.html)).\n",
     "Let's pull out two example scenarios (implemented by multiple modelling frameworks each) and plot them with the default color scheme."
    ]
   },
@@ -74,9 +78,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Updating the run control\n",
+    "## Updating the run control\n",
     "\n",
-    "We need to tell `pyam` that whenever it sees a certain scenario name, it should use a specific color."
+    "We need to tell **pyam** that whenever it sees a certain scenario name, it should use a specific color from the IPCC palette."
    ]
   },
   {
@@ -104,9 +108,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Use the new colors\n",
+    "## Use the new colors\n",
     "\n",
-    "It's as simple as calling the plot function!"
+    "Now, it's as simple as calling the plot function again!"
    ]
   },
   {

doc/source/tutorials/legends.ipynb

@@ -109,13 +109,6 @@
    "source": [
     "df.line_plot(color='model', legend=OUTSIDE_LEGEND['bottom'])"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

doc/source/tutorials/pyam_first_steps.ipynb

@@ -61,18 +61,21 @@
     "\n",
     "Please refer to the [About](https://data.ene.iiasa.ac.at/iamc-1.5c-explorer/#/about) page of the *IAMC 1.5°C Scenario Explorer* for references and additional information.\n",
     "\n",
-    "<div style=\"text-align: center; margin: 10px; width: 700px\">\n",
-    "<div class=\"alert alert-block alert-warning\">\n",
-    "    <i>The data used here is a partial snapshot of the IAMC 1.5°C Scenario Data!</i><br />\n",
-    "    <i>This tutorial is only intended as an illustration of the <b>pyam</b> package.</i>\n",
-    "</div></div>\n",
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "The data used here is a partial snapshot of the IAMC 1.5°C Scenario Data!  \n",
+    "This tutorial is only intended as an illustration of the **pyam** package.\n",
+    "\n",
+    "</div>\n",
     "\n",
     "### Citation of the scenario ensemble\n",
     "\n",
     "> D. Huppmann, E. Kriegler, V. Krey, K. Riahi, J. Rogelj, K. Calvin, F. Humpenoeder, A. Popp, S. K. Rose, J. Weyant, et al.  \n",
     "> *IAMC 1.5°C Scenario Explorer and Data hosted by IIASA* (release 2.0)  \n",
     "> Integrated Assessment Modeling Consortium & International Institute for Applied Systems Analysis, 2019.  \n",
-    "> doi: [10.5281/zenodo.3363345](https://doi.org/10.5281/zenodo.3363345) | url: [data.ene.iiasa.ac.at/iamc-1.5c-explorer](https://data.ene.iiasa.ac.at/iamc-1.5c-explorer)"
+    "> doi: [10.5281/zenodo.3363345](https://doi.org/10.5281/zenodo.3363345) | url: [data.ene.iiasa.ac.at/iamc-1.5c-explorer](https://data.ene.iiasa.ac.at/iamc-1.5c-explorer)\n",
+    "\n",
+    "***"
    ]
   },
   {
@@ -94,10 +97,12 @@
     "\n",
     "We import the snapshot of the timeseries data from the file ``tutorial_data.csv``.\n",
     "\n",
-    "<div class=\"alert alert-block alert-info\">\n",
-    "If you haven't cloned the <b>pyam</b> GitHub repository to your machine, you can download the file\n",
-    "from the folder <a href=\"https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials\">doc/source/tutorials</a>. <br />\n",
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "If you haven't cloned the **pyam** GitHub repository to your machine, you can download the file\n",
+    "from the folder [doc/source/tutorials](https://github.com/IAMconsortium/pyam/tree/master/doc/source/tutorials).  \n",
     "Make sure to place the file in the same folder as this notebook.\n",
+    "\n",
     "</div>"
    ]
   },
@@ -300,10 +305,12 @@
     "\n",
     "As a next step, we want to view a selection of the timeseries data.\n",
     "\n",
-    "<div class=\"alert alert-block alert-info\">\n",
-    "    The <a href=\"https://pyam-iamc.readthedocs.io/en/stable/api.html#pyam.IamDataFrame.timeseries\">timeseries()</a> function\n",
-    "    returns the data as a <a href=\"https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html\">pandas.DataFrame</a> in the standard IAMC template. <br />\n",
-    "    This is a <b>wide format</b> table where years are shown as columns.\n",
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "The [timeseries()](https://pyam-iamc.readthedocs.io/en/stable/api.html#pyam.IamDataFrame.timeseries) function\n",
+    "returns the data as a [pandas.DataFrame](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html) in the standard IAMC template.  \n",
+    "This is a **wide format** table where years are shown as columns.\n",
+    "\n",
     "</div>"
    ]
   },
@@ -325,9 +332,11 @@
     "\n",
     "Filtering for **years** can be done by one integer value, a list of integers, or the Python class [range](https://docs.python.org/3/library/stdtypes.html#ranges).\n",
     "\n",
-    "<div class=\"alert alert-block alert-info\">\n",
-    "    The last year of a range is not included, so <code>range(2010, 2015)</code>\n",
-    "    is interpreted as <code>[2010, 2011, 2012, 2013, 2014]</code>.\n",
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "The last year of a range is not included, so `range(2010, 2015)`\n",
+    "is interpreted as `[2010, 2011, 2012, 2013, 2014]`.\n",
+    "\n",
     "</div>\n",
     "\n",
     "The next cell shows the same down-selected `IamDataFrame` as above, but further reduced to three timesteps."
@@ -872,11 +881,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "<div class=\"alert alert-block alert-info\">\n",
-    "    <b>New to Jupyter notebooks?</b>\n",
-    "    Read <a href=\"https://www.dataquest.io/blog/jupyter-notebook-tips-tricks-shortcuts/\">this page</a> for helpful tips and tricks when working with Jupyter notebooks.\n",
-    "</div>\n",
+    "<div class=\"alert alert-info\">\n",
+    "    \n",
+    "**New to Jupyter notebooks?**\n",
+    "Read [this page](https://www.dataquest.io/blog/jupyter-notebook-tips-tricks-shortcuts/) for helpful tips and tricks when working with Jupyter notebooks.\n",
     "\n",
+    "</div>\n",
     "\n",
     "## Questions?\n",
     "\n",

pyam/core.py

@@ -46,9 +46,9 @@
 
 
 class IamDataFrame(object):
-    """This class is a wrapper for dataframes following the IAMC format.
+    """This class is a wrapper for timeseries data following the IAMC format.
     It provides a number of diagnostic features (including validation of data,
-    completeness of variables provided) as well as a number of visualization
+    completeness of variables provided) as well as visualization
     and plotting tools.
 
     Parameters
@@ -148,7 +148,7 @@ def _execute_run_control(self):
                 f(self)
 
     def copy(self):
-        """Return a deepcopy of self
+        """Make a deepcopy of this object
 
         Documentation about deepcopy is available
         `here <https://docs.python.org/2/library/copy.html#copy.deepcopy>`_
@@ -165,7 +165,7 @@ def tail(self, *args, **kwargs):
 
     @property
     def empty(self):
-        """Indicator whether ``IamDataFrame`` is empty"""
+        """Indicator whether this object is empty"""
         return self.data.empty
 
     def equals(self, other):
@@ -766,8 +766,9 @@ def convert_unit(self, conversion_mapping, inplace=False):
             return ret
 
     def normalize(self, inplace=False, **kwargs):
-        """Normalize data to a given value. Currently only supports normalizing
-        to a specific time.
+        """Normalize data to a specific data point
+
+        Currently only supports normalizing to a specific time.
 
         Parameters
         ----------
@@ -870,9 +871,9 @@ def aggregate_region(self, variable, region='World', subregions=None,
         Parameters
         ----------
         variable: str or list of str
-            variable(s) for which the aggregate will be computed
+            variable(s) to be aggregated
         region: str, default 'World'
-            dimension
+            region to which data will be aggregated
         subregions: list of str
             list of subregions, defaults to all regions other than `region`
         components: bool or list of str, default False
@@ -979,7 +980,7 @@ def downscale_region(self, variable, proxy, region='World',
         proxy: str
             variable to be used as proxy (i.e, weight) for the downscaling
         region: str, default 'World'
-            dimension
+            region from which data will be downscaled
         subregions: list of str
             list of subregions, defaults to all regions other than `region`
         append: bool, default False
@@ -1290,7 +1291,7 @@ def load_metadata(self, path, *args, **kwargs):
         self.load_meta(path, *args, **kwargs)
 
     def load_meta(self, path, *args, **kwargs):
-        """Load ``meta`` table  exported from a ``pyam.IamDataFrame`` instance
+        """Load ``meta`` table  exported from a :class:`IamDataFrame` instance
 
         Parameters
         ----------
@@ -1324,7 +1325,7 @@ def load_meta(self, path, *args, **kwargs):
 
         df = df.loc[idx]
 
-        # Merge in imported metadata
+        # merge in imported metadata
         msg = 'Importing metadata for {} scenario{} (for total of {})'
         logger.info(msg.format(len(df), 's' if len(df) > 1 else '',
                                  len(self.meta)))