diff --git a/docs/representations/choosing_a_method.md b/docs/representations/choosing_a_method.md index 7524f36..c0e2faf 100644 --- a/docs/representations/choosing_a_method.md +++ b/docs/representations/choosing_a_method.md @@ -84,9 +84,11 @@ feature does not carry the signal, no representation will create it. Measure, do PreTab is explicit about degenerate inputs rather than failing silently. - **Constant column**: the splines that need spread (B/M/I, cubic, natural cubic, P-spline, - tensor-product) raise a typed error rather than fitting a meaningless basis. Numeric - binning falls back to a single bin instead of raising, and PLE and the feature maps place - all their bins or centers at the same value, a degenerate but still valid basis. + tensor-product) raise a typed error rather than fitting a meaningless basis. A column + with a single observed value (a one-row input, or one non-missing value) has no spread + either and raises the same error. Numeric binning falls back to a single bin instead of + raising, and PLE and the feature maps place all their bins or centers at the same value, + a degenerate but still valid basis. - **Discrete or heavily tied column**: target-aware PLE and feature maps still get the requested number of distinct bin edges or centers strictly inside the observed range. When the tree finds fewer splits than requested, the shortfall is filled with spaced quantile diff --git a/pretab/expansion/spline/base.py b/pretab/expansion/spline/base.py index d5540bf..bc51a69 100644 --- a/pretab/expansion/spline/base.py +++ b/pretab/expansion/spline/base.py @@ -158,6 +158,11 @@ class BaseSplineTransformer(BasePreTabTransformer): expands to a row of NaN in its feature's basis block (an optional bias column stays 1), as in the other spline families. + A feature needs at least two distinct observed values: ``fit`` raises a + :class:`~pretab.exceptions.PretabDataError` for a constant feature and for a + feature with a single observed value (a one-row ``X``, or one non-missing + value), since no knot can be placed on a zero-range feature. + Examples -------- >>> import numpy as np @@ -361,7 +366,15 @@ def fit(self, X, y=None): xi_valid = xi[valid_mask] if xi_valid.size == 0: raise PretabDataError(f"Feature at index {i} has only NaN values") - if xi_valid.size > 1 and np.ptp(xi_valid) == 0: + if xi_valid.size == 1: + # One observed value has no range either: no interior knot fits + # between the coinciding boundary knots, and evaluating the basis + # at transform would fail inside SciPy. + raise PretabDataError( + f"Feature at index {i} has only 1 sample with an observed (non-missing) value " + f"({float(xi_valid[0])!r}); a spline basis cannot be constructed on a zero-range feature." + ) + if np.ptp(xi_valid) == 0: raise PretabDataError( f"Feature at index {i} is constant (all values equal {float(xi_valid[0])!r}); " "a spline basis cannot be constructed on a zero-range feature." diff --git a/pretab/expansion/spline/mixins.py b/pretab/expansion/spline/mixins.py index ddb7971..5c7f787 100644 --- a/pretab/expansion/spline/mixins.py +++ b/pretab/expansion/spline/mixins.py @@ -56,7 +56,8 @@ def _finite_column(self, x, y): feature no longer poisons ``min`` / ``max`` / quantile knots with ``NaN``; the missing rows are still expanded to ``NaN`` basis rows at transform time (the "propagate" contract). A fully missing feature cannot yield knots and - raises a :class:`~pretab.exceptions.PretabDataError`. + raises a :class:`~pretab.exceptions.PretabDataError`, as does a zero-range + feature: a constant one, or one with a single observed value. """ x = np.asarray(x, dtype=float) finite = ~np.isnan(x) @@ -65,7 +66,14 @@ def _finite_column(self, x, y): if not finite.all(): x = x[finite] y = np.asarray(y)[finite] if y is not None else y - if x.size > 1 and np.ptp(x) == 0: + if x.size == 1: + # One observed value has no range either: the basis would silently + # degenerate (all-zero rows, or fewer columns than requested). + raise PretabDataError( + f"Feature has only 1 sample with an observed (non-missing) value ({float(x[0])!r}); " + "a spline basis cannot be constructed on a zero-range feature." + ) + if np.ptp(x) == 0: raise PretabDataError( f"Feature is constant (all values equal {float(x[0])!r}); " "a spline basis cannot be constructed on a zero-range feature." diff --git a/tests/integration/test_edge_case_contract.py b/tests/integration/test_edge_case_contract.py index 005c397..905f50b 100644 --- a/tests/integration/test_edge_case_contract.py +++ b/tests/integration/test_edge_case_contract.py @@ -125,6 +125,60 @@ def test_constant_column_degrades_gracefully(name, rng): assert np.isfinite(out).all() +# --------------------------------------------------------------------------- # +# Single observed value +# --------------------------------------------------------------------------- # +def _single_value_inputs(): + """A one-row column, and a column whose only non-missing value sits among NaNs.""" + mostly_missing = np.full((40, 1), np.nan) + mostly_missing[7, 0] = 3.14 + return {"one_row": np.array([[3.14]]), "one_observed": mostly_missing} + + +@pytest.mark.parametrize("shape", ["one_row", "one_observed"]) +@pytest.mark.parametrize("name", CONSTANT_RAISES) +def test_single_observed_value_raises_typed_error(name, shape): + """One observed value is a zero-range feature, like a constant column. + + It used to pass ``fit``: the B/M/I splines then failed inside SciPy at + ``transform``, the P-spline / tensor-product bases were all zero, and the + cubic families emitted fewer columns than requested. + """ + X = _single_value_inputs()[shape] + if name == "TensorProduct": + X = np.hstack([X, X]) + with pytest.raises(PretabDataError, match=r"only 1 sample with an observed .* zero-range feature"): + _factory(name).fit(X) + + +@pytest.mark.parametrize("name", ["BSpline", "MSpline", "ISpline"]) +def test_single_observed_value_error_names_the_feature(name): + X = np.column_stack([np.linspace(0.0, 1.0, 40), np.full(40, np.nan)]) + X[3, 1] = 2.5 + with pytest.raises(PretabDataError, match="Feature at index 1 has only 1 sample"): + _factory(name).fit(X) + + +@pytest.mark.parametrize("name", CONSTANT_RAISES) +def test_two_distinct_values_still_fit(name): + """The smallest feature with spread keeps fitting and gives a finite basis.""" + X = np.array([[0.0], [1.0]]) + if name == "TensorProduct": + X = np.hstack([X, X]) + out = _factory(name).fit(X).transform(X) + assert out.shape[0] == 2 + assert np.isfinite(out).all() + + +@pytest.mark.parametrize("method", ["bspline", "pspline", "cubicspline", "naturalspline"]) +def test_preprocessor_single_row_spline_fit_raises_typed_error(method): + """A one-row fit reports the zero-range column instead of failing at transform.""" + df = pd.DataFrame({"x": [1.5]}) + pre = Preprocessor(numerical_method=method, target_aware=False, placement_strategy="uniform") + with pytest.raises(PretabDataError, match="only 1 sample with an observed"): + pre.fit(df) + + # --------------------------------------------------------------------------- # # Fully-missing column # --------------------------------------------------------------------------- #