small refactoring for better api doc

.prettierignore

@@ -0,0 +1,3 @@
+# this file contains non standard yaml sections for options
+# that must not be corrected by prettier
+docs/api.md

data_disaggregation/__init__.py

@@ -1,15 +1,5 @@
 __version__ = "0.10.0"
 
-# isort: skip_file -> keep order to prevent circular import
-from .ext import transform_pandas
-from .base import transform
-from .classes import VT_Nominal, VT_Numeric, VT_NumericExt, VT_Ordinal
+from . import actions, types
 
-__all__ = [
-    "transform",
-    "transform_pandas",
-    "VT_Nominal",
-    "VT_Ordinal",
-    "VT_Numeric",
-    "VT_NumericExt",
-]
+__all__ = ["actions", "types"]

data_disaggregation/actions.py

@@ -0,0 +1,7 @@
+"""Functions to perform data transformations.
+"""
+
+from .base import transform
+from .ext import transform_pandas
+
+__all__ = ["transform", "transform_pandas"]

data_disaggregation/base.py

@@ -48,7 +48,7 @@
 
 from typing import Mapping, Tuple
 
-from .classes import F, T, V, VariableType, VT_NumericExt
+from .types import F, T, V, VT_NumericExt, _AbstractVariableType
 from .utils import (
     as_set,
     group_idx_first,
@@ -65,7 +65,7 @@
 
 
 def transform(
-    vtype: VariableType,
+    vtype: _AbstractVariableType,
     data: Mapping[F, V],
     weight_map: Mapping[Tuple[F, T], float],
     weights_from: Mapping[F, float] = None,

data_disaggregation/ext.py

@@ -6,7 +6,7 @@
 from pandas import DataFrame, Index, MultiIndex, Series
 
 from .base import transform
-from .classes import SCALAR_DIM_NAME, SCALAR_INDEX_KEY, VariableType
+from .types import SCALAR_DIM_NAME, SCALAR_INDEX_KEY, _AbstractVariableType
 from .utils import is_scalar
 
 IDX_SCALAR = MultiIndex.from_product([Index([SCALAR_INDEX_KEY], name=SCALAR_DIM_NAME)])
@@ -189,7 +189,7 @@ def validate_multiindex(item: Union[Index, Series, DataFrame]):
 
 
 def transform_pandas(
-    vtype: VariableType,
+    vtype: _AbstractVariableType,
     data: Union[DataFrame, Series, float],
     weights: Union[Index, Series, Tuple[Union[Index, Series]]],
     dim_in: Union[Index, Series] = None,

data_disaggregation/classes.py → data_disaggregation/types.py

@@ -1,4 +1,4 @@
-"""classes and types
+"""Type classes for data.
 """
 
 from abc import ABC
@@ -15,7 +15,7 @@
 SCALAR_INDEX_KEY = "__SCALAR__"
 
 
-class VariableType(ABC):
+class _AbstractVariableType(ABC):
     @classmethod
     def weighted_aggregate(cls, data):
         """aggregate data
@@ -33,7 +33,7 @@ def weighted_aggregate(cls, data):
         raise NotImplementedError()
 
 
-class VT_Nominal(VariableType):
+class VT_Nominal(_AbstractVariableType):
     """Type class for nominal (categorical) data.
 
     - Aggregation method: mode (most commonly used)
@@ -57,7 +57,7 @@ def weighted_aggregate(cls, data):
         return utils.weighted_median(data)
 
 
-class VT_Numeric(VariableType):
+class VT_Numeric(_AbstractVariableType):
     """Type class for numerical, intensive data.
 
     An intensive variable is one which does not scale with the system size.

data_disaggregation/utils.py

@@ -5,7 +5,7 @@
 
 from pandas import DataFrame, Index, Series
 
-from . import classes
+from . import types
 
 
 def group_sum(key_vals: Mapping, get_key: Callable = None) -> Mapping:
@@ -177,16 +177,16 @@ def as_mapping(x, default_val=1) -> Mapping:
     elif is_list(x):
         return dict((k, default_val) for k in x)
     elif is_scalar(x):
-        return {classes.SCALAR_INDEX_KEY: x}
+        return {types.SCALAR_INDEX_KEY: x}
     raise TypeError(x)
 
 
 def as_scalar(x):
     if as_scalar(x):
         return x
     elif is_mapping(x):
-        assert set(x.keys()) == set([classes.SCALAR_INDEX_KEY])
-        return x[classes.SCALAR_INDEX_KEY]
+        assert set(x.keys()) == set([types.SCALAR_INDEX_KEY])
+        return x[types.SCALAR_INDEX_KEY]
     raise TypeError(x)
 
 

docs/api.md

@@ -1,3 +1,9 @@
 # API
 
-::: data_disaggregation
+::: data_disaggregation.types
+
+::: data_disaggregation.actions
+    options:
+      members:
+        - transform
+        - transform_pandas

docs/index.ipynb

@@ -5,43 +5,35 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Theory\n",
-    "\n",
-    "Conceptually, aggregation/disaggregation operations are\n",
-    "\n",
-    "* start with *indexed data* (index can be multidimensional)\n",
-    "* use a *weight map* to map data to a new (multidimensional) index. Each key is a pair of (old index, new index).\n",
-    "* group values for each unique in the new index and use a *weighted aggregation*, which depends on the *variable type*, e.g.nominal, ordinal, numerical (intensive, extensive)\n"
+    "# Usage"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 1,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "from pandas import Series, Index, MultiIndex\n",
-    "from data_disaggregation import transform, create_weight_map,  VT_Numeric, VT_NumericExt"
+    "## Installation\n",
+    "\n",
+    "```bash\n",
+    "    pip install data-disaggregation\n",
+    "```"
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To make the creation of the *weight map* easier, we create it from pandas Series:\n",
-    "\n",
-    "* if we don't specify the output dimensions, we use dims(weights) - dims(input)\n",
-    "* we create a cross product of all the (unique) input and output dimemnsions\n",
-    "* we join the weight on all the applicaple dimensions (so the weights dimensions must be a nonempty subset of the other dimensions)\n"
+    "## Quickstart Examples"
    ]
   },
   {
-   "attachments": {},
-   "cell_type": "markdown",
+   "cell_type": "code",
+   "execution_count": 1,
    "metadata": {},
+   "outputs": [],
    "source": [
-    "Note: for aggregation of extensive data, the weight value doe not really matter, but it does for intensive data. For disaggregation, it's the other way round."
+    "from pandas import Series, Index, MultiIndex\n",
+    "import data_disaggregation as dd"
    ]
   },
   {

mkdocs.yml

@@ -35,6 +35,8 @@ plugins:
         python:
           options:
             show_source: false
+            show_root_heading: true
+            show_root_full_path: true
             docstring_style: numpy
   - search:
       lang: en

test/test.py

@@ -7,13 +7,6 @@
 from pandas import DataFrame, Index, MultiIndex, Series
 
 from data_disaggregation.base import transform
-from data_disaggregation.classes import (
-    SCALAR_INDEX_KEY,
-    VT_Nominal,
-    VT_Numeric,
-    VT_NumericExt,
-    VT_Ordinal,
-)
 from data_disaggregation.ext import (
     COL_FROM,
     COL_TO,
@@ -26,6 +19,13 @@
     remap_series_to_frame,
     transform_pandas,
 )
+from data_disaggregation.types import (
+    SCALAR_INDEX_KEY,
+    VT_Nominal,
+    VT_Numeric,
+    VT_NumericExt,
+    VT_Ordinal,
+)
 from data_disaggregation.utils import (
     as_mapping,
     group_idx_first,