xplainable-preprocessing 0.2.1__tar.gz → 0.2.2__tar.gz

{xplainable_preprocessing-0.2.1 → xplainable_preprocessing-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xplainable-preprocessing
-Version: 0.2.1
+Version: 0.2.2
 Summary: Shared preprocessing pipeline package for xplainable
 Requires-Python: >=3.9
 Requires-Dist: cloudpickle>=3.0

{xplainable_preprocessing-0.2.1 → xplainable_preprocessing-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xplainable-preprocessing"
-version = "0.2.1"
+version = "0.2.2"
 description = "Shared preprocessing pipeline package for xplainable"
 requires-python = ">=3.9"
 dependencies = [

xplainable_preprocessing-0.2.2/src/xplainable_preprocessing/transformers/groupby_agg.py

@@ -0,0 +1,143 @@
+"""GroupBy aggregation transformer for collapsing rows."""
+
+from __future__ import annotations
+
+import pandas as pd
+from sklearn.base import BaseEstimator, TransformerMixin
+
+
+class GroupByAggTransformer(BaseEstimator, TransformerMixin):
+    """Aggregate rows by grouping columns, collapsing many rows into one per group.
+
+    Supports standard pandas aggregation functions plus ``mode`` and ``nunique``.
+    Each aggregation entry maps a source column to one or more operations, with
+    optional output column renaming.
+
+    Parameters
+    ----------
+    group_by : list[str]
+        Columns to group by. These become the index of the result and are
+        always retained in the output.
+    aggregations : dict
+        Mapping of ``source_column`` to aggregation specification(s).
+
+        Each value can be:
+
+        - A string: a single function name (e.g. ``"sum"``, ``"mean"``).
+          The output column keeps the source name.
+        - A dict with ``func`` and optional ``output``:
+          ``{"func": "sum", "output": "total_revenue"}``.
+        - A list of the above, producing multiple output columns from one
+          source.
+
+        Supported functions: ``sum``, ``mean``, ``median``, ``min``, ``max``,
+        ``std``, ``count``, ``first``, ``last``, ``nunique``, ``mode``.
+
+    Examples
+    --------
+    >>> spec_params = {
+    ...     "group_by": ["customer_id"],
+    ...     "aggregations": {
+    ...         "country": "first",
+    ...         "order_id": {"func": "count", "output": "orders_count"},
+    ...         "revenue": [
+    ...             {"func": "sum", "output": "total_spent"},
+    ...             {"func": "mean", "output": "avg_order_value"},
+    ...         ],
+    ...         "product_id": {"func": "nunique", "output": "unique_products"},
+    ...         "category": {"func": "mode", "output": "primary_category"},
+    ...     },
+    ... }
+    """
+
+    FUNCTIONS = {
+        "sum", "mean", "median", "min", "max", "std",
+        "count", "first", "last", "nunique", "mode",
+    }
+
+    def __init__(
+        self,
+        group_by: list[str] | None = None,
+        aggregations: dict | None = None,
+    ):
+        self.group_by = group_by or []
+        self.aggregations = aggregations or {}
+
+    def fit(self, X: pd.DataFrame, y=None):
+        # Validate all requested functions
+        for col, specs in self._iter_specs():
+            for func, _ in specs:
+                if func not in self.FUNCTIONS:
+                    raise ValueError(
+                        f"Column '{col}': unknown function '{func}'. "
+                        f"Available: {sorted(self.FUNCTIONS)}"
+                    )
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        if not self.group_by:
+            raise ValueError("group_by must be specified")
+        if not self.aggregations:
+            raise ValueError("aggregations must be specified")
+
+        grouped = X.groupby(self.group_by, sort=False)
+
+        result_parts: dict[str, pd.Series] = {}
+
+        for col, specs in self._iter_specs():
+            if col not in X.columns:
+                continue
+            for func, output_name in specs:
+                result_parts[output_name] = self._apply_func(grouped, col, func)
+
+        result = pd.DataFrame(result_parts)
+
+        # Restore group_by columns from the index
+        for i, col in enumerate(self.group_by):
+            if len(self.group_by) == 1:
+                result.insert(i, col, result.index)
+            else:
+                result.insert(i, col, result.index.get_level_values(i))
+
+        return result.reset_index(drop=True)
+
+    def _iter_specs(self):
+        """Yield (source_column, [(func, output_name), ...]) tuples."""
+        for col, spec in self.aggregations.items():
+            yield col, self._normalise(col, spec)
+
+    @staticmethod
+    def _normalise(col: str, spec) -> list[tuple[str, str]]:
+        """Normalise the various spec formats into [(func, output), ...]."""
+        if isinstance(spec, str):
+            return [(spec, col)]
+
+        if isinstance(spec, dict):
+            func = spec["func"]
+            output = spec.get("output", col)
+            return [(func, output)]
+
+        if isinstance(spec, list):
+            result = []
+            for entry in spec:
+                if isinstance(entry, str):
+                    result.append((entry, col))
+                elif isinstance(entry, dict):
+                    func = entry["func"]
+                    output = entry.get("output", col)
+                    result.append((func, output))
+            return result
+
+        raise ValueError(
+            f"Column '{col}': spec must be a string, dict, or list, "
+            f"got {type(spec).__name__}"
+        )
+
+    @staticmethod
+    def _apply_func(grouped, col: str, func: str) -> pd.Series:
+        """Apply a single aggregation function to a grouped column."""
+        if func == "mode":
+            return grouped[col].agg(lambda x: x.mode().iloc[0] if len(x.mode()) > 0 else None)
+        if func == "nunique":
+            return grouped[col].nunique()
+        return grouped[col].agg(func)

{xplainable_preprocessing-0.2.1 → xplainable_preprocessing-0.2.2}/tests/test_transformers/test_all_transformers.py

@@ -9,6 +9,7 @@ from xplainable_preprocessing.transformers.datetime_extract import DateTimeExtra
 from xplainable_preprocessing.transformers.drop_columns import DropColumnsTransformer
 from xplainable_preprocessing.transformers.fill_missing import FillMissingTransformer
 from xplainable_preprocessing.transformers.grouped_lag import GroupedLagTransformer
+from xplainable_preprocessing.transformers.groupby_agg import GroupByAggTransformer
 from xplainable_preprocessing.transformers.rename_columns import RenameColumnsTransformer
 from xplainable_preprocessing.transformers.rolling_agg import RollingAggTransformer
 from xplainable_preprocessing.transformers.text_clean import TextCleanTransformer
@@ -226,3 +227,128 @@ class TestRollingAggTransformer:
         t = RollingAggTransformer(columns=["v"], operation="invalid")
         with pytest.raises(ValueError, match="Unknown operation"):
             t.fit(pd.DataFrame({"v": [1]}))
+
+
+class TestGroupByAggTransformer:
+    @pytest.fixture
+    def orders_df(self):
+        return pd.DataFrame({
+            "customer_id": [1, 1, 1, 2, 2, 3],
+            "country": ["US", "US", "US", "UK", "UK", "CA"],
+            "revenue": [100.0, 200.0, 150.0, 300.0, 250.0, 50.0],
+            "quantity": [2, 3, 1, 4, 2, 1],
+            "product_id": [10, 20, 10, 30, 30, 40],
+            "category": ["A", "B", "A", "C", "C", "A"],
+            "returned": [0, 1, 0, 0, 0, 1],
+        })
+
+    def test_basic_string_agg(self, orders_df):
+        t = GroupByAggTransformer(
+            group_by=["customer_id"],
+            aggregations={"country": "first"},
+        )
+        result = t.fit_transform(orders_df)
+        assert len(result) == 3
+        assert "customer_id" in result.columns
+        assert "country" in result.columns
+        assert result.loc[result["customer_id"] == 1, "country"].iloc[0] == "US"
+
+    def test_dict_with_rename(self, orders_df):
+        t = GroupByAggTransformer(
+            group_by=["customer_id"],
+            aggregations={
+                "revenue": {"func": "sum", "output": "total_spent"},
+            },
+        )
+        result = t.fit_transform(orders_df)
+        assert "total_spent" in result.columns
+        assert "revenue" not in result.columns
+        assert result.loc[result["customer_id"] == 1, "total_spent"].iloc[0] == 450.0
+
+    def test_list_multiple_aggs(self, orders_df):
+        t = GroupByAggTransformer(
+            group_by=["customer_id"],
+            aggregations={
+                "revenue": [
+                    {"func": "sum", "output": "total_revenue"},
+                    {"func": "mean", "output": "avg_revenue"},
+                ],
+            },
+        )
+        result = t.fit_transform(orders_df)
+        assert "total_revenue" in result.columns
+        assert "avg_revenue" in result.columns
+        assert result.loc[result["customer_id"] == 1, "total_revenue"].iloc[0] == 450.0
+        assert result.loc[result["customer_id"] == 1, "avg_revenue"].iloc[0] == 150.0
+
+    def test_nunique(self, orders_df):
+        t = GroupByAggTransformer(
+            group_by=["customer_id"],
+            aggregations={
+                "product_id": {"func": "nunique", "output": "unique_products"},
+            },
+        )
+        result = t.fit_transform(orders_df)
+        assert result.loc[result["customer_id"] == 1, "unique_products"].iloc[0] == 2
+        assert result.loc[result["customer_id"] == 2, "unique_products"].iloc[0] == 1
+
+    def test_mode(self, orders_df):
+        t = GroupByAggTransformer(
+            group_by=["customer_id"],
+            aggregations={
+                "category": {"func": "mode", "output": "primary_category"},
+            },
+        )
+        result = t.fit_transform(orders_df)
+        assert result.loc[result["customer_id"] == 1, "primary_category"].iloc[0] == "A"
+        assert result.loc[result["customer_id"] == 2, "primary_category"].iloc[0] == "C"
+
+    def test_count(self, orders_df):
+        t = GroupByAggTransformer(
+            group_by=["customer_id"],
+            aggregations={
+                "revenue": {"func": "count", "output": "orders_count"},
+            },
+        )
+        result = t.fit_transform(orders_df)
+        assert result.loc[result["customer_id"] == 1, "orders_count"].iloc[0] == 3
+        assert result.loc[result["customer_id"] == 3, "orders_count"].iloc[0] == 1
+
+    def test_invalid_function(self, orders_df):
+        t = GroupByAggTransformer(
+            group_by=["customer_id"],
+            aggregations={"revenue": "bogus"},
+        )
+        with pytest.raises(ValueError, match="unknown function"):
+            t.fit(orders_df)
+
+    def test_empty_group_by_raises(self, orders_df):
+        t = GroupByAggTransformer(
+            group_by=[],
+            aggregations={"revenue": "sum"},
+        )
+        t.fit(orders_df)
+        with pytest.raises(ValueError, match="group_by must be specified"):
+            t.transform(orders_df)
+
+    def test_combined_spec(self, orders_df):
+        """Full integration: multiple agg types in one spec."""
+        t = GroupByAggTransformer(
+            group_by=["customer_id"],
+            aggregations={
+                "country": "first",
+                "revenue": [
+                    {"func": "sum", "output": "total_spent"},
+                    {"func": "mean", "output": "avg_order_value"},
+                ],
+                "product_id": {"func": "nunique", "output": "unique_products"},
+                "category": {"func": "mode", "output": "top_category"},
+                "returned": {"func": "sum", "output": "return_count"},
+            },
+        )
+        result = t.fit_transform(orders_df)
+        assert len(result) == 3
+        assert set(result.columns) == {
+            "customer_id", "country", "total_spent", "avg_order_value",
+            "unique_products", "top_category", "return_count",
+        }