diff --git a/docs/core_concepts/target_awareness.md b/docs/core_concepts/target_awareness.md index d3eccf2..18f958e 100644 --- a/docs/core_concepts/target_awareness.md +++ b/docs/core_concepts/target_awareness.md @@ -29,6 +29,13 @@ 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. Explicit spline +`knot_locations` also ignore `y`, because no target-aware selector runs. + ## 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 dd1cf6f..7e61a59 100644 --- a/pretab/core/selectors.py +++ b/pretab/core/selectors.py @@ -30,6 +30,7 @@ from ..exceptions import IncompatibleParamsError, OptionalDependencyError from .knots import quantile_knots, select_knots, uniform_knots from .parameters import validate_task +from .validation import single_target Task = Literal["regression", "classification"] @@ -75,8 +76,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"} or None, default="regression" Type of prediction task. ``None`` is treated as ``"regression"``. min_count : int @@ -96,6 +99,8 @@ def select( ------ InvalidParamError If ``task`` is not ``"regression"``, ``"classification"`` or ``None``. + IncompatibleParamsError + If ``y`` is missing or has more than one output column. """ if y is None: raise IncompatibleParamsError(f"{type(self).__name__} requires y to select locations.") @@ -104,7 +109,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 7bd8a96..9c86645 100644 --- a/pretab/core/validation.py +++ b/pretab/core/validation.py @@ -14,9 +14,50 @@ import pandas as pd from sklearn.utils.validation import check_array -from ..exceptions import DataWarning, PretabDataError +from ..exceptions import DataWarning, IncompatibleParamsError, PretabDataError -__all__ = ["is_polars_frame", "polars_to_pandas", "validate_2d_allow_nan"] +__all__ = ["is_polars_frame", "polars_to_pandas", "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 is_polars_frame(X) -> bool: diff --git a/pretab/encoding/numerical/ple.py b/pretab/encoding/numerical/ple.py index 72caed7..5c899ca 100644 --- a/pretab/encoding/numerical/ple.py +++ b/pretab/encoding/numerical/ple.py @@ -16,6 +16,7 @@ from ...core.parameters import UNSET, AliasResolverMixin, validate_task 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 ac57686..4b12199 100644 --- a/pretab/expansion/spline/base.py +++ b/pretab/expansion/spline/base.py @@ -71,8 +71,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"``. @@ -291,8 +294,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. @@ -307,6 +308,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 46d4e54..d797d3b 100644 --- a/tests/expansion/spline/test_spline_expansions.py +++ b/tests/expansion/spline/test_spline_expansions.py @@ -244,6 +244,64 @@ def test_spline_penalty_matrix_symmetric(data): 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]) + + # --- target-aware splines search their own knot window (issue #69) ------------ diff --git a/tests/integration/test_edge_case_contract.py b/tests/integration/test_edge_case_contract.py index eb91d48..005c397 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 CrossFittedTransformer, Preprocessor, RepresentationPolicy -from pretab.exceptions import DataWarning, InsufficientSamplesError, PretabDataError +from pretab.exceptions import DataWarning, IncompatibleParamsError, InsufficientSamplesError, PretabDataError from pretab.transformers import ( BSplineTransformer, CubicRegressionSplineTransformer, @@ -261,6 +261,62 @@ def test_preprocessor_stores_resolved_policy(rng): 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) +@pytest.mark.parametrize("n_samples", [5, 200]) +def test_target_aware_placement_rejects_a_multi_output_target(name, strategy, n_samples, 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=(n_samples, 1)) + Y = np.column_stack([np.sin(X[:, 0]), np.cos(X[:, 0])]) + with pytest.raises(IncompatibleParamsError, match=rf"single target, but y has shape \({n_samples}, 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) + + # --------------------------------------------------------------------------- # # Column with no observed value at fit, through the Preprocessor # --------------------------------------------------------------------------- # diff --git a/tests/integration/test_preprocessor.py b/tests/integration/test_preprocessor.py index 51cee2a..24c831f 100644 --- a/tests/integration/test_preprocessor.py +++ b/tests/integration/test_preprocessor.py @@ -383,6 +383,67 @@ def test_unknown_feature_preprocessing_key_raises(sample_data): 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", "mspline", "ispline"]) +def test_multi_output_pipeline_imputes_before_unsupervised_spline(method): + from sklearn.linear_model import Ridge + + rng = np.random.default_rng(0) + frame = pd.DataFrame({"a": rng.normal(size=200), "b": rng.normal(size=200)}) + targets = np.column_stack([np.sin(frame["a"]), np.cos(frame["b"])]) + frame.iloc[::10, 0] = np.nan + pipeline = Pipeline( + [ + ("pre", Preprocessor(numerical_method=method, target_aware=False, placement_strategy="uniform")), + ("model", Ridge()), + ] + ).fit(frame, targets) + predictions = pipeline.predict(frame) + assert predictions.shape == targets.shape + assert np.isfinite(predictions).all() + assert np.isfinite(pipeline.named_steps["pre"].transform(frame)).all() + + +@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) + + # --- input containers (issue #94) -------------------------------------------------