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
13 changes: 7 additions & 6 deletions docs/tutorials/adaptive_resolution.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,15 +57,16 @@ for name, y in [("simple", simple), ("wiggly", wiggly)]:
```

```text
simple -> selected width 15
wiggly -> selected width 15
simple -> selected width 20
wiggly -> selected width 20
```

Both widths land inside the `[5, 20]` window without you having to guess a number up front.
The two happen to match here because the underlying CART selector's split count is governed
more by its own tree depth and minimum-samples settings than by how wiggly the signal looks;
with noisier or smaller data, or a narrower window, the two searches can land on different
widths. The bound is what you control directly, the exact count inside it is data-driven.
Here both reach the upper bound: with 3000 samples the CART selector finds more informative
splits than the window admits, so it keeps the most informative ones. Its split count is governed
more by its own tree depth and minimum-samples settings than by how wiggly the signal looks; with
smaller data or a wider window the two searches can land on different widths. The bound is what
you control directly, the exact count inside it is data-driven.

```{note}
Fitting a target-aware transformer directly like this, outside a `Pipeline`, normally emits a
Expand Down
10 changes: 9 additions & 1 deletion pretab/expansion/spline/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,9 @@ class BaseSplineTransformer(BasePreTabTransformer):
If True, the per-feature output dimension may vary within
``[min_output_dim, max_output_dim]``. When both bounds are set,
``output_dim`` is ignored entirely.
A target-aware selector searches exactly this window (the width set by
``output_dim`` when ``adaptive=False``) and keeps its most informative
splits.

