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
4 changes: 2 additions & 2 deletions docs/core_concepts/missing_values.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ consistently with imputation.

```{note}
Disabling imputation lets `NaN` reach the transformer directly. Scalers, splines, and the
feature maps (`rbf`, `relu`, `sigmoid`, `tanh`) tolerate it, so an affected row's output is
itself undefined; finite-only methods (PLE, numeric binning, periodic encoding, Fourier
feature maps (`rbf`, `relu`, `sigmoid`, `tanh`) propagate it: the affected row's output columns
for that feature are `NaN` (a spline's optional bias column stays `1`); finite-only methods (PLE, numeric binning, periodic encoding, Fourier
features, `rff`, `nystroem`) raise a typed error instead, since expanding an undefined value
has no meaning for them. `add_missing_indicator=True` still works with imputation disabled: it
routes through the same `__missing` branch `missing_policy="separate_state"` uses below.
Expand Down
18 changes: 16 additions & 2 deletions pretab/expansion/spline/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,10 @@ class BaseSplineTransformer(BasePreTabTransformer):
takes precedence over the automatic ``output_dim`` strategy. Multi-column input
is expanded column by column and stacked horizontally.

Missing values are ignored for knot placement; at transform time a missing value
expands to a row of NaN in its feature's basis block (an optional bias column
stays 1), as in the other spline families.

Examples
--------
>>> import numpy as np
Expand Down Expand Up @@ -334,7 +338,12 @@ def transform(self, X):
for i in range(X.shape[1]):
knots = self.knots_[i]
xi = resolve_out_of_range(X[:, i], knots[0], knots[-1], self._resolved_policy(), estimator=self)
design = self._design_matrix(xi, knots)
# A missing value has no position on the basis: only the observed rows
# are evaluated and the missing ones stay NaN (the "propagate" contract
# of the other spline families) instead of becoming a finite basis row.
observed = ~np.isnan(xi)
design = np.full((len(xi), self.n_basis_[i]), np.nan)
design[observed] = self._design_matrix(xi[observed], knots)
if self.include_bias:
design = np.hstack([np.ones((design.shape[0], 1)), design])
transformed.append(design)
Expand All @@ -346,7 +355,12 @@ def fit_transform(self, X, y=None):
return self.fit(X, y).transform(X)

def _design_matrix(self, x: np.ndarray, knots: np.ndarray) -> np.ndarray:
"""Return the basis matrix for a single feature (without the bias column)."""
"""Return the basis matrix for a single feature (without the bias column).

``x`` holds only the observed (non-missing) values, already resolved
against the out-of-range policy; :meth:`transform` fills the rows of
missing values with NaN.
"""
raise NotImplementedError

def _feature_suffix(self) -> str:
Expand Down
4 changes: 3 additions & 1 deletion pretab/expansion/spline/multivariate/thin_plate.py
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,9 @@ def _tps_kernel(r, d):
if d == 1:
return r**3
if d == 2:
return np.where(r > 0, r**2 * np.log(np.where(r > 0, r, 1.0)), 0.0)
# r == 0 (not r > 0) selects the zero branch, so a missing
# coordinate keeps its NaN distance instead of becoming 0.
return np.where(r == 0, 0.0, r**2 * np.log(np.where(r > 0, r, 1.0)))
# d >= 3: biharmonic (linear) radial kernel.
return r

Expand Down
6 changes: 4 additions & 2 deletions pretab/preprocessor.py
Original file line number Diff line number Diff line change
Expand Up @@ -225,8 +225,10 @@ class Preprocessor(TransformerMixin, BaseEstimator):
numerical_imputation : str or None, default="median"
Strategy for the ``SimpleImputer`` that runs *before* every numerical method. Accepts
any ``sklearn`` strategy (``"median"``, ``"mean"``, ``"most_frequent"``, ``"constant"``).
``None`` disables imputation, so NaNs reach the numerical transformers unchanged and the
finite-input methods (all numerical methods, including PLE) raise on missing values.
``None`` disables imputation, so NaNs reach the numerical transformers unchanged: the
scalers, splines and ``rbf`` / ``relu`` / ``sigmoid`` / ``tanh`` feature maps propagate a
missing value as NaN in that feature's output, while the finite-input methods
(``"ple"``, ``"custombin"``, ``"fourier"``, ``"polynomial"``) raise.
categorical_imputation : str or None, default="most_frequent"
Strategy for the ``SimpleImputer`` that runs *before* every categorical method. ``None``
disables imputation for categorical columns.
Expand Down
49 changes: 48 additions & 1 deletion tests/expansion/spline/test_spline_expansions.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import warnings

import numpy as np
import pytest

Expand Down Expand Up @@ -110,12 +112,57 @@ def test_mspline_non_negative(data):


def test_mspline_handles_nan():
"""A missing value is left out of knot placement and expands to a NaN row."""
X = np.linspace(0, 1, 50).reshape(-1, 1)
X[5] = np.nan
transformer = MSplineTransformer(output_dim=6)
Xt = transformer.fit_transform(X)
assert Xt.shape == (50, 6)
assert np.isfinite(Xt).all()
assert np.isnan(Xt[5]).all()
assert np.isfinite(np.delete(Xt, 5, axis=0)).all()


# --- missing values expand to NaN basis rows -------------------------------------------


@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer])
@pytest.mark.parametrize("include_bias", [False, True])
@pytest.mark.parametrize("out_of_range", ["clip", "extrapolate", "warn", "error"])
def test_bmi_spline_missing_value_expands_to_a_nan_row(cls, include_bias, out_of_range):
"""A missing value became a finite all-zero basis row: impossible data for the
B/M-spline and, for the I-spline, the exact encoding of the training minimum."""
X = np.linspace(0.0, 10.0, 50).reshape(-1, 1)
transformer = cls(output_dim=5, include_bias=include_bias, policy={"out_of_range": out_of_range}).fit(X)
observed = np.array([[0.0], [2.5], [10.0]])
if out_of_range in ("clip", "extrapolate"):
observed = np.vstack([observed, [[-3.0], [14.0]]])
expected = transformer.transform(observed)

probe = np.insert(observed, [0, 2], np.nan, axis=0)
with warnings.catch_warnings():
# A missing value is not out of range: it must not trigger "warn" / "error".
warnings.simplefilter("error")
out = transformer.transform(probe)

missing = np.isnan(probe[:, 0])
basis = slice(1, None) if include_bias else slice(None)
assert np.isnan(out[missing, basis]).all()
if include_bias:
np.testing.assert_array_equal(out[:, 0], 1.0)
np.testing.assert_array_equal(out[~missing], expected)


@pytest.mark.parametrize("cls", [BSplineTransformer, MSplineTransformer, ISplineTransformer])
def test_bmi_spline_missing_value_only_affects_its_own_feature_block(cls):
rng = np.random.default_rng(0)
X = rng.uniform(0.0, 10.0, size=(60, 2))
X[4, 0] = np.nan
X[9, 1] = np.nan
transformer = cls(output_dim=6).fit(X)
out = transformer.transform(X)
np.testing.assert_array_equal(np.isnan(out[:, :6]).any(axis=1), np.isnan(X[:, 0]))
np.testing.assert_array_equal(np.isnan(out[:, 6:]).any(axis=1), np.isnan(X[:, 1]))
assert np.isnan(out[4, :6]).all() and np.isnan(out[9, 6:]).all()


@pytest.mark.parametrize("scale", [1.0, 1e-2, 1e-3, 1e-7])
Expand Down
17 changes: 17 additions & 0 deletions tests/expansion/spline/test_thinplate_transformer.py
Original file line number Diff line number Diff line change
Expand Up @@ -124,3 +124,20 @@ def test_tprs_transform_requires_fit():
transformer.transform(np.random.rand(5, 1))
with pytest.raises(NotFittedError):
transformer.get_penalty_matrix()


@pytest.mark.parametrize("n_features", [1, 2, 3])
def test_tprs_expands_a_missing_value_to_a_nan_row(n_features):
"""The two-feature kernel used to map a NaN distance to 0, turning a missing
coordinate into an all-zero row; every input dimension now gives NaN, as the
other spline families do."""
rng = np.random.default_rng(0)
X = rng.uniform(size=(80, n_features))
transformer = ThinPlateSplineTransformer(n_components=5, random_state=0).fit(X)
probe = X[:3].copy()
probe[1, 0] = np.nan

out = transformer.transform(probe)

assert np.isnan(out[1]).all()
np.testing.assert_allclose(out[[0, 2]], transformer.transform(X[[0, 2]]), rtol=1e-12, atol=1e-12)
5 changes: 3 additions & 2 deletions tests/integration/test_edge_case_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -84,9 +84,10 @@ def _factory(name):
ALL_FAMILIES = CONSTANT_RAISES + CONSTANT_GRACEFUL

# Families that let missing values pass through the basis (NaN in -> NaN row out).
# The B/M/I splines instead clip a missing value to the fitted boundary, so they
# are intentionally excluded here.
NAN_PROPAGATING = [
"BSpline",
"MSpline",
"ISpline",
"RBF",
"ReLU",
"Sigmoid",
Expand Down
15 changes: 15 additions & 0 deletions tests/integration/test_missing_policy.py
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,21 @@ def test_propagate_lets_nan_through(frame_with_nan, y):
assert np.isnan(out).any()


@pytest.mark.parametrize("method", ["bspline", "mspline", "ispline"])
def test_propagate_expands_a_missing_value_to_a_nan_basis_row(method):
"""The B/M/I splines encoded a missing value as a finite all-zero row, which for
the I-spline is exactly the row of the smallest observed value."""
rng = np.random.default_rng(0)
frame = pd.DataFrame({"x": rng.uniform(0, 10, 300)})
frame.loc[0, "x"] = np.nan
pre = Preprocessor(
numerical_method=method, missing_policy="propagate", target_aware=False, placement_strategy="uniform"
).fit(frame, rng.normal(size=300))
out = np.asarray(pre.transform(frame, return_array=True))
assert np.isnan(out[0]).all()
assert np.isfinite(out[1:]).all()


# --- impute --------------------------------------------------------------------


Expand Down
Loading