From e6d43eb0733d16987435364f269d79740e9397c1 Mon Sep 17 00:00:00 2001 From: ChrisW09 <50968720+ChrisW09@users.noreply.github.com> Date: Fri, 16 Oct 2026 14:37:43 +0200 Subject: [PATCH] fix(splines): search the resolved knot window in target-aware placement The B/M/I, cubic-regression and natural-cubic splines asked their target-aware selector for a fixed 3-15 basis-function window and then reduced the result to the needed count with select_knots, which keeps evenly spaced indices of the sorted list. That positional trim routinely discarded the split where the target changes, and capped adaptive widths at 15 (14 / 12 for the cubic families); a window lying entirely above the cap collapsed to min_output_dim. SplinePlacementAdapter.get_knot_locations now accepts a per-call min_knots / max_knots window, and the transformers pass the window resolved from output_dim or [min_output_dim, max_output_dim], so the selector's importance ranking keeps the most informative splits. The spline and adapter docstrings describe the window, and the adaptive tutorial output is updated (both signals now reach the [5, 20] bound). Fixes #69 --- docs/tutorials/adaptive_resolution.md | 13 +++--- pretab/expansion/spline/base.py | 10 ++++- pretab/expansion/spline/cubic_regression.py | 3 ++ pretab/expansion/spline/mixins.py | 11 +++-- pretab/expansion/spline/natural_cubic.py | 3 ++ pretab/placement/adapters.py | 43 ++++++++++++++---- .../spline/test_spline_expansions.py | 45 +++++++++++++++++++ .../test_spline_placement_adapter.py | 15 +++++++ 8 files changed, 125 insertions(+), 18 deletions(-) diff --git a/docs/tutorials/adaptive_resolution.md b/docs/tutorials/adaptive_resolution.md index 9159e01..6f7870a 100644 --- a/docs/tutorials/adaptive_resolution.md +++ b/docs/tutorials/adaptive_resolution.md @@ -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 diff --git a/pretab/expansion/spline/base.py b/pretab/expansion/spline/base.py index ab365bf..ac7401a 100644 --- a/pretab/expansion/spline/base.py +++ b/pretab/expansion/spline/base.py @@ -84,6 +84,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. @@ -248,7 +251,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) diff --git a/pretab/expansion/spline/cubic_regression.py b/pretab/expansion/spline/cubic_regression.py index 392a99d..bc5cb1b 100644 --- a/pretab/expansion/spline/cubic_regression.py +++ b/pretab/expansion/spline/cubic_regression.py @@ -62,6 +62,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. diff --git a/pretab/expansion/spline/mixins.py b/pretab/expansion/spline/mixins.py index b325181..3fdaec6 100644 --- a/pretab/expansion/spline/mixins.py +++ b/pretab/expansion/spline/mixins.py @@ -112,13 +112,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 generate_internal_knots(x, n_interior, strategy) diff --git a/pretab/expansion/spline/natural_cubic.py b/pretab/expansion/spline/natural_cubic.py index 21c3f45..7519d33 100644 --- a/pretab/expansion/spline/natural_cubic.py +++ b/pretab/expansion/spline/natural_cubic.py @@ -64,6 +64,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. diff --git a/pretab/placement/adapters.py b/pretab/placement/adapters.py index 15a0e65..a44e4db 100644 --- a/pretab/placement/adapters.py +++ b/pretab/placement/adapters.py @@ -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 @@ -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__( @@ -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, ) diff --git a/tests/expansion/spline/test_spline_expansions.py b/tests/expansion/spline/test_spline_expansions.py index a55d9ca..f80d9d0 100644 --- a/tests/expansion/spline/test_spline_expansions.py +++ b/tests/expansion/spline/test_spline_expansions.py @@ -3,8 +3,10 @@ from pretab.transformers import ( BSplineTransformer, + CubicRegressionSplineTransformer, ISplineTransformer, MSplineTransformer, + NaturalCubicSplineTransformer, ) @@ -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 diff --git a/tests/placement/test_spline_placement_adapter.py b/tests/placement/test_spline_placement_adapter.py index 5d24fa1..52a1350 100644 --- a/tests/placement/test_spline_placement_adapter.py +++ b/tests/placement/test_spline_placement_adapter.py @@ -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