min_output_dim : int or None, default=None
Lower bound on the per-feature output dimension used in adaptive mode.
Expand Down Expand Up @@ -249,7 +252,12 @@ def _column_knots(
)
internal_knots = self._adjust_internal_knots(x_valid, np.asarray(self.knot_locations), min_knots, max_knots)
elif selector is not None:
selected = selector.get_knot_locations(x_valid.reshape(-1, 1), y_valid, task=self.task)
# Search exactly the window this feature needs, so the selector's own
# importance ranking picks the knots instead of a positional trim.
min_knots = min(min_knots, max_knots)
selected = selector.get_knot_locations(
x_valid.reshape(-1, 1), y_valid, task=self.task, min_knots=min_knots, max_knots=max_knots
)
internal_knots = self._adjust_internal_knots(x_valid, np.asarray(selected), min_knots, max_knots)
else:
n_internal = self._basis_to_knots(n_basis)
Expand Down
3 changes: 3 additions & 0 deletions pretab/expansion/spline/cubic_regression.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,9 @@ class CubicRegressionSplineTransformer(SplineBasisMixin, TransformerMixin, BaseE
If True (with ``target_aware=True``), the per-feature output dimension may
vary within ``[min_output_dim, max_output_dim]`` instead of being fixed to
``output_dim``. When both bounds are set, ``output_dim`` is ignored entirely.
A target-aware selector searches exactly this window (the width set by
``output_dim`` when ``adaptive=False``) and keeps its most informative
splits.

min_output_dim : int or None, default=None
Lower bound on the per-feature output dimension in adaptive mode.
Expand Down
11 changes: 8 additions & 3 deletions pretab/expansion/spline/mixins.py
Original file line number Diff line number Diff line change
Expand Up @@ -119,13 +119,18 @@ def _place_interior_knots(self, x, y, n_interior, strategy, selector, task, min_
if selector is not None:
if y is None:
raise IncompatibleParamsError("A knot selector requires y during fit for target-aware knot placement.")
selected = np.asarray(selector.get_knot_locations(x.reshape(-1, 1), y, task=task), dtype=float)
x_min, x_max = x.min(), x.max()
selected = np.unique(selected[(selected > x_min) & (selected < x_max)])
if min_interior is None and max_interior is None:
# Fixed (non-adaptive) selector path: force exactly ``n_interior``
# interior knots so the width stays ``output_dim``.
min_interior = max_interior = n_interior
# Search exactly this window, so the selector's own importance ranking
# picks the knots instead of a positional trim afterwards.
selected = selector.get_knot_locations(
x.reshape(-1, 1), y, task=task, min_knots=min_interior, max_knots=max_interior
)
selected = np.asarray(selected, dtype=float)
x_min, x_max = x.min(), x.max()
selected = np.unique(selected[(selected > x_min) & (selected < x_max)])
selected = self._clamp_interior_knots(x, selected, min_interior, max_interior, strategy)
return selected
return supplement_interior_knots(x, generate_internal_knots(x, n_interior, strategy), n_interior)
Expand Down
3 changes: 3 additions & 0 deletions pretab/expansion/spline/natural_cubic.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,9 @@ class NaturalCubicSplineTransformer(SplineBasisMixin, TransformerMixin, BaseEsti
If True (with ``target_aware=True``), the per-feature output dimension may
vary within ``[min_output_dim, max_output_dim]`` instead of being fixed to
``output_dim``. When both bounds are set, ``output_dim`` is ignored entirely.
A target-aware selector searches exactly this window (the width set by
``output_dim`` when ``adaptive=False``) and keeps its most informative
splits.

min_output_dim : int or None, default=None
Lower bound on the per-feature output dimension in adaptive mode.
Expand Down
43 changes: 35 additions & 8 deletions pretab/placement/adapters.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,9 @@
"SplinePlacementAdapter",
]

# The spline knot selectors have always searched a fixed basis-function window,
# independent of the requested output_dim (the transformer clamps to output_dim
# afterwards). These reproduce ``CART/LightGBMKnotSelector``'s defaults.
# Default basis-function search window of a standalone adapter, reproducing the
# historical ``CART/LightGBMKnotSelector`` defaults. The spline transformers do
# not rely on it: they pass their own resolved knot window per call.
_SPLINE_MIN_BASIS = 3
_SPLINE_MAX_BASIS = 15
# Historical default seed used by the spline knot selectors when random_state is
Expand Down Expand Up @@ -67,8 +67,10 @@ class SplinePlacementAdapter:
Random state forwarded to the strategy. When unset the historical spline
default seed (51) is used.
min_basis_functions, max_basis_functions : int
Basis-function search window (defaults 3 and 15, matching the old
selectors).
Default basis-function search window (defaults 3 and 15, matching the old
selectors). It applies only when :meth:`get_knot_locations` is called
without ``min_knots`` / ``max_knots``; the spline transformers always pass
their own window.
"""

def __init__(
Expand Down Expand Up @@ -101,14 +103,39 @@ def get_knot_locations(
X: np.ndarray,
y: np.ndarray | None = None,
task: Task | None = "regression",
*,
min_knots: int | None = None,
max_knots: int | None = None,
) -> np.ndarray:
"""Return sorted internal knot locations for a single feature."""
"""Return sorted internal knot locations for a single feature.

Parameters
----------
X : ndarray of shape (n_samples, 1)
Values of the feature.
y : ndarray of shape (n_samples,) or None, default=None
Target the selector places the knots against.
task : {"regression", "classification"} or None, default="regression"
Prediction task passed to the selector.
min_knots, max_knots : int or None, default=None
Interior-knot window for this call, overriding the adapter's default
window. The spline transformers pass the window resolved from their
own ``output_dim`` (or adaptive bounds), so that the selector's
importance ranking -- not a positional down-sample afterwards --
decides which knots are kept.

Returns
-------
ndarray
Sorted internal knot locations, usually ``min_knots`` to
``max_knots`` of them.
"""
seed = self.random_state if self.random_state is not None else _SPLINE_DEFAULT_SEED
strategy = create_placement_strategy(
target_aware=True,
placement_strategy=self.placement_strategy,
min_count=self.min_knots,
max_count=self.max_knots,
min_count=self.min_knots if min_knots is None else min_knots,
max_count=self.max_knots if max_knots is None else max_knots,
task=task,
random_state=seed,
)
Expand Down
45 changes: 45 additions & 0 deletions tests/expansion/spline/test_spline_expansions.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,10 @@

from pretab.transformers import (
BSplineTransformer,
CubicRegressionSplineTransformer,
ISplineTransformer,
MSplineTransformer,
NaturalCubicSplineTransformer,
)


Expand Down Expand Up @@ -154,3 +156,46 @@ def test_spline_penalty_matrix_symmetric(data):
P = transformer.get_penalty_matrix()
assert P.shape[0] == P.shape[1]
assert np.allclose(P, P.T, atol=1e-9)


# --- target-aware splines search their own knot window (issue #69) ------------


def _step_data(seed=1):
rng = np.random.default_rng(seed)
x = rng.uniform(0, 10, 1000)
y = np.where(x > 5.0, 1.0, 0.0) + 0.3 * rng.normal(size=1000)
return x.reshape(-1, 1), y


@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer])
@pytest.mark.parametrize("output_dim", [5, 6])
def test_target_aware_bmi_spline_keeps_the_dominant_split(cls, output_dim):
"""Regression guard for issue #69: selector knots were trimmed by position, so
the split where the target changes was routinely discarded."""
X, y = _step_data()
transformer = cls(output_dim=output_dim, target_aware=True, placement_strategy="cart").fit(X, y)
interior = transformer.knots_[0][transformer.degree + 1 : -(transformer.degree + 1)]
assert len(interior) == output_dim - transformer.degree - 1
assert np.abs(interior - 5.0).min() < 0.1, interior


@pytest.mark.parametrize("cls", [CubicRegressionSplineTransformer, NaturalCubicSplineTransformer])
def test_target_aware_cubic_families_keep_the_dominant_split(cls):
X, y = _step_data()
knots = cls(output_dim=5, target_aware=True, placement_strategy="cart").fit(X, y).knots_[0]
assert np.abs(knots - 5.0).min() < 0.1, knots


@pytest.mark.parametrize("cls", [BSplineTransformer, CubicRegressionSplineTransformer, NaturalCubicSplineTransformer])
@pytest.mark.parametrize(("low", "high"), [(5, 40), (20, 50)])
def test_adaptive_spline_width_is_not_capped_at_the_legacy_window(cls, low, high):
"""The fixed 3-15 selector window capped the width at 15 (14 / 12 for the cubic
families), and a window entirely above it collapsed to ``min_output_dim``."""
rng = np.random.default_rng(0)
x = rng.uniform(0, 10, 3000)
y = np.sin(2 * x) * 3 + rng.normal(0, 0.3, 3000)
transformer = cls(
adaptive=True, min_output_dim=low, max_output_dim=high, target_aware=True, placement_strategy="cart"
).fit(x.reshape(-1, 1), y)
assert max(15, low) < transformer.total_output_dim_ <= high
15 changes: 15 additions & 0 deletions tests/placement/test_spline_placement_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,3 +99,18 @@ def test_lightgbm_adapter_reproducible(data):
a = SplinePlacementAdapter(placement_strategy="lightgbm", degree=3).get_knot_locations(X, y)
b = SplinePlacementAdapter(placement_strategy="lightgbm", degree=3).get_knot_locations(X, y)
np.testing.assert_array_equal(a, b)


def _step_data(seed=1):
rng = np.random.default_rng(seed)
x = rng.uniform(0, 10, 1000)
y = np.where(x > 5.0, 1.0, 0.0) + 0.3 * rng.normal(size=1000)
return x.reshape(-1, 1), y


def test_get_knot_locations_window_override():
X, y = _step_data()
adapter = SplinePlacementAdapter(placement_strategy="cart", degree=3)
knots = adapter.get_knot_locations(X, y, min_knots=1, max_knots=1)
assert len(knots) == 1
assert abs(knots[0] - 5.0) < 0.1
Loading