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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xplainable-preprocessing
-Version: 0.2.1
+Version: 0.2.3
 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.3}/pyproject.toml

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

{xplainable_preprocessing-0.2.1 → xplainable_preprocessing-0.2.3}/src/xplainable_preprocessing/compiler.py

@@ -3,6 +3,9 @@
 from __future__ import annotations
 
 import inspect
+import logging
+
+logger = logging.getLogger(__name__)
 
 from xplainable_preprocessing.pipeline import DataFrameColumnTransformer, DataFramePipeline
 from xplainable_preprocessing.registry import REGISTRY
@@ -11,14 +14,29 @@ from xplainable_preprocessing.schema import PipelineSpec
 
 
 def _coerce_params(cls, params: dict) -> dict:
-    """Convert list params to tuples where the constructor expects them.
+    """Adapt spec params to the constructor's signature.
 
-    JSON has no tuple type, so specs always contain lists. sklearn transformers
-    like MinMaxScaler expect tuples for params like feature_range.
+    - Converts list params to tuples where the constructor expects them
+      (JSON has no tuple type, so specs always contain lists; sklearn
+      transformers like MinMaxScaler expect tuples for feature_range).
+    - Drops params the constructor does not accept, with a warning. Specs
+      may be generated in an env with a newer sklearn than the one
+      compiling them (2026-07: sklearn 1.7 emitted
+      KBinsDiscretizer(quantile_method=...), which 1.6 rejects).
     """
     sig = inspect.signature(cls.__init__)
+    accepts_kwargs = any(
+        p.kind is inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+    )
     coerced = {}
     for key, value in params.items():
+        if key not in sig.parameters and not accepts_kwargs:
+            logger.warning(
+                "%s does not accept param '%s' in this environment "
+                "(likely a library-version mismatch with the spec's "
+                "generator); dropping it", cls.__name__, key
+            )
+            continue
         if isinstance(value, list) and key in sig.parameters:
             param = sig.parameters[key]
             if param.default is not inspect.Parameter.empty and isinstance(param.default, tuple):
@@ -48,6 +66,8 @@ def compile_spec(spec: PipelineSpec) -> DataFramePipeline:
     steps = []
 
     for step in spec.steps:
+        wrap = bool(step.columns)
+
         if step.type == "custom":
             transformer = compile_custom(step.params)
         else:
@@ -58,9 +78,18 @@ def compile_spec(spec: PipelineSpec) -> DataFramePipeline:
                 )
             cls = REGISTRY[step.type]
             params = _coerce_params(cls, step.params)
+
+            # Column-aware transformers (constructor takes `columns`) must
+            # receive the step-level columns directly and must NOT be wrapped:
+            # DataFrameColumnTransformer feeds them only their declared columns
+            # and re-attaches the result, which turns e.g. a drop into a no-op.
+            if step.columns and "columns" in inspect.signature(cls.__init__).parameters:
+                params.setdefault("columns", step.columns)
+                wrap = False
+
             transformer = cls(**params)
 
-        if step.columns:
+        if wrap:
             transformer = DataFrameColumnTransformer(transformer, step.columns)
 
         steps.append((step.id, transformer))

xplainable_preprocessing-0.2.3/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.3}/tests/test_compiler.py

@@ -34,6 +34,40 @@ class TestCompileSpec:
         name, transformer = pipeline.steps[0]
         assert not isinstance(transformer, DataFrameColumnTransformer)
 
+    def test_step_level_columns_on_drop_actually_drops(self):
+        # Specs commonly declare columns at the step level with empty params.
+        # DropColumnsTransformer is column-aware: wrapping it in
+        # DataFrameColumnTransformer turns the drop into a no-op (the wrapper
+        # re-attaches the "transformed" — i.e. untouched — columns).
+        spec = PipelineSpec(steps=[
+            StepSpec(id="drop", type="DropColumnsTransformer",
+                     columns=["id", "count"], params={}),
+        ])
+        pipeline = compile_spec(spec)
+        df = pd.DataFrame({"id": [1, 2], "count": [3, 4], "value": [5.0, 6.0]})
+        result = pipeline.fit_transform(df)
+        assert list(result.columns) == ["value"]
+
+    def test_step_level_columns_injected_into_column_aware_transformer(self):
+        spec = PipelineSpec(steps=[
+            StepSpec(id="drop", type="DropColumnsTransformer",
+                     columns=["id"], params={}),
+        ])
+        pipeline = compile_spec(spec)
+        _, transformer = pipeline.steps[0]
+        assert not isinstance(transformer, DataFrameColumnTransformer)
+        assert transformer.columns == ["id"]
+
+    def test_params_columns_take_precedence_over_step_columns(self):
+        spec = PipelineSpec(steps=[
+            StepSpec(id="drop", type="DropColumnsTransformer",
+                     columns=["id"], params={"columns": ["count"]}),
+        ])
+        pipeline = compile_spec(spec)
+        _, transformer = pipeline.steps[0]
+        assert not isinstance(transformer, DataFrameColumnTransformer)
+        assert transformer.columns == ["count"]
+
     def test_unknown_type_raises(self):
         spec = PipelineSpec(steps=[
             StepSpec(id="bad", type="FakeTransformer"),
@@ -118,3 +152,51 @@ class TestCompileSpec:
         assert "id" not in result.columns
         assert "value" in result.columns
         assert not result["value"].isna().any()
+
+
+class TestUnsupportedParamFiltering:
+    """Specs may be generated in an env with a newer sklearn than the one
+    compiling them (2026-07: autotrain on sklearn 1.7 emitted
+    KBinsDiscretizer(quantile_method=...), which the API's sklearn 1.6
+    constructor rejects). Unknown constructor params must be dropped with a
+    warning instead of crashing compilation."""
+
+    def test_unknown_param_is_dropped_with_warning(self, caplog):
+        import logging
+
+        spec = PipelineSpec(steps=[
+            StepSpec(
+                id="bin",
+                type="KBinsDiscretizer",
+                columns=["age"],
+                params={
+                    "n_bins": 4,
+                    "encode": "ordinal",
+                    "strategy": "quantile",
+                    "definitely_not_a_real_sklearn_param": "x",
+                },
+            ),
+        ])
+        with caplog.at_level(logging.WARNING):
+            pipeline = compile_spec(spec)
+
+        _, transformer = pipeline.steps[0]
+        inner = transformer.transformer
+        assert inner.n_bins == 4
+        assert not hasattr(inner, "definitely_not_a_real_sklearn_param")
+        assert any("definitely_not_a_real_sklearn_param" in r.message
+                   for r in caplog.records)
+
+    def test_supported_params_pass_through_unchanged(self):
+        spec = PipelineSpec(steps=[
+            StepSpec(
+                id="bin",
+                type="KBinsDiscretizer",
+                columns=["age"],
+                params={"n_bins": 3, "encode": "ordinal"},
+            ),
+        ])
+        pipeline = compile_spec(spec)
+        _, transformer = pipeline.steps[0]
+        assert transformer.transformer.n_bins == 3
+        assert transformer.transformer.encode == "ordinal"

{xplainable_preprocessing-0.2.1 → xplainable_preprocessing-0.2.3}/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",
+        }