diff --git a/docs/representations/spline_expansions.md b/docs/representations/spline_expansions.md index d6b28d7..7db8578 100644 --- a/docs/representations/spline_expansions.md +++ b/docs/representations/spline_expansions.md @@ -20,11 +20,13 @@ knot positions by `placement_strategy` (see [Resolution and placement](../core_concepts/resolution_and_placement.md)). ```{important} -For every univariate spline in this section, `output_dim` is the number of output columns +Without explicit knots, `output_dim` is the number of output columns for a univariate spline **per input feature**, not the total. A `(n_samples, 3)` input produces `(n_samples, 3 * output_dim)` output (plus one extra column per feature if `include_bias=True`). Feature names are suffixed per input, for example `x0_bs0, x0_bs1, ...` -for a B-spline on column `x0`. +for a B-spline on column `x0`. For B/M/I splines with explicit `knot_locations`, a feature +with `K` retained unique interior knots instead gets `K + degree + 1` non-bias columns; +different feature ranges can therefore produce different widths. ``` ## B-spline @@ -49,20 +51,24 @@ 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"`, +(pass explicit interior knots to override placement, `output_dim`, and the adaptive bounds: +repeated knots are merged, and knots on or outside a feature's fitted range are dropped with +a warning rather than replaced), `target_aware=False`, `placement_strategy="quantile"`, `adaptive`, `random_state`. **Parameter impact.** `degree` -: Sets the minimum usable `output_dim`: PreTab requires `output_dim >= degree + 1` (a cubic, +: For automatic placement, sets the minimum usable `output_dim`: PreTab requires +`output_dim >= degree + 1` (a cubic, `degree=3`, needs at least 4 columns) and raises a typed error otherwise. Higher degree gives smoother, wider-support basis functions at the same `output_dim`; `degree=1` recovers piecewise-linear segments. `output_dim` : The exact per-feature output width (unlike the cubic/natural/tensor families below, no -conversion is applied). More columns track finer local detail and increase overfitting risk. +conversion is applied). Ignored when `knot_locations` is provided. More columns track finer +local detail and increase overfitting risk. `include_bias` : Defaults to `False`. A B-spline basis over a clamped knot vector already sums to 1 in every @@ -77,7 +83,8 @@ Increase `output_dim` for more wiggle, decrease it to regularize. ```{note} Every spline in this family exposes `get_penalty_matrix(feature_index=0, diff_order=2)`, a -`D^T D` second-difference penalty matrix of shape `(output_dim, output_dim)` (plus the bias +`D^T D` second-difference penalty matrix of shape `(m, m)`, where `m` is the fitted non-bias +width (plus the bias row/column left unpenalized when `include_bias=True`). It is not limited to the "penalized" splines further down this page. Note that `diff_order` is specific to this B/M/I family; the cubic, natural cubic, P-spline, tensor-product, and thin-plate variants expose diff --git a/pretab/expansion/spline/base.py b/pretab/expansion/spline/base.py index 4b12199..a3857c7 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 @@ -30,9 +31,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 @@ -64,10 +66,11 @@ 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``. Like every interior knot, they must be unique and lie - strictly inside a feature's range: repeated knots and knots on or outside - the range are dropped and replaced by strictly interior quantile / uniform - knots. + ``output_dim`` and the adaptive bounds. Repeated knots are merged; knots + on or outside a feature's fitted range are dropped for that feature with + a :class:`~pretab.exceptions.DataWarning`, without adding replacements. + A feature with ``K`` retained unique interior knots gets + ``K + degree + 1`` non-bias basis functions. target_aware : bool, default=False If True, knots are placed by a target-aware selector built from @@ -246,23 +249,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: # 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) @@ -275,10 +277,41 @@ def _column_knots( internal_knots = self._generate_knots(x_valid, n_internal, strategy) internal_knots = self._adjust_internal_knots(x_valid, internal_knots, min_knots, max_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) @@ -287,9 +320,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 d797d3b..e83345e 100644 --- a/tests/expansion/spline/test_spline_expansions.py +++ b/tests/expansion/spline/test_spline_expansions.py @@ -244,6 +244,62 @@ def test_spline_penalty_matrix_symmetric(data): 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], [np.inf], [-np.inf], 5.0]) +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)) + + # --- y is only read by the target-aware selector ------------------------------------- @@ -343,3 +399,98 @@ def test_adaptive_spline_width_is_not_capped_at_the_legacy_window(cls, low, high 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 + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +@pytest.mark.parametrize( + "params", + [ + {"output_dim": 1}, + {"output_dim": 100}, + {"adaptive": True, "output_dim": 1, "min_output_dim": 100, "max_output_dim": 1}, + ], +) +def test_explicit_knots_ignore_output_dim_and_adaptive_range_checks(cls, params): + X = np.linspace(0, 10, 50).reshape(-1, 1) + transformer = cls(knot_locations=[2.0, 4.0, 6.0, 8.0], **params).fit(X) + assert transformer.transform(X).shape == (50, 8) + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +@pytest.mark.parametrize("placement_strategy", ["cart", "lightgbm"]) +def test_explicit_knots_fit_in_a_multi_output_pipeline_without_a_selector(cls, placement_strategy): + from sklearn.linear_model import Ridge + from sklearn.pipeline import make_pipeline + + X = np.linspace(0, 10, 200).reshape(-1, 1) + y = np.column_stack([np.sin(X[:, 0]), np.cos(X[:, 0])]) + transformer = cls( + knot_locations=np.array([2.0, 4.0, 6.0, 8.0]), + output_dim=1, + target_aware=True, + placement_strategy=placement_strategy, + ) + pipe = make_pipeline(transformer, Ridge()).fit(X, y) + assert pipe.predict(X).shape == (200, 2) + assert pipe.named_steps["ridge"].n_features_in_ == 8 + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +@pytest.mark.parametrize("degree", [1, 3]) +@pytest.mark.parametrize("knots", [[], [8.0, 2.0, 5.0, 5.0], list(np.linspace(1, 9, 60))]) +def test_explicit_knots_are_sorted_merged_and_never_refilled_or_capped(cls, degree, knots): + X = np.linspace(0, 10, 201).reshape(-1, 1) + requested = np.asarray(knots) + original = requested.copy() + expected = np.unique(requested) + transformer = cls(knot_locations=requested, degree=degree).fit(X) + boundary = degree + 1 + + np.testing.assert_array_equal(transformer.knots_[0][boundary:-boundary], expected) + assert transformer.transform(X).shape == (201, len(expected) + boundary) + np.testing.assert_array_equal(requested, original) + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +@pytest.mark.parametrize("degree", [1, 3]) +@pytest.mark.parametrize("include_bias", [False, True]) +def test_explicit_knots_size_metadata_penalties_and_missing_blocks_per_feature(cls, degree, include_bias): + import pickle + + from pretab.exceptions import DataWarning + + X = np.column_stack([np.linspace(0, 10, 201), np.linspace(2, 8, 201), np.linspace(20, 30, 201)]) + requested = [0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 4.0] + with pytest.warns(DataWarning) as caught: + transformer = cls(knot_locations=requested, degree=degree, include_bias=include_bias).fit(X) + assert len(caught) == 3 + np.testing.assert_array_equal(transformer.n_knots_, [4, 2, 0]) + sizes = [count + degree + 1 + int(include_bias) for count in [4, 2, 0]] + out = transformer.transform(X) + assert out.shape == (201, sum(sizes)) + assert np.isfinite(out).all() + assert transformer.get_n_features_out() == sum(sizes) + spec = transformer.get_representation_spec(["a", "b", "c"]) + assert spec.output_dim == sum(sizes) + assert spec.output_features == tuple(transformer.get_feature_names_out(["a", "b", "c"])) + restored = pickle.loads(pickle.dumps(transformer)) # noqa: S301 - only locally generated test data + np.testing.assert_array_equal(restored.transform(X), out) + + probe = X.copy() + probe[7, 1] = np.nan + probe[9, 0] = np.nan + missing_out = transformer.transform(probe) + offset = 0 + for i, size in enumerate(sizes): + basis = slice(offset + int(include_bias), offset + size) + assert (out[:, basis].max(axis=0) > 0).all() + missing = np.isnan(probe[:, i]) + assert np.isnan(missing_out[missing, basis]).all() + np.testing.assert_array_equal(missing_out[~missing, basis], out[~missing, basis]) + penalty = transformer.get_penalty_matrix(feature_index=i) + assert penalty.shape == (size, size) + np.testing.assert_array_equal(penalty, penalty.T) + if include_bias: + np.testing.assert_array_equal(missing_out[:, offset], 1.0) + np.testing.assert_array_equal(penalty[0], 0.0) + offset += size