From 2caf2b50f14a423bff3fd2073771b145c6d86cfc Mon Sep 17 00:00:00 2001 From: ChrisW09 <50968720+ChrisW09@users.noreply.github.com> Date: Fri, 16 Oct 2026 14:15:57 +0200 Subject: [PATCH] fix(placement): return distinct quantile locations on tied data QuantilePlacement returned the data quantiles verbatim, so on zero-inflated, top-coded or discrete features the RBF / ReLU / sigmoid / tanh feature maps got repeated centers and exactly duplicated output columns (4 of 8 distinct on a zero-inflated feature). The locations are now made distinct with the supplement_interior_knots helper the splines use: the endpoints (when included) are kept once and the rest is topped up with strictly interior quantile / uniform candidates. Untied data is unchanged, and a zero-range feature keeps its repeated location so the width holds. The feature-map docstrings and the placement guide describe the rule. Fixes #82 --- .../core_concepts/resolution_and_placement.md | 5 +- pretab/expansion/functional/rbf.py | 4 +- pretab/expansion/functional/relu.py | 4 +- pretab/expansion/functional/sigmoid.py | 4 +- pretab/expansion/functional/tanh.py | 4 +- pretab/placement/unsupervised.py | 25 ++++++++-- tests/placement/test_placement.py | 48 +++++++++++++++++++ 7 files changed, 84 insertions(+), 10 deletions(-) diff --git a/docs/core_concepts/resolution_and_placement.md b/docs/core_concepts/resolution_and_placement.md index 71a0b7e..a3d19e9 100644 --- a/docs/core_concepts/resolution_and_placement.md +++ b/docs/core_concepts/resolution_and_placement.md @@ -100,7 +100,10 @@ placement subsystem so no transformer re-implements it, and it is driven by two On tied data, such as a zero-inflated, top-coded or low-cardinality feature, several quantiles coincide or fall on the range boundary. The spline families keep their interior knots unique and strictly inside the observed range, topping a short set up with evenly spaced interior -points, so no basis function collapses to a point and leaves a dead column. +points, so no basis function collapses to a point and leaves a dead column. The feature maps +(RBF, ReLU, sigmoid, tanh) likewise keep their `"quantile"` centers distinct: the range endpoints +are kept once and the rest is topped up with strictly interior points, so no output column is +duplicated. ```{warning} The unsupervised and target-aware rows are mutually exclusive. Combining them, for example diff --git a/pretab/expansion/functional/rbf.py b/pretab/expansion/functional/rbf.py index bbf7b1b..a35e229 100644 --- a/pretab/expansion/functional/rbf.py +++ b/pretab/expansion/functional/rbf.py @@ -26,7 +26,9 @@ class RBFExpansionTransformer(BaseCenterExpansion): placement_strategy : {"cart", "lightgbm", "uniform", "quantile"}, optional Selector when `target_aware=True` (`"cart"` or `"lightgbm"`); spacing when `target_aware=False` (`"uniform"` or `"quantile"`). If left unset, resolves - to `"cart"` on the target-aware path and `"quantile"` otherwise. + to `"cart"` on the target-aware path and `"quantile"` otherwise. On tied + data the `"quantile"` centers stay distinct: the range endpoints are kept + once and repeated quantiles are replaced by strictly interior points. task : {"regression", "classification"}, default="regression" Task type for the target-aware selector used to place centers. diff --git a/pretab/expansion/functional/relu.py b/pretab/expansion/functional/relu.py index 6b2496a..7829a64 100644 --- a/pretab/expansion/functional/relu.py +++ b/pretab/expansion/functional/relu.py @@ -22,7 +22,9 @@ class ReLUExpansionTransformer(BaseCenterExpansion): placement_strategy : {"cart", "lightgbm", "uniform", "quantile"}, optional Selector when `target_aware=True` (`"cart"` or `"lightgbm"`); spacing when `target_aware=False` (`"uniform"` or `"quantile"`). If left unset, resolves - to `"cart"` on the target-aware path and `"quantile"` otherwise. + to `"cart"` on the target-aware path and `"quantile"` otherwise. On tied + data the `"quantile"` centers stay distinct: the range endpoints are kept + once and repeated quantiles are replaced by strictly interior points. task : {"regression", "classification"}, default="regression" Task type for the target-aware selector used to place centers. diff --git a/pretab/expansion/functional/sigmoid.py b/pretab/expansion/functional/sigmoid.py index f831320..31fe989 100644 --- a/pretab/expansion/functional/sigmoid.py +++ b/pretab/expansion/functional/sigmoid.py @@ -26,7 +26,9 @@ class SigmoidExpansionTransformer(BaseCenterExpansion): placement_strategy : {"cart", "lightgbm", "uniform", "quantile"}, optional Selector when `target_aware=True` (`"cart"` or `"lightgbm"`); spacing when `target_aware=False` (`"uniform"` or `"quantile"`). If left unset, resolves - to `"cart"` on the target-aware path and `"quantile"` otherwise. + to `"cart"` on the target-aware path and `"quantile"` otherwise. On tied + data the `"quantile"` centers stay distinct: the range endpoints are kept + once and repeated quantiles are replaced by strictly interior points. task : {"regression", "classification"}, default="regression" Task type for the target-aware selector used to place centers. diff --git a/pretab/expansion/functional/tanh.py b/pretab/expansion/functional/tanh.py index 0c7c941..5b4a195 100644 --- a/pretab/expansion/functional/tanh.py +++ b/pretab/expansion/functional/tanh.py @@ -25,7 +25,9 @@ class TanhExpansionTransformer(BaseCenterExpansion): placement_strategy : {"cart", "lightgbm", "uniform", "quantile"}, optional Selector when `target_aware=True` (`"cart"` or `"lightgbm"`); spacing when `target_aware=False` (`"uniform"` or `"quantile"`). If left unset, resolves - to `"cart"` on the target-aware path and `"quantile"` otherwise. + to `"cart"` on the target-aware path and `"quantile"` otherwise. On tied + data the `"quantile"` centers stay distinct: the range endpoints are kept + once and repeated quantiles are replaced by strictly interior points. task : {"regression", "classification"}, default="regression" Task type for the target-aware selector used to place centers. diff --git a/pretab/placement/unsupervised.py b/pretab/placement/unsupervised.py index 1ba3000..53c5fb6 100644 --- a/pretab/placement/unsupervised.py +++ b/pretab/placement/unsupervised.py @@ -24,7 +24,7 @@ import numpy as np -from ..core.knots import quantile_knots, spanning_knots, uniform_knots +from ..core.knots import quantile_knots, spanning_knots, supplement_interior_knots, uniform_knots from .base import BasePlacementStrategy, PlacementResult __all__ = ["QuantilePlacement", "UniformPlacement"] @@ -80,11 +80,26 @@ def _place(self, x: np.ndarray, n_units: int) -> np.ndarray: class QuantilePlacement(_UnsupervisedPlacement): - """Locations at evenly spaced data quantiles of a feature.""" + """Locations at evenly spaced data quantiles of a feature. + + On tied data (zero-inflated, top-coded or discrete features) several quantiles + coincide, which would repeat a location and duplicate an output column. The + locations are therefore made distinct: the endpoints (when included) are kept + once and the remaining locations are topped up with strictly interior + quantile / uniform candidates (see + :func:`pretab.core.knots.supplement_interior_knots`). A zero-range feature, + which has no interior, keeps its repeated location so the count still holds. + """ name: ClassVar[str] = "quantile" def _place(self, x: np.ndarray, n_units: int) -> np.ndarray: - if self.include_endpoints: - return spanning_knots(x, n_units, "quantile") - return quantile_knots(x, n_units) + if x.size == 0 or x.max() <= x.min(): + return spanning_knots(x, n_units, "quantile") if self.include_endpoints else quantile_knots(x, n_units) + if not self.include_endpoints: + return supplement_interior_knots(x, quantile_knots(x, n_units), n_units) + locations = spanning_knots(x, n_units, "quantile") + if n_units <= 2: + return locations + interior = supplement_interior_knots(x, locations[1:-1], n_units - 2) + return np.concatenate([[x.min()], interior, [x.max()]]) diff --git a/tests/placement/test_placement.py b/tests/placement/test_placement.py index d0dc463..9081cbf 100644 --- a/tests/placement/test_placement.py +++ b/tests/placement/test_placement.py @@ -215,3 +215,51 @@ def test_rbf_adapter_unsupervised_matches_inline(data): assert np.allclose(centers, np.percentile(x, np.linspace(0, 100, 6))) centers_u = RBFPlacementAdapter(target_aware=False, placement_strategy="uniform").get_centers(x, None, 6, 6) assert np.allclose(centers_u, np.linspace(x.min(), x.max(), 6)) + + +# --- quantile placement on tied data ------------------------------------------------ + + +def _tied_features(): + rng = np.random.default_rng(0) + return { + "zero-inflated": np.where(rng.random(1000) < 0.6, 0.0, rng.exponential(5.0, 1000)), + "discrete": rng.integers(0, 5, 1000).astype(float), + "top-coded": np.minimum(rng.uniform(0, 160, 1000), 100.0), + } + + +@pytest.mark.parametrize("name", ["zero-inflated", "discrete", "top-coded"]) +@pytest.mark.parametrize("include_endpoints", [True, False]) +def test_quantile_placement_returns_distinct_locations_on_tied_data(name, include_endpoints): + """Coinciding quantiles repeated feature-map centers, duplicating output columns.""" + x = _tied_features()[name] + locations = QuantilePlacement(8, include_endpoints=include_endpoints).fit(x).locations_ + assert len(locations) == 8 + assert len(np.unique(locations)) == 8 + if include_endpoints: + assert locations[0] == x.min() and locations[-1] == x.max() + else: + assert locations.min() > x.min() and locations.max() < x.max() + + +@pytest.mark.parametrize("name", ["zero-inflated", "discrete", "top-coded"]) +@pytest.mark.parametrize("method", ["RBF", "ReLU", "Sigmoid", "Tanh"]) +def test_quantile_feature_map_has_no_duplicate_columns_on_tied_data(method, name): + from pretab import transformers + + cls = getattr(transformers, f"{method}ExpansionTransformer") + X = _tied_features()[name].reshape(-1, 1) + out = cls(output_dim=8, placement_strategy="quantile").fit(X).transform(X) + assert len(np.unique(out.round(10), axis=1).T) == 8 + + +def test_preprocessor_rbf_has_no_duplicate_columns_on_tied_data(): + import pandas as pd + + from pretab import Preprocessor + + df = pd.DataFrame({"x": _tied_features()["zero-inflated"]}) + pre = Preprocessor(numerical_method="rbf", target_aware=False, placement_strategy="quantile").fit(df) + out = np.asarray(pre.transform(df), dtype=float) + assert len(np.unique(out.round(10), axis=1).T) == out.shape[1]