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
7 changes: 7 additions & 0 deletions docs/core_concepts/target_awareness.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 8 additions & 3 deletions pretab/core/selectors.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]

Expand Down Expand Up @@ -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
Expand All @@ -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.")
Expand All @@ -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.
Expand Down
45 changes: 43 additions & 2 deletions pretab/core/validation.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
14 changes: 11 additions & 3 deletions pretab/encoding/numerical/ple.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
-------
Expand All @@ -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)}")
Expand Down
13 changes: 9 additions & 4 deletions pretab/expansion/spline/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"``.
Expand Down Expand Up @@ -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.
Expand All @@ -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]):
Expand Down
58 changes: 58 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,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) ------------


Expand Down
58 changes: 57 additions & 1 deletion tests/integration/test_edge_case_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
# --------------------------------------------------------------------------- #
Expand Down
61 changes: 61 additions & 0 deletions tests/integration/test_preprocessor.py
Original file line number Diff line number Diff line change
Expand Up @@ -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) -------------------------------------------------


Expand Down
Loading