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
19 changes: 13 additions & 6 deletions docs/representations/spline_expansions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
76 changes: 56 additions & 20 deletions pretab/expansion/spline/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
basis matrix through the ``_design_matrix`` hook.
"""

import warnings
from typing import ClassVar, Literal

import numpy as np
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand Down
151 changes: 151 additions & 0 deletions tests/expansion/spline/test_spline_expansions.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 -------------------------------------


Expand Down Expand Up @@ -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
Loading