fix(splines): ignore y when unsupervised and reject a multi-output target

[ChrisW09]

Fixes #88.

A 2-D (multi-output) y made BSplineTransformer, MSplineTransformer and ISplineTransformer raise an IndexError in fit, even with unsupervised or explicit knot placement where y is never used, so a standard multi-output pipeline such as make_pipeline(BSplineTransformer(), Ridge()).fit(X, Y) failed. Target-aware placement, which needs a single target, failed with unrelated errors instead of saying so.

Root cause

BaseSplineTransformer.fit built y_arr = np.asarray(y).ravel() and sliced it with each feature's NaN mask on every path, not only when a selector used it. A target of shape (n, k) became n * k values, which a mask of length n cannot index. BaseLocationSelector.select and PLETransformer.fit flattened y the same way, so on the target-aware paths of the other families a multi-output target failed with a NumPy broadcasting ValueError (combining the NaN masks of x and y) or with PLE's "X and y must have same length" check.

Fix

• BaseSplineTransformer.fit builds y_arr only when the target-aware selector (SplinePlacementAdapter) places the knots, and slices it by rows like X instead of flattening it. The unsupervised and explicit-knot_locations paths ignore y.
• New pretab.core.validation.single_target(y, estimator, *, fix=None): returns a 1-D target or a column vector flattened, as before, and raises IncompatibleParamsError naming the estimator and the shape of y when it has more than one output column. The message points to one target column or target_aware=False.
• The error's fix hint suits the estimator: the selectors suggest target_aware=False, while PLETransformer, which is always target-aware and has no such option, suggests fitting on one target column or choosing a method with unsupervised placement.
• BaseLocationSelector.select (the CART and LightGBM selectors behind target-aware B/M/I, natural-cubic and cubic-regression splines and the RBF/ReLU/sigmoid/tanh feature maps) and PLETransformer.fit call single_target instead of np.asarray(y).ravel().

Behaviour changes

• B/M/I splines with target_aware=False or explicit knot_locations ignore y entirely, whatever its shape and even when it is not row-aligned with X; knots and output equal those of fit(X). Multi-output pipelines and the unsupervised Preprocessor methods "bspline", "mspline" and "ispline" now fit.
• Every target-aware placement with a multi-output y (B/M/I, natural-cubic, cubic-regression, RBF/ReLU/sigmoid/tanh feature maps and PLE, with "cart" or "lightgbm"; this includes the Preprocessor default ple and the regression presets) raises IncompatibleParamsError: <CARTLocationSelector | LightGBMLocationSelector | PLETransformer> places locations against a single target, but y has shape (200, 2). followed by a Fix: line. Before, it raised an IndexError, a broadcasting ValueError or, for PLE, a PretabDataError.
• Knots and outputs for a 1-D or column-vector target are unchanged; no golden baseline changed.
• pretab.core.validation exports the new helper single_target.

Documentation

• Docstrings (NumPy format): the target_aware parameter of BaseSplineTransformer (True needs a single-target y, a multi-output y raises; False and explicit knot_locations ignore y), the y parameter of BaseLocationSelector.select and PLETransformer.fit (shape (n_samples,) or (n_samples, 1), a multi-output y raises), and single_target with a Raises section.
• docs/core_concepts/target_awareness.md: new paragraph. Target-aware placement fits one model on a single target, so a multi-output y raises IncompatibleParamsError for ple and for an optional method with target_aware=True; a column vector counts as a single target; with target_aware=False the optional methods ignore y and fit inside a multi-output pipeline.

Tests

• test_unsupervised_bmi_spline_ignores_a_multi_output_target[{B,M,I}SplineTransformer x default | uniform | target-aware with explicit knots]: fitting with a 2-D Y (and a NaN in X) gives the same knots and output as fitting without y. Fails on main, passes here.
• test_unsupervised_bmi_spline_never_reads_y[{B,M,I}SplineTransformer x default | uniform]: a y of the wrong length is ignored. Fails on main, passes here.
• test_bmi_spline_fits_in_a_multi_output_pipeline[{B,M,I}SplineTransformer]: make_pipeline(cls(), Ridge()) with a 2-D Y predicts shape (200, 2). Fails on main, passes here.
• test_target_aware_bmi_spline_accepts_a_column_vector_target[{B,M,I}SplineTransformer]: a column-vector y gives the same knots as the flat y on the new row-sliced selector path. Guard test: passes on both by design.
• test_target_aware_placement_rejects_a_multi_output_target[{BSpline, MSpline, ISpline, NaturalCubic, CubicReg, RBF, ReLU, Sigmoid, Tanh, PLE} x {cart, lightgbm}] (edge-case contract): a 2-D Y raises IncompatibleParamsError naming the shape, and a column vector gives the same output as the flat target. All 20 fail on main, pass here; the lightgbm cases skip without LightGBM.
• test_unsupervised_numerical_method_accepts_a_multi_output_target[bspline, mspline, ispline, pspline, naturalspline, rbf] (Preprocessor, target_aware=False): the output with a 2-D Y equals the output without y. The bspline, mspline and ispline cases fail on main, pass here; the pspline, naturalspline and rbf cases are controls that pass on both by design.
• test_target_aware_numerical_method_rejects_a_multi_output_target[bspline, naturalspline, rbf, ple] (Preprocessor): a 2-D Y raises IncompatibleParamsError, a column vector fits. Fails on main, passes here.
• test_preprocessor_defaults_reject_a_multi_output_target[default-ple, regression-preset-bspline]: Preprocessor() and Preprocessor(preset="standard", task="regression") raise IncompatibleParamsError. Fails on main, passes here.
• test_multi_output_error_suggests_a_fix_the_estimator_supports: the PLE message does not mention target_aware, the B-spline message does. Fails on main, passes here.

Reproduction

Output of the script from #88 on this branch:

SplineTransformer -> (200, 2)
NaturalCubicSplineTransformer -> (200, 2)
BSplineTransformer -> (200, 2)
Preprocessor('pspline') -> (200, 7)
Preprocessor('bspline') -> (200, 7)
Preprocessor('ple'), target-aware -> IncompatibleParamsError: PLETransformer places locations against a single target, but y has shape (200, 2).
Fix: fit on one target column, or use unsupervised placement (target_aware=False) for a multi-output target.
Preprocessor('naturalspline'), target-aware -> IncompatibleParamsError: CARTLocationSelector places locations against a single target, but y has shape (200, 2).
Fix: fit on one target column, or use unsupervised placement (target_aware=False) for a multi-output target.

Checks

• just test: 1492 passed, 59 skipped, 7 xfailed; coverage 93.77% (gate 90%).
• Minimum dependencies (CI job: Python 3.10, numpy 1.24.4, pandas 2.0.3, scipy 1.10.1, scikit-learn 1.6.0): 1469 passed, 82 skipped, 7 xfailed; scripts/quickstart.py passes.
• just docs: strict build succeeds.
• just check: all pre-commit and pre-push hooks pass (ruff format, ruff lint, prettier, file hygiene, pyright with 0 errors).
• Import direction between subpackages is unchanged.

Merge notes

• Base: main.
• The PR for An invalid task such as "Regression" is silently treated as classification by the splines and selectors #93 (fix(validation): reject an unknown task instead of using classification #128) conflicts in pretab/core/selectors.py in two places. In the imports, this PR adds from .validation import single_target and An invalid task such as "Regression" is silently treated as classification by the splines and selectors #93 adds from .parameters import validate_task. In the docstring of BaseLocationSelector.select, this PR rewrites the y entry and An invalid task such as "Regression" is silently treated as classification by the splines and selectors #93 the task entry. Keep both sides in each. The code of select and of PLETransformer.fit merges cleanly (validate_task runs first, then single_target), and the combined branches pass the full test suite (1523 passed, 59 skipped, 7 xfailed).
• The PR for Target-aware location selectors return too few, duplicate, or boundary locations on tied/discrete features #57 (fix(placement): fill tied-data locations with distinct interior points #102) adds uniform_knots to the .knots import line in pretab/core/selectors.py, next to this PR's single_target import: keep both. The PRs for LightGBM placement with task="classification" always uses the binary objective on raw labels #61 (fix(placement): label-encode classification targets for LightGBM #105) and CART location selector can drop the dominant split because spacing is enforced in ascending location order #70 (fix(placement): rank CART splits by impurity decrease before spacing #110) also change selectors.py and merge cleanly.
• The PR for Standalone transformers drop DataFrame feature names, so reordered columns are silently misaligned #85 (fix(transformers): record and check DataFrame feature names #135) conflicts in pretab/core/validation.py (both add a helper, extend __all__ and change the ..exceptions import) and on the core.validation import line in pretab/encoding/numerical/ple.py. Keep both: __all__ = ["resolve_input_features", "single_target", "validate_2d_allow_nan"], import DataWarning, IncompatibleParamsError, PretabDataError, invalid_param_error, and from ...core.validation import resolve_input_features, single_target.
• The PR for Preprocessor rejects polars DataFrames, so pipelines with set_output(transform="polars") crash #94 (fix(preprocessor): accept polars DataFrames as input #129) conflicts in pretab/core/validation.py the same way (it adds is_polars_frame and polars_to_pandas and extends __all__): keep both helpers and all names in __all__.
• The PRs for Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56 (fix(splines): keep knots unique and strictly interior on tied data #101), Target-aware splines trim selector knots by position, dropping the dominant split, and cap adaptive width at 15 #69 (fix(splines): search the resolved knot window in target-aware placement #109), B/M/I spline knot_locations are sized by output_dim and clipped to the data range instead of used as given #81 (fix(splines): honour explicit knot_locations regardless of output_dim #118), Unsupervised quantile placement repeats RBF/ReLU/sigmoid/tanh centers on tied data, duplicating columns #82 (fix(placement): return distinct quantile locations on tied data #119), A partial spline policy mapping drops the "clip" default, and "extrapolate"/"warn" give all-zero basis rows #84 (fix(splines): keep family policy defaults and extrapolate out-of-range rows #121) and B/M/I spline and two-feature thin-plate spline transformers encode a missing value as an all-zero row #87 (fix(splines): expand a missing value to a NaN row in the B/M/I and thin-plate bases #122) also change pretab/expansion/spline/base.py and merge cleanly. The explicit-knot test case here uses two knots, [-0.5, 0.5], which both main and the PR for B/M/I spline knot_locations are sized by output_dim and clipped to the data range instead of used as given #81 (fix(splines): honour explicit knot_locations regardless of output_dim #118) accept; with B/M/I spline knot_locations are sized by output_dim and clipped to the data range instead of used as given #81 merged in, the spline, edge-case contract and Preprocessor tests pass.
• Tests are appended at the end of shared files, so whichever lands later gets an append/append conflict: tests/expansion/spline/test_spline_expansions.py with Target-aware splines trim selector knots by position, dropping the dominant split, and cap adaptive width at 15 #69 and B/M/I spline knot_locations are sized by output_dim and clipped to the data range instead of used as given #81, tests/integration/test_preprocessor.py with Preprocessor.fit crashes on any bool column under default settings #54, Preprocessor(numerical_method="box-cox") raises at transform for values below the training minimum #59, Preprocessor.get_feature_names_out(input_features) fails after fitting on an ndarray, breaking Pipeline.get_feature_names_out() #65, Preprocessor.transform does not check n_features_in_ for ndarray input; extra columns are silently misaligned #72, Preprocessor fitted on a DataFrame rejects a same-width NumPy array at transform (and vice versa) #78 and Preprocessor rejects polars DataFrames, so pipelines with set_output(transform="polars") crash #94, and tests/integration/test_edge_case_contract.py with Preprocessor crashes on an all-missing column at fit (numerical, one-hot) or silently drops it (int) #95, which also changes the import lines there (this PR adds IncompatibleParamsError, Preprocessor crashes on an all-missing column at fit (numerical, one-hot) or silently drops it (int) #95 adds CrossFittedTransformer). Keep both sides in each.

This change was previously part of #97, which is closed in favour of one pull request per issue.