Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/core_concepts/resolution_and_placement.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion pretab/expansion/functional/rbf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion pretab/expansion/functional/relu.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion pretab/expansion/functional/sigmoid.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion pretab/expansion/functional/tanh.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
25 changes: 20 additions & 5 deletions pretab/placement/unsupervised.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down Expand Up @@ -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()]])
48 changes: 48 additions & 0 deletions tests/placement/test_placement.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Loading