From f6e86d84ce83f2ede246ddb7857d9479a201faa3 Mon Sep 17 00:00:00 2001 From: ChrisW09 <50968720+ChrisW09@users.noreply.github.com> Date: Fri, 16 Oct 2026 14:25:41 +0200 Subject: [PATCH] fix(splines): honour explicit knot_locations regardless of output_dim BaseSplineTransformer documented that output_dim is ignored when knot_locations is given, but it still checked the knot count against output_dim - degree - 1 (raising for any other count), trimmed the knots to the adaptive window, and clipped out-of-range knots onto the boundary, which silently replaced them by degenerate boundary knots. Explicit knots now fix the width (len(knot_locations) + degree + 1 basis functions per feature) and bypass output_dim and the adaptive bounds. Repeated knots are merged, knots on or outside a feature's fitted range are dropped with a DataWarning, and knot_locations must be a 1-D sequence of finite numbers (InvalidParamError otherwise). Fixes #81 --- docs/representations/spline_expansions.md | 6 +- pretab/expansion/spline/base.py | 73 ++++++++++++++----- .../spline/test_spline_expansions.py | 56 ++++++++++++++ 3 files changed, 115 insertions(+), 20 deletions(-) diff --git a/docs/representations/spline_expansions.md b/docs/representations/spline_expansions.md index d6b28d7..71dfa1a 100644 --- a/docs/representations/spline_expansions.md +++ b/docs/representations/spline_expansions.md @@ -49,8 +49,10 @@ t.fit_transform(X).shape ``` Constructor highlights: `output_dim`, `degree=3`, `include_bias=False`, `knot_locations=None` -(pass explicit knots to override placement), `target_aware=False`, `placement_strategy="quantile"`, -`adaptive`, `random_state`. +(pass explicit interior knots to override placement and `output_dim`: each feature then gets +`len(knot_locations) + degree + 1` columns, and knots on or outside its fitted range are dropped +with a warning), `target_aware=False`, `placement_strategy="quantile"`, `adaptive`, +`random_state`. **Parameter impact.** diff --git a/pretab/expansion/spline/base.py b/pretab/expansion/spline/base.py index ab365bf..7ea8c11 100644 --- a/pretab/expansion/spline/base.py +++ b/pretab/expansion/spline/base.py @@ -14,6 +14,7 @@ basis matrix through the ``_design_matrix`` hook. """ +import warnings from typing import ClassVar, Literal import numpy as np @@ -31,9 +32,10 @@ from ...core.policy import RepresentationPolicy, resolve_out_of_range from ...core.supervised import warn_target_leakage from ...exceptions import ( - IncompatibleParamsError, + DataWarning, InvalidParamError, PretabDataError, + invalid_param_error, ) from ...placement.adapters import SplinePlacementAdapter @@ -65,7 +67,10 @@ class BaseSplineTransformer(BasePreTabTransformer): knot_locations : ndarray or None, default=None Explicit internal knot locations applied to every feature. Takes priority over ``target_aware`` placement and the automatic strategy, and overrides - ``output_dim``. + ``output_dim`` and the adaptive bounds: a feature gets + ``len(knot_locations) + degree + 1`` basis functions. Repeated knots are + merged; knots on or outside a feature's fitted range are dropped for that + feature with a :class:`~pretab.exceptions.DataWarning`. target_aware : bool, default=False If True, knots are placed by a target-aware selector built from @@ -231,23 +236,22 @@ def _column_knots( max_basis_req: int | None, ) -> np.ndarray: """Build the full knot vector for a single feature.""" + x_min = x_valid.min() + x_max = x_valid.max() + boundary_left = np.repeat(x_min, self.degree + 1) + boundary_right = np.repeat(x_max, self.degree + 1) + + if self.knot_locations is not None: + internal_knots = self._explicit_knots(x_min, x_max) + return np.concatenate([boundary_left, internal_knots, boundary_right]) + min_basis, max_basis = self._resolve_basis_bounds(n_basis, min_basis_req, max_basis_req) min_knots = self._basis_to_knots(min_basis) max_knots = self._basis_to_knots(max_basis) if self.adaptive: max_knots = min(max_knots, max(0, np.unique(x_valid).size - 2)) - x_min = x_valid.min() - x_max = x_valid.max() - - if self.knot_locations is not None: - expected_knots = self._basis_to_knots(n_basis) - if not self.adaptive and len(self.knot_locations) != expected_knots: - raise IncompatibleParamsError( - "knot_locations length must match output_dim - degree - 1 when adaptive=False" - ) - internal_knots = self._adjust_internal_knots(x_valid, np.asarray(self.knot_locations), min_knots, max_knots) - elif selector is not None: + if selector is not None: selected = selector.get_knot_locations(x_valid.reshape(-1, 1), y_valid, task=self.task) internal_knots = self._adjust_internal_knots(x_valid, np.asarray(selected), min_knots, max_knots) else: @@ -257,11 +261,41 @@ def _column_knots( internal_knots = np.clip(internal_knots, x_min, x_max) internal_knots = np.unique(np.sort(internal_knots)) - - boundary_left = np.repeat(x_min, self.degree + 1) - boundary_right = np.repeat(x_max, self.degree + 1) return np.concatenate([boundary_left, internal_knots, boundary_right]) + def _explicit_knots(self, x_min: float, x_max: float) -> np.ndarray: + """Return the user's ``knot_locations`` that are valid interior knots for one feature. + + Repeated knots are merged. A knot on or beyond the fitted range would give + a basis function with zero-width support, so such knots are dropped with + a :class:`~pretab.exceptions.DataWarning` instead of being replaced. + """ + requested = np.unique(np.asarray(self.knot_locations, dtype=float)) + inside = (requested > x_min) & (requested < x_max) + if not inside.all(): + warnings.warn( + f"knot_locations {requested[~inside].tolist()} lie outside the open feature range " + f"({float(x_min)!r}, {float(x_max)!r}) and were dropped: a knot on or beyond the " + "boundary gives a basis function with zero-width support.", + DataWarning, + stacklevel=4, + ) + return requested[inside] + + def _validate_knot_locations(self) -> None: + """Reject ``knot_locations`` that are not a 1-D sequence of finite numbers.""" + try: + knots = np.asarray(self.knot_locations, dtype=float) + except (TypeError, ValueError): + knots = None + if knots is None or knots.ndim != 1 or not np.isfinite(knots).all(): + raise invalid_param_error( + type(self).__name__, + "knot_locations", + self.knot_locations, + "must be a 1-D sequence of finite numbers (the interior knots shared by every feature)", + ) + def fit(self, X, y=None): """Determine per-feature knot vectors.""" warn_target_leakage(self, y) @@ -269,9 +303,12 @@ def fit(self, X, y=None): n_basis = self._resolve_param("output_dim", default=6) min_basis_req = self._resolve_param("min_output_dim", default=None) max_basis_req = self._resolve_param("max_output_dim", default=None) - if n_basis < self.degree + 1: + if self.knot_locations is not None: + # Explicit knots fix the width; output_dim and the adaptive bounds are ignored. + self._validate_knot_locations() + elif n_basis < self.degree + 1: raise InvalidParamError(f"output_dim must be >= degree + 1 = {self.degree + 1}, got {n_basis}") - if n_basis > 50: + elif n_basis > 50: raise InvalidParamError(f"output_dim should be <= 50, got {n_basis}") X = self._validate(X, reset=True) diff --git a/tests/expansion/spline/test_spline_expansions.py b/tests/expansion/spline/test_spline_expansions.py index a55d9ca..ef97c6d 100644 --- a/tests/expansion/spline/test_spline_expansions.py +++ b/tests/expansion/spline/test_spline_expansions.py @@ -154,3 +154,59 @@ 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) + + +# --- explicit knot_locations ---------------------------------------------------------- + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +@pytest.mark.parametrize("knots", [[5.0], [2.0, 4.0, 6.0, 8.0], list(np.linspace(1, 9, 12))]) +def test_knot_locations_set_the_width_regardless_of_output_dim(cls, knots): + """knot_locations raised unless its length matched the default output_dim, although + the docstring says output_dim is ignored when knots are given.""" + X = np.linspace(0, 10, 50).reshape(-1, 1) + transformer = cls(knot_locations=knots).fit(X) + np.testing.assert_allclose(transformer.knots_[0][4:-4], knots) + assert transformer.transform(X).shape == (50, len(knots) + 4) + + +@pytest.mark.parametrize( + ("knots", "min_output_dim", "max_output_dim"), + [([2.0, 4.0, 6.0, 8.0], 5, 6), ([5.0], 7, 8)], + ids=["not-trimmed", "not-padded"], +) +def test_knot_locations_are_kept_in_adaptive_mode(knots, min_output_dim, max_output_dim): + X = np.linspace(0, 10, 50).reshape(-1, 1) + transformer = BSplineTransformer( + knot_locations=np.array(knots), adaptive=True, min_output_dim=min_output_dim, max_output_dim=max_output_dim + ) + np.testing.assert_array_equal(transformer.fit(X).knots_[0][4:-4], knots) + + +def test_knot_locations_outside_the_range_are_dropped_with_a_warning(): + from pretab.exceptions import DataWarning + + X = np.linspace(0, 10, 50).reshape(-1, 1) + with pytest.warns(DataWarning, match=r"\[-5\.0, 15\.0\] lie outside"): + transformer = BSplineTransformer(knot_locations=np.array([-5.0, 3.0, 3.0, 15.0])).fit(X) + np.testing.assert_array_equal(transformer.knots_[0][4:-4], [3.0]) + + +def test_knot_locations_on_the_boundary_are_dropped_instead_of_giving_a_dead_column(): + """A knot on the boundary was kept and repeated the boundary knot, so one basis + function had zero-width support and was zero on all of the training data.""" + from pretab.exceptions import DataWarning + + X = np.linspace(0, 10, 50).reshape(-1, 1) + with pytest.warns(DataWarning, match=r"\[0\.0\] lie outside"): + transformer = BSplineTransformer(knot_locations=np.array([0.0, 5.0])).fit(X) + np.testing.assert_array_equal(transformer.knots_[0][4:-4], [5.0]) + assert (transformer.transform(X).max(axis=0) > 0).all() + + +@pytest.mark.parametrize("knots", [[[1.0, 2.0]], ["a"], [np.nan]]) +def test_invalid_knot_locations_raise_a_typed_error(knots): + from pretab.exceptions import InvalidParamError + + with pytest.raises(InvalidParamError, match="knot_locations"): + BSplineTransformer(knot_locations=knots).fit(np.linspace(0, 10, 50).reshape(-1, 1))