Merge pull request #188 from khaeru/report-message-data

- Reporter:
  - add exceptions: KeyExistsError, MissingKeyError, ComputationError.
  - full_key(): handle a wider set of inputs.
- reporting.key: move Key here from reporting.utils
  - name, dims, and tag are all now read-only public properties.
  - cache str() and repr() for a small speed gain
  - add methods drop(), append(), add_tag().
  - use new methods in from_str_or_key().
- reporting.attrseries: move AttrSeries here from reporting.utils
  - add methods dims(), transpose(), to_dataframe()
  - sel(): avoid dropping indices in certain cases.
- reporting.utils: use upper-case consistently for global RENAME_DIMS, UNITS
- computations.write_report: handle str path argument.
- Expand documentation.

.gitignore

@@ -26,17 +26,13 @@
 # Apple file system
 .DS_Store
 
-# local version of auto-documentation features
-/doc/build/**
-/doc/source/model/**
+# sphinx
+doc/build
 
-# files generated during install
+# setuptools
 build
 dist
 
-# credentials
-config/*.properties
-
 # testdb
 .cache/**
 tests/testdb/test.properties
@@ -55,11 +51,12 @@ rixmp/source/.Rhistory
 # virtualenv
 .env
 
-# pytest
+# pytest and related
 *.pid
-.coverage*
+.coverage
 .pytest_cache/
 coverage.xml
+htmlcov/
 
 # idea
 .idea/

RELEASE_NOTES.md

@@ -1,6 +1,7 @@
 
 # Next Release
 
+- [#188](https://github.com/iiasa/ixmp/pull/188): Enhance reporting.
 - [#177](https://github.com/iiasa/ixmp/pull/177): add ability to pass `gams_args` through `Scenario.solve()`
 - [#175](https://github.com/iiasa/ixmp/pull/175): Drop support for Python 2.
 - [#174](https://github.com/iiasa/ixmp/pull/174): Set `convertStrings=True` for JPype >= 0.7; see the [JPype changelog](https://jpype.readthedocs.io/en/latest/CHANGELOG.html).

doc/source/conf.py

@@ -302,8 +302,8 @@ def setup(app):
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/', None),
-    'dask': ('http://docs.dask.org/en/stable/', None),
+    'python': ('https://docs.python.org/3/', None),
+    'dask': ('https://docs.dask.org/en/stable/', None),
     'jpype': ('https://jpype.readthedocs.io/en/latest', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
     'pint': ('https://pint.readthedocs.io/en/stable/', None),

doc/source/reporting.rst

@@ -9,6 +9,20 @@ Reporting
    Python 3. The API and functionality may change without advance notice or a
    deprecation period in subsequent releases.
 
+Top-level methods and classes:
+
+.. autosummary::
+
+   configure
+   Reporter
+   Key
+
+Others:
+
+.. contents::
+   :local:
+   :depth: 3
+
 .. automethod:: ixmp.reporting.configure
 
 .. autoclass:: ixmp.reporting.Reporter
@@ -83,12 +97,43 @@ Reporting
          computations.
 
 
+.. autoclass:: ixmp.reporting.Key
+   :members:
+
+   Quantities in a :class:`Scenario` can be indexed by one or more dimensions.
+   For example, a parameter with three dimensions can be initialized with:
+
+   >>> scenario.init_par('foo', ['a', 'b', 'c'], ['apple', 'bird', 'car'])
+
+   Computations for this scenario might use the quantity ``foo`` in different
+   ways:
+
+   1. in its full resolution, i.e. indexed by a, b, and c;
+   2. aggregated (e.g. summed) over any one dimension, e.g. aggregated over c
+      and thus indexed by a and b;
+   3. aggregated over any two dimensions; etc.
+
+   A Key for (1) will hash, display, and evaluate as equal to ``'foo:a-b-c'``.
+   A Key for (2) corresponds to ``'foo:a-b'``, and so forth.
+
+   Keys may be generated concisely by defining a convenience method:
+
+   >>> def foo(dims):
+   >>>     return Key('foo', dims.split(''))
+   >>> foo('a b')
+   foo:a-b
+
+
 Computations
 ------------
 
 .. automodule:: ixmp.reporting.computations
    :members:
 
+   Unless otherwise specified, these methods accept and return
+   :class:`Quantity <ixmp.reporting.utils.Quantity>` objects for data
+   arguments/return values.
+
    Calculations:
 
    .. autosummary::
@@ -113,34 +158,8 @@ Computations
 Utilities
 ---------
 
-.. autoclass:: ixmp.reporting.utils.Key
-   :members:
-
-   Quantities in a :class:`Scenario` can be indexed by one or more dimensions.
-   For example, a parameter with three dimensions can be initialized with:
-
-   >>> scenario.init_par('foo', ['a', 'b', 'c'], ['apple', 'bird', 'car'])
-
-   Computations for this scenario might use the quantity ``foo`` in different
-   ways:
-
-   1. in its full resolution, i.e. indexed by a, b, and c;
-   2. aggregated (e.g. summed) over any one dimension, e.g. aggregated over c
-      and thus indexed by a and b;
-   3. aggregated over any two dimensions; etc.
-
-   A Key for (1) will hash, display, and evaluate as equal to ``'foo:a-b-c'``.
-   A Key for (2) corresponds to ``'foo:a-b'``, and so forth.
-
-   Keys may be generated concisely by defining a convenience method:
-
-   >>> def foo(dims):
-   >>>     return Key('foo', dims.split(''))
-   >>> foo('a b')
-   foo:a-b
-
-.. autoclass:: ixmp.reporting.utils.AttrSeries
+.. autoclass:: ixmp.reporting.attrseries.AttrSeries
 
 .. automodule:: ixmp.reporting.utils
    :members:
-   :exclude-members: AttrSeries, Key, combo_partition
+   :exclude-members: AttrSeries