Add documentation for the pyam.iiasa.Connection class (#384)

IAMconsortium · Jun 3, 2020 · ea481ef · ea481ef
1 parent fbee76d
commit ea481ef
Show file tree

Hide file tree

Showing 6 changed files with 78 additions and 47 deletions.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -3,6 +3,7 @@
 ## Individual Updates
 
 - [#386](https://github.com/IAMconsortium/pyam/pull/386) Enables unit conversion to apply to strings with "-equiv" in them. 
+- [#384](https://github.com/IAMconsortium/pyam/pull/384) Add documentation for the pyam.iiasa.Connection class.
 - [#382](https://github.com/IAMconsortium/pyam/pull/382) Streamline dependencies and implementation of xlsx-io
 - [#373](https://github.com/IAMconsortium/pyam/pull/373) Extends the error message when initializing with duplicate rows.
 - [#370](https://github.com/IAMconsortium/pyam/pull/370) Allowed filter to work with np.int64 years and np.datetime64 dates.  

diff --git a/doc/source/api.rst b/doc/source/api.rst
@@ -13,6 +13,7 @@ and methods.
    api/general
    api/iamdataframe
    api/filtering
+   api/iiasa
    api/statistics
    api/timeseries
    api/variables

diff --git a/doc/source/api/iiasa.rst b/doc/source/api/iiasa.rst
@@ -0,0 +1,19 @@
+.. currentmodule:: pyam.iiasa
+
+The **Connection** class
+========================
+
+IIASA's ixmp scenario explorer infrastructure implements a RestAPI
+to directly query the database server connected to an explorer instance.
+See https://software.ene.iiasa.ac.at/ixmp-server for more information.
+
+The |pyam| package uses this interface to read timeseries data as well as
+categorization and quantitative indicators.
+The data is returned as an :class:`IamDataFrame`.
+See `this tutorial <../tutorials/iiasa_dbs.html>`_ for more information.
+
+.. autoclass:: Connection
+   :members:
+
+.. autofunction:: read_iiasa
+   :noindex:
diff --git a/doc/source/api/io.rst b/doc/source/api/io.rst
@@ -14,10 +14,13 @@ directly by initializing an :class:`IamDataFrame` - see
 Exporting to these formats is implemented via the following functions:
 
 .. automethod:: IamDataFrame.as_pandas
+   :noindex:
 
 .. automethod:: IamDataFrame.to_excel
+   :noindex:
 
 .. automethod:: IamDataFrame.to_csv
+   :noindex:
 
 The frictionless Data Package
 -----------------------------
@@ -28,14 +31,18 @@ The |pyam| package supports reading and writing to the
 .. autofunction:: read_datapackage
 
 .. automethod:: IamDataFrame.to_datapackage
+   :noindex:
 
 Connecting to an IIASA scenario explorer instance
 -------------------------------------------------
 
-IIASA's ixmp scenario explorer infrastructure includes a RestAPI
-to query data directly from the database server.
-The |pyam| package uses this interface to read resources
-and initialize an :class:`IamDataFrame`.
-See `this tutorial ../tutorials/iiasa_dbs.html>`_ for more information.
+IIASA's ixmp scenario explorer infrastructure implements a RestAPI
+to directly query the database server connected to an explorer instance.
+See https://software.ene.iiasa.ac.at/ixmp-server for more information.
+
+The |pyam| package uses this interface to read timeseries data as well as
+categorization and quantitative indicators.
+The data is returned as an :class:`IamDataFrame`.
+See `this tutorial <../tutorials/iiasa_dbs.html>`_ for more information.
 
 .. autofunction:: read_iiasa
diff --git a/doc/source/tutorials/iiasa_dbs.ipynb b/doc/source/tutorials/iiasa_dbs.ipynb
@@ -4,9 +4,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Read Directly from IIASA Data Resources\n",
+    "# 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.\n",
+    "The IIASA Energy Program hosts a suite of **Scenario Explorer** instances and related infrastructure to support analysis of integrated-assessment pathways in IPCC reports and model comparison projects. \n",
+    "High-profile use cases include the [IAMC 1.5°C Scenario Explorer hosted by IIASA](https://data.ene.iiasa.ac.at/iamc-1.5c-explorer) supporting the *IPCC Special Report on Global Warming of 1.5°C* (SR15) and the Horizon 2020 project [CD-LINKS](https://data.ene.iiasa.ac.at/cd-links).\n",
+    "\n",
+    "IIASA's [modeling platform infrastructure](http://software.ene.iiasa.ac.at/ixmp-server) and the Scenario Explorer UI 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."
    ]
   },
@@ -23,7 +26,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Accessing an explorer is done via a `Connection` object. By default, all public explorers can be connected to. "
+    "Accessing an explorer is done via a `Connection` object.\n",
+    "By default, your can connect to all public scenario explorers instances. "
    ]
   },
   {
@@ -54,14 +58,14 @@
     "In this example, we will be pulling data from the Special Report on 1.5C explorer. This can be done either via the constructor:\n",
     "\n",
     "```\n",
-    "pyam.iiasa.Connection('IXSE_SR15')\n",
+    "pyam.iiasa.Connection('iamc15')\n",
     "```\n",
     "\n",
     "or, if you want to query multiple databases, via the explicit `connect()` method:\n",
     "\n",
     "```\n",
     "conn = pyam.iiasa.Connection()\n",
-    "conn.connect('IXSE_SR15')\n",
+    "conn.connect('iamc15')\n",
     "```"
    ]
   },
@@ -80,7 +84,7 @@
    "outputs": [],
    "source": [
     "df = pyam.read_iiasa(\n",
-    "    'IXSE_SR15',\n",
+    "    'iamc15',\n",
     "    model='MESSAGEix*', \n",
     "    variable=['Emissions|CO2', 'Primary Energy|Coal'], \n",
     "    region='World',\n",
@@ -134,9 +138,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Exploring the Data Source\n",
+    "## Exploring the data resource\n",
     "\n",
-    "If you're interested in what data is actually in the data source, you can use `pyam.iiasa.Connection` to do so."
+    "If you're interested in what data is actually in the data source, you can use **pyam.iiasa.Connection** to do so."
    ]
   },
   {
@@ -145,7 +149,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "conn = pyam.iiasa.Connection('IXSE_SR15')"
+    "conn = pyam.iiasa.Connection('iamc15')"
    ]
   },
   {
@@ -212,7 +216,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can directly query the `Connection`, which will give you a [pandas.DataFrame](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html)."
+    "You can directly query the **Connection**, which will give you a [pandas.DataFrame](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html)."
    ]
   },
   {
@@ -233,7 +237,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "And you can easily turn this into a `pyam.IamDataFrame` to continue your analysis."
+    "And you can easily turn this into a **pyam.IamDataFrame** to continue your analysis."
    ]
   },
   {

diff --git a/pyam/iiasa.py b/pyam/iiasa.py
@@ -81,7 +81,7 @@ def __init__(self, name=None, creds=None, base_url=_BASE_URL):
                 (preferred)
               - an ordered container (tuple, list, etc.) with the same values
               - a dictionary with the same keys
-        base_url: str, custom authentication server URL
+        base_url : str, custom authentication server URL
         """
         self._base_url = base_url
         self._token = _get_token(creds, base_url=self._base_url)
@@ -171,9 +171,9 @@ def scenario_list(self, default=True):
         Metadata regarding the list of scenarios (e.g., models, scenarios,
         run identifier, etc.) in the connected data source.
 
-        Parameter
-        ---------
-        default : bool, optional, default True
+        Parameters
+        ----------
+        default : bool, optional
             Return *only* the default version of each Scenario.
             Any (`model`, `scenario`) without a default version is omitted.
             If :obj:`False`, return all versions.
@@ -188,10 +188,7 @@ def scenario_list(self, default=True):
 
     @lru_cache()
     def available_metadata(self):
-        """
-        List all scenario metadata indicators available in the connected
-        data source
-        """
+        """List all available meta indicators in the instance"""
         url = '/'.join([self._base_url, 'metadata/types'])
         headers = {'Authorization': 'Bearer {}'.format(self._token)}
         r = requests.get(url, headers=headers)
@@ -200,12 +197,11 @@ def available_metadata(self):
 
     @lru_cache()
     def metadata(self, default=True):
-        """
-        Metadata of scenarios in the connected data source
+        """All meta categories and indicators of scenarios
 
-        Parameter
-        ---------
-        default : bool, optional, default True
+        Parameters
+        ----------
+        default : bool, optional
             Return *only* the default version of each Scenario.
             Any (`model`, `scenario`) without a default version is omitted.
             If :obj:`False`, return all versions.
@@ -256,9 +252,12 @@ def variables(self):
     def regions(self, include_synonyms=False):
         """All regions in the connected data source
 
-        :param include_synonyms: whether to include synonyms
-               (possibly leading to duplicate region names for
-               regions with more than one synonym)
+        Parameters
+        ----------
+        include_synonyms : bool
+            whether to include synonyms
+            (possibly leading to duplicate region names for
+            regions with more than one synonym)
         """
         url = '/'.join([self._base_url, 'nodes?hierarchy=%2A'])
         headers = {'Authorization': 'Bearer {}'.format(self._token)}
@@ -345,9 +344,9 @@ def _match(data, patterns):
         return data
 
     def query(self, **kwargs):
-        """
-        Query the data source, subselecting data. Available keyword arguments
-        include
+        """Query the data source with filters
+
+        Available keyword arguments include
 
         - model
         - scenario
@@ -406,28 +405,28 @@ def query(self, **kwargs):
 
 
 def read_iiasa(name, meta=False, creds=None, base_url=_BASE_URL, **kwargs):
-    """
-    Query an IIASA database. See Connection.query() for more documentation
+    """Read data from an IIASA scenario explorer and return as IamDataFrame
 
     Parameters
     ----------
     name : str
-        A valid IIASA database name, see pyam.iiasa.valid_connections()
+        A valid name of an IIASA scenario explorer instance,
+        see :attr:`pyam.iiasa.Connection.valid_connections`
     meta : bool or list of strings
-        If not False, also include metadata indicators (or subset if provided).
+        If :obj:`True`, include all meta categories & quantitative indicators
+        (or subset if list is given).
     creds : dict
-        Credentials to access IXMP and authentication service APIs
-        (username/password)
-    base_url: str
+        Credentials to access scenario explorer instance and
+        authentication service APIs (username/password)
+    base_url : str
         Authentication server URL
-    kwargs :
-        Arguments for pyam.iiasa.Connection.query()
+    kwargs
+        Arguments for :meth:`pyam.iiasa.Connection.query`
     """
     conn = Connection(name, creds, base_url)
     # data
-    df = conn.query(**kwargs)
-    df = IamDataFrame(df)
-    # metadata
+    df = IamDataFrame(conn.query(**kwargs))
+    # meta: categorization and quantitative indications
     if meta:
         mdf = conn.metadata()
         # only data for models/scenarios in df