From 1cf85c0e5e5fa31cdfb1bcca1c7a90651b37a884 Mon Sep 17 00:00:00 2001 From: ChrisW09 <50968720+ChrisW09@users.noreply.github.com> Date: Fri, 16 Oct 2026 14:34:05 +0200 Subject: [PATCH] fix(splines): ignore y when unsupervised and reject a multi-output target The B-, M- and I-spline transformers flattened y and masked it with each feature's missing-value mask even when no target-aware selector used it, so a multi-output target of n rows (2n values after ravel) raised an IndexError in fit. make_pipeline(BSplineTransformer(), Ridge()).fit(X, Y) with a 2-D Y failed, as did explicit knot_locations and the Preprocessor with numerical_method="bspline" / "mspline" / "ispline" and target_aware=False, while scikit-learn's SplineTransformer and the other spline families and feature maps ignore y there. Target-aware placement fits one decision tree or boosting model on one target, but no error said so: the B/M/I splines (including the regression presets) hit the same IndexError before the selector ran, the shared location selector flattened y and failed with a NumPy broadcasting error (natural-cubic, cubic-regression, feature maps), and PLE, the Preprocessor's default method, reported "X and y must have same length". y is now read only when the target-aware selector places the knots; the unsupervised and explicit knot_locations paths ignore it. On the selector path y is sliced by rows like X instead of being flattened. A shared single_target() check in the location selector and PLE flattens a column vector as before and raises an IncompatibleParamsError for more than one output column, pointing to target_aware=False. Fixes #88 --- docs/core_concepts/target_awareness.md | 6 ++ pretab/core/selectors.py | 9 ++- pretab/core/validation.py | 45 +++++++++++++- pretab/encoding/numerical/ple.py | 14 ++++- pretab/expansion/spline/base.py | 13 +++-- .../spline/test_spline_expansions.py | 58 +++++++++++++++++++ tests/integration/test_edge_case_contract.py | 57 +++++++++++++++++- tests/integration/test_preprocessor.py | 41 +++++++++++++ 8 files changed, 230 insertions(+), 13 deletions(-) diff --git a/docs/core_concepts/target_awareness.md b/docs/core_concepts/target_awareness.md index d3eccf2..2464289 100644 --- a/docs/core_concepts/target_awareness.md +++ b/docs/core_concepts/target_awareness.md @@ -29,6 +29,12 @@ rather than silently producing an unsupervised result. Always pass `y` to a pipe contains PLE. ``` +Target-aware placement fits one decision tree or boosting model on a single target, so a +multi-output `y` of shape `(n_samples, k)` with `k > 1` raises `IncompatibleParamsError` for +`ple` and for an `optional` method with `target_aware=True`; a column vector of shape +`(n_samples, 1)` counts as a single target. With `target_aware=False` the `optional` methods +ignore `y`, so they also fit inside a multi-output pipeline. + ## The fitted-usage flag After fitting, a transformer reports whether it actually consumed the target through diff --git a/pretab/core/selectors.py b/pretab/core/selectors.py index f4cef30..271a8d5 100644 --- a/pretab/core/selectors.py +++ b/pretab/core/selectors.py @@ -27,6 +27,7 @@ from ..exceptions import IncompatibleParamsError, OptionalDependencyError from .knots import quantile_knots, select_knots +from .validation import single_target Task = Literal["regression", "classification"] @@ -66,8 +67,10 @@ def select( ---------- x : np.ndarray of shape (n_samples,) or (n_samples, 1) Input feature values for one feature. - y : np.ndarray of shape (n_samples,) - Target values. Required -- these selectors are target aware. + y : np.ndarray of shape (n_samples,) or (n_samples, 1) + Target values. Required -- these selectors are target aware and fit a + single target; a multi-output ``y`` raises + :class:`~pretab.exceptions.IncompatibleParamsError`. task : {"regression", "classification"}, optional Type of prediction task. Defaults to ``"regression"``. min_count : int @@ -87,7 +90,7 @@ def select( x = np.asarray(x) if x.ndim == 1: x = x.reshape(-1, 1) - y = np.asarray(y).ravel() + y = single_target(y, type(self).__name__) # Only float targets can carry NaN; for integer / object (e.g. string # class label) targets, leave the target validation to the fitted model. diff --git a/pretab/core/validation.py b/pretab/core/validation.py index fbe7ea7..5f2c783 100644 --- a/pretab/core/validation.py +++ b/pretab/core/validation.py @@ -12,9 +12,50 @@ import numpy as np from sklearn.utils.validation import check_array -from ..exceptions import DataWarning, PretabDataError +from ..exceptions import DataWarning, IncompatibleParamsError, PretabDataError -__all__ = ["validate_2d_allow_nan"] +__all__ = ["single_target", "validate_2d_allow_nan"] + + +def single_target(y, estimator: str, *, fix: str | None = None) -> np.ndarray: + """Return the target that target-aware placement fits on, as a 1D array. + + Locations are placed by one decision tree or boosting model fitted on a single + target: a column vector is flattened, while a multi-output ``y`` raises instead + of being flattened into ``n_samples * n_outputs`` values. + + Parameters + ---------- + y : array-like + Target values. + estimator : str + Class name used in the error message. + fix : str, optional + How to resolve a multi-output ``y``, appended to the error message. + Defaults to fitting on one target column or switching to unsupervised + placement (``target_aware=False``). + + Returns + ------- + np.ndarray of shape (n_samples,) + The flattened single target. + + Raises + ------ + IncompatibleParamsError + If ``y`` has more than one output column. + """ + y = np.asarray(y) + if y.ndim > 1 and int(np.prod(y.shape[1:])) != 1: + if fix is None: + fix = ( + "fit on one target column, or use unsupervised placement (target_aware=False) " + "for a multi-output target." + ) + raise IncompatibleParamsError( + f"{estimator} places locations against a single target, but y has shape {y.shape}.\nFix: {fix}" + ) + return y.ravel() def validate_2d_allow_nan(X, *, allow_nan: bool = True, reset: bool, estimator): diff --git a/pretab/encoding/numerical/ple.py b/pretab/encoding/numerical/ple.py index 81a639c..57785e3 100644 --- a/pretab/encoding/numerical/ple.py +++ b/pretab/encoding/numerical/ple.py @@ -16,6 +16,7 @@ from ...core.parameters import UNSET, AliasResolverMixin from ...core.representation import RepresentationSpecMixin from ...core.supervised import warn_target_leakage +from ...core.validation import single_target from ...exceptions import ( IncompatibleParamsError, InvalidParamError, @@ -146,9 +147,11 @@ def fit(self, X, y=None): ---------- X : array-like of shape (n_samples, n_features) Training data. Must be finite; NaN values raise an error. - y : array-like of shape (n_samples,) + y : array-like of shape (n_samples,) or (n_samples, 1) Target values used to grow the per-feature decision trees. PLE is - always target-aware, so ``y`` is required. + always target-aware, so ``y`` is required, and it places its bins + against a single target: a multi-output ``y`` raises + :class:`~pretab.exceptions.IncompatibleParamsError`. Returns ------- @@ -167,7 +170,12 @@ def fit(self, X, y=None): ensure_2d=True, ensure_all_finite=True, # type: ignore ) - y = np.asarray(y).ravel() + y = single_target( + y, + type(self).__name__, + fix="fit on one target column. PLE always places its bins against y, so a multi-output " + "target needs a numerical method with unsupervised placement.", + ) if len(X) != len(y): raise PretabDataError(f"X and y must have same length. Got {len(X)} and {len(y)}") diff --git a/pretab/expansion/spline/base.py b/pretab/expansion/spline/base.py index ab365bf..762f7a4 100644 --- a/pretab/expansion/spline/base.py +++ b/pretab/expansion/spline/base.py @@ -69,8 +69,11 @@ class BaseSplineTransformer(BasePreTabTransformer): target_aware : bool, default=False If True, knots are placed by a target-aware selector built from - ``placement_strategy`` (requires ``y`` during fit). If False, knots are - placed by the unsupervised ``placement_strategy`` spacing. + ``placement_strategy`` (requires a single-target ``y`` during fit; a + multi-output ``y`` raises + :class:`~pretab.exceptions.IncompatibleParamsError`). If False, knots are + placed by the unsupervised ``placement_strategy`` spacing and ``y`` is + ignored (as it is with explicit ``knot_locations``). placement_strategy : {"cart", "lightgbm", "uniform", "quantile"}, default="quantile" When ``target_aware=True``, the selector: ``"cart"`` or ``"lightgbm"``. @@ -276,8 +279,6 @@ def fit(self, X, y=None): X = self._validate(X, reset=True) - y_arr = None if y is None else np.asarray(y).ravel() - # Knot placement priority: explicit knot_locations win, then a target-aware # selector built from placement_strategy, then the automatic (unsupervised) # spacing named by placement_strategy. @@ -292,6 +293,10 @@ def fit(self, X, y=None): else: selector = None strategy = self.placement_strategy if not self.target_aware else "quantile" + # Only the target-aware selector reads y; the unsupervised and explicit-knot + # paths ignore it, so any target shape (e.g. multi-output) can pass through + # a Pipeline. For the selector, y is sliced by rows like X, not flattened. + y_arr = None if y is None or selector is None else np.asarray(y) self.knots_ = [] for i in range(X.shape[1]): diff --git a/tests/expansion/spline/test_spline_expansions.py b/tests/expansion/spline/test_spline_expansions.py index a55d9ca..42b32cc 100644 --- a/tests/expansion/spline/test_spline_expansions.py +++ b/tests/expansion/spline/test_spline_expansions.py @@ -154,3 +154,61 @@ 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) + + +# --- y is only read by the target-aware selector ------------------------------------- + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +@pytest.mark.parametrize( + "params", + [ + {}, + {"placement_strategy": "uniform"}, + {"target_aware": True, "placement_strategy": "cart", "knot_locations": [-0.5, 0.5]}, + ], +) +def test_unsupervised_bmi_spline_ignores_a_multi_output_target(cls, params): + """The target was flattened and masked even when no selector used it, so a 2-D y + of n rows (2n values) raised an IndexError in fit.""" + rng = np.random.default_rng(0) + X = rng.normal(size=(200, 2)) + X[3, 0] = np.nan + Y = np.column_stack([np.sin(X[:, 0]), np.cos(X[:, 1])]) + reference = cls(**params).fit(X) + fitted = cls(**params).fit(X, Y) + for knots, expected in zip(fitted.knots_, reference.knots_, strict=True): + np.testing.assert_array_equal(knots, expected) + np.testing.assert_array_equal(fitted.transform(X), reference.transform(X)) + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +@pytest.mark.parametrize("params", [{}, {"placement_strategy": "uniform"}]) +def test_unsupervised_bmi_spline_never_reads_y(cls, params): + X = np.linspace(0.0, 1.0, 50).reshape(-1, 1) + X[3, 0] = np.nan + reference = cls(**params).fit(X) + fitted = cls(**params).fit(X, np.zeros(10)) # a y that cannot be row-aligned with X + np.testing.assert_array_equal(fitted.knots_[0], reference.knots_[0]) + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +def test_bmi_spline_fits_in_a_multi_output_pipeline(cls): + from sklearn.linear_model import Ridge + from sklearn.pipeline import make_pipeline + + rng = np.random.default_rng(0) + X = rng.normal(size=(200, 1)) + Y = np.column_stack([np.sin(X[:, 0]), np.cos(X[:, 0])]) + assert make_pipeline(cls(), Ridge()).fit(X, Y).predict(X).shape == (200, 2) + + +@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer]) +def test_target_aware_bmi_spline_accepts_a_column_vector_target(cls): + rng = np.random.default_rng(1) + X = rng.uniform(0, 10, (1000, 1)) + y = np.where(X[:, 0] > 5.0, 1.0, 0.0) + 0.3 * rng.normal(size=1000) + X[::50, 0] = np.nan + flat = cls(output_dim=6, target_aware=True, placement_strategy="cart").fit(X, y) + column = cls(output_dim=6, target_aware=True, placement_strategy="cart").fit(X, y.reshape(-1, 1)) + np.testing.assert_array_equal(column.knots_[0], flat.knots_[0]) diff --git a/tests/integration/test_edge_case_contract.py b/tests/integration/test_edge_case_contract.py index 97e8b07..ec0d62a 100644 --- a/tests/integration/test_edge_case_contract.py +++ b/tests/integration/test_edge_case_contract.py @@ -16,7 +16,7 @@ import pytest from pretab import Preprocessor, RepresentationPolicy -from pretab.exceptions import DataWarning, InsufficientSamplesError, PretabDataError +from pretab.exceptions import DataWarning, IncompatibleParamsError, InsufficientSamplesError, PretabDataError from pretab.transformers import ( BSplineTransformer, CubicRegressionSplineTransformer, @@ -258,3 +258,58 @@ def test_preprocessor_stores_resolved_policy(rng): pre.fit(df, y) assert isinstance(pre.policy_, RepresentationPolicy) assert pre.policy_.constant == "warn" + + +# --------------------------------------------------------------------------- # +# Multi-output target +# --------------------------------------------------------------------------- # +def _target_aware_factory(name, strategy): + """Build a transformer that places its units against the target.""" + if strategy == "lightgbm": + pytest.importorskip("lightgbm") + options = {"target_aware": True, "placement_strategy": strategy} + return { + "BSpline": lambda: BSplineTransformer(**options), + "MSpline": lambda: MSplineTransformer(**options), + "ISpline": lambda: ISplineTransformer(**options), + "NaturalCubic": lambda: NaturalCubicSplineTransformer(**options), + "CubicReg": lambda: CubicRegressionSplineTransformer(**options), + "RBF": lambda: RBFExpansionTransformer(**options), + "ReLU": lambda: ReLUExpansionTransformer(**options), + "Sigmoid": lambda: SigmoidExpansionTransformer(**options), + "Tanh": lambda: TanhExpansionTransformer(**options), + "PLE": lambda: PLETransformer(output_dim=5, placement_strategy=strategy), + }[name]() + + +TARGET_AWARE = ["BSpline", "MSpline", "ISpline", "NaturalCubic", "CubicReg", "RBF", "ReLU", "Sigmoid", "Tanh", "PLE"] + + +@pytest.mark.parametrize("strategy", ["cart", "lightgbm"]) +@pytest.mark.parametrize("name", TARGET_AWARE) +def test_target_aware_placement_rejects_a_multi_output_target(name, strategy, rng): + """Target-aware placement fits one model on one target. A 2-D target was flattened + into twice as many values and failed with an IndexError (B/M/I), a broadcasting + ValueError (natural-cubic, cubic-regression, feature maps) or a misleading length + mismatch (PLE) instead of saying so.""" + X = rng.normal(size=(200, 1)) + Y = np.column_stack([np.sin(X[:, 0]), np.cos(X[:, 0])]) + with pytest.raises(IncompatibleParamsError, match=r"single target, but y has shape \(200, 2\)"): + _target_aware_factory(name, strategy).fit(X, Y) + # A column vector is a single target and places the same units as the flat target. + flat = _target_aware_factory(name, strategy).fit(X, Y[:, 0]).transform(X) + column = _target_aware_factory(name, strategy).fit(X, Y[:, :1]).transform(X) + np.testing.assert_array_equal(column, flat) + + +def test_multi_output_error_suggests_a_fix_the_estimator_supports(rng): + """PLE has no ``target_aware`` option, so its error must not suggest switching it + off; the spline and feature-map selectors do support it.""" + X = rng.normal(size=(200, 1)) + Y = np.column_stack([X[:, 0], -X[:, 0]]) + with pytest.raises(IncompatibleParamsError) as ple_error: + PLETransformer(output_dim=5).fit(X, Y) + assert "target_aware" not in str(ple_error.value) + assert "unsupervised placement" in str(ple_error.value) + with pytest.raises(IncompatibleParamsError, match=r"target_aware=False"): + BSplineTransformer(output_dim=6, target_aware=True, placement_strategy="cart").fit(X, Y) diff --git a/tests/integration/test_preprocessor.py b/tests/integration/test_preprocessor.py index df9d224..a0d0b46 100644 --- a/tests/integration/test_preprocessor.py +++ b/tests/integration/test_preprocessor.py @@ -377,3 +377,44 @@ def test_unknown_feature_preprocessing_key_raises(sample_data): X, y = sample_data with pytest.raises(InvalidParamError, match="feature_preprocessing"): Preprocessor(feature_preprocessing={"nnum1": "minmax"}).fit(X, y) + + +@pytest.mark.parametrize("method", ["bspline", "mspline", "ispline", "pspline", "naturalspline", "rbf"]) +def test_unsupervised_numerical_method_accepts_a_multi_output_target(method): + """The B/M/I splines flattened y even when target_aware=False, so a 2-D target + raised an IndexError in fit while the other methods ignored it.""" + rng = np.random.default_rng(0) + frame = pd.DataFrame({"a": rng.normal(size=200), "b": rng.normal(size=200)}) + Y = np.column_stack([np.sin(frame["a"]), np.cos(frame["b"])]) + options = {"numerical_method": method, "target_aware": False, "placement_strategy": "uniform"} + reference = Preprocessor(**options).fit(frame).transform(frame) + np.testing.assert_array_equal(Preprocessor(**options).fit(frame, Y).transform(frame), reference) + + +@pytest.mark.parametrize("method", ["bspline", "naturalspline", "rbf", "ple"]) +def test_target_aware_numerical_method_rejects_a_multi_output_target(method): + """Target-aware placement fits one model on one target. A 2-D target was + flattened into twice as many values and failed with an unrelated IndexError / + broadcasting error; it now raises a clear error pointing to target_aware=False.""" + rng = np.random.default_rng(0) + frame = pd.DataFrame({"a": rng.normal(size=200), "b": rng.normal(size=200)}) + Y = np.column_stack([np.sin(frame["a"]), np.cos(frame["b"])]) + + with pytest.raises(IncompatibleParamsError, match=r"single target, but y has shape \(200, 2\)"): + Preprocessor(numerical_method=method).fit(frame, Y) + # A column vector is a single target. + Preprocessor(numerical_method=method).fit(frame, Y[:, :1]) + + +@pytest.mark.parametrize( + "options", [{}, {"preset": "standard", "task": "regression"}], ids=["default-ple", "regression-preset-bspline"] +) +def test_preprocessor_defaults_reject_a_multi_output_target(options): + """The default method (PLE) reported "X and y must have same length" and the + regression preset (target-aware B-splines) an IndexError for a 2-D target.""" + rng = np.random.default_rng(0) + frame = pd.DataFrame({"a": rng.normal(size=200), "b": rng.normal(size=200)}) + Y = np.column_stack([np.sin(frame["a"]), np.cos(frame["b"])]) + + with pytest.raises(IncompatibleParamsError, match=r"single target, but y has shape \(200, 2\)"): + Preprocessor(**options).fit(frame, Y)