diff --git a/docs/tutorials/custom_representation.md b/docs/tutorials/custom_representation.md index 978f8c4..e791aac 100644 --- a/docs/tutorials/custom_representation.md +++ b/docs/tutorials/custom_representation.md @@ -71,7 +71,9 @@ The four class attributes are the declarative contract. `supervision` : `"unsupervised"`, `"optional"` (uses `y` only when `target_aware=True`), or `"supervised"` -(always needs `y`). +(always needs `y`). An `"optional"` class must take a `target_aware` constructor parameter: +`Preprocessor` sets it from its own `target_aware`, and registration rejects a class without +one. ```{tip} Implement `_output_sizes` to return the number of output columns each input contributes. The diff --git a/pretab/compose/factory.py b/pretab/compose/factory.py index f5cb114..c518edc 100644 --- a/pretab/compose/factory.py +++ b/pretab/compose/factory.py @@ -102,23 +102,24 @@ def _placement_kwargs(spec: TransformerSpec, kwargs): """Return the placement kwargs to inject for a method, honouring its capability. Mirrors the shared-placement contract: methods with optional target awareness - (feature maps and freely-placed knot splines) receive ``target_aware`` plus - the ``placement_strategy`` (when set); the always-target-aware ``ple`` receives - a supervised ``placement_strategy`` only when target-aware; the unsupervised-only - penalized splines receive an unsupervised ``placement_strategy`` only when not - target-aware. Methods without data-driven placement receive nothing. + (feature maps, freely-placed knot splines, and registered ``"optional"`` + representations) always receive ``target_aware``, which decides whether they + use ``y`` at all, plus the ``placement_strategy`` (when set) if they declare + placement strategies; the always-target-aware ``ple`` receives a supervised + ``placement_strategy`` only when target-aware; the unsupervised-only penalized + splines receive an unsupervised ``placement_strategy`` only when not + target-aware. Other methods without data-driven placement receive nothing. """ - if not spec.placement_strategies: - return {} - target_aware = bool(kwargs.get("target_aware", False)) placement_strategy = kwargs.get("placement_strategy") if spec.target_usage == "optional": out = {"target_aware": target_aware} - if placement_strategy is not None: + if placement_strategy is not None and spec.placement_strategies: out["placement_strategy"] = placement_strategy return out + if not spec.placement_strategies: + return {} if spec.target_usage == "required": if target_aware and placement_strategy in ("cart", "lightgbm"): return {"placement_strategy": placement_strategy} diff --git a/pretab/extension.py b/pretab/extension.py index e8107ed..64af86e 100644 --- a/pretab/extension.py +++ b/pretab/extension.py @@ -19,6 +19,7 @@ from __future__ import annotations +import inspect import warnings import numpy as np @@ -80,7 +81,9 @@ class BaseRepresentation(BasePreTabTransformer): supervision : {"unsupervised", "optional", "supervised"} How the representation uses the target ``y``. ``"supervised"`` mandates ``y`` at fit time; ``"optional"`` consumes it only when ``target_aware`` - is enabled. + is enabled, so an optional class must take a ``target_aware`` constructor + parameter (:class:`~pretab.Preprocessor` sets it from its own + ``target_aware``). """ representation_name: str | None = None @@ -110,6 +113,14 @@ def __init_subclass__(cls, **kwargs): cls._requires_y = cls.supervision == "supervised" +def _accepts_target_aware(cls) -> bool: + """Whether ``cls`` takes a ``target_aware`` constructor parameter.""" + try: + return "target_aware" in inspect.signature(cls.__init__).parameters + except (TypeError, ValueError): # no introspectable signature + return False + + def register_representation( name, cls, @@ -145,13 +156,17 @@ def register_representation( scope : {"univariate", "multivariate"}, optional Inferred from ``cls`` when omitted. supervision : {"unsupervised", "optional", "supervised"}, optional - Inferred from ``cls`` when omitted. + Inferred from ``cls`` when omitted. An ``"optional"`` class must take a + ``target_aware`` constructor parameter: ``Preprocessor`` always passes its + own ``target_aware``, so the class uses ``y`` only when that is True. A + class without one raises ``TypeError``. allowed_args : iterable of str, default=() Constructor argument names the shared Preprocessor keyword arguments are filtered down to for this method. placement_strategies : iterable of str, default=() Placement strategies the method honours (empty for methods without - data-driven placement). + data-driven placement). ``Preprocessor`` passes its ``placement_strategy`` + only to a method that declares strategies. supports_adaptive_resolution : bool, default=False Whether the method can size its output dimension from the data. preprocessor_compatible : bool, default=True @@ -186,6 +201,13 @@ def register_representation( raise ValueError(f"scope must be one of {sorted(_VALID_SCOPES)}, got {scope!r}") if supervision not in _VALID_SUPERVISION: raise ValueError(f"supervision must be one of {sorted(_VALID_SUPERVISION)}, got {supervision!r}") + if supervision == "optional" and not _accepts_target_aware(cls): + raise TypeError( + f"{cls.__name__} is registered with supervision='optional' but its constructor has no " + "target_aware parameter. An optionally supervised representation uses y only when " + "target_aware=True, and Preprocessor sets it from its own target_aware: add the " + "parameter, or register the class as 'unsupervised' or 'supervised'." + ) spec = TransformerSpec( name=name, diff --git a/tests/compose/test_factory.py b/tests/compose/test_factory.py index 2aa614d..f271615 100644 --- a/tests/compose/test_factory.py +++ b/tests/compose/test_factory.py @@ -12,7 +12,7 @@ get_categorical_transformer_steps, get_numerical_transformer_steps, ) -from pretab.compose.registry import get_spec +from pretab.compose.registry import TransformerSpec, get_spec from pretab.exceptions import ConfigWarning, InvalidParamError @@ -165,6 +165,14 @@ def test_placement_absent_when_method_has_no_strategies(): assert _placement_kwargs(spec, {"target_aware": True, "placement_strategy": "cart"}) == {} +def test_placement_optional_without_strategies_still_forwards_target_aware(): + # e.g. a registered supervision="optional" representation with no placement + # strategies: target_aware decides whether it uses y, placement does not apply. + spec = TransformerSpec(name="custom", transformer_cls=object, target_usage="optional") + assert _placement_kwargs(spec, {"target_aware": False, "placement_strategy": "uniform"}) == {"target_aware": False} + assert _placement_kwargs(spec, {"target_aware": True, "placement_strategy": "cart"}) == {"target_aware": True} + + # --------------------------------------------------------------------------- # # ColumnTransformer assembly # --------------------------------------------------------------------------- # diff --git a/tests/extension/test_registration_discovery.py b/tests/extension/test_registration_discovery.py index fad8f5e..e8279df 100644 --- a/tests/extension/test_registration_discovery.py +++ b/tests/extension/test_registration_discovery.py @@ -59,6 +59,63 @@ def _output_sizes(self): return [1] * self.n_features_in_ +class _SplitAtTarget(BaseRepresentation): + """Optionally supervised: split at the median, or (target-aware) where ``y`` peaks.""" + + representation_name = "split_reg" + feature_kind = "numerical" + supervision = "optional" + + def __init__(self, target_aware=True): + self.target_aware = target_aware + + def fit(self, X, y=None): + X = self._validate(X, reset=True) + self.used_y_ = bool(self.target_aware and y is not None) + self.threshold_ = X[np.argmax(np.asarray(y)), 0] if self.used_y_ else np.median(X[:, 0]) + return self + + def transform(self, X): + check_is_fitted(self, "threshold_") + return (self._validate(X, reset=False) > self.threshold_).astype(float) + + def _output_sizes(self): + return [1] * self.n_features_in_ + + +class _SplitAtTargetOffByDefault(_SplitAtTarget): + def __init__(self, target_aware=False): + super().__init__(target_aware=target_aware) + + +@pytest.mark.parametrize("cls", [_SplitAtTarget, _SplitAtTargetOffByDefault]) +def test_register_optional_representation_follows_preprocessor_target_aware(cls): + # Whatever the class default, the Preprocessor's target_aware decides whether + # the representation uses y (no placement strategies are declared). + register_representation("split_reg", cls) + X = pd.DataFrame({"x": np.linspace(0.0, 1.0, 50)}) + y = np.sin(X["x"] * 6) + for target_aware, placement in [(False, "uniform"), (True, "cart")]: + pre = Preprocessor(numerical_method="split_reg", target_aware=target_aware, placement_strategy=placement) + pre.fit(X, y) + + step = pre.column_transformer_.named_transformers_["num_x"].named_steps["split_reg"] + assert step.target_aware is target_aware + assert step.used_y_ is target_aware + assert [record.uses_target for record in pre.get_feature_lineage()] == [target_aware] + + +def test_register_optional_representation_requires_target_aware_parameter(): + class _NoTargetAware(_Square): + supervision = "optional" + + with pytest.raises(TypeError, match="target_aware"): + register_representation("optional_reg", _NoTargetAware) + with pytest.raises(TypeError, match="target_aware"): + register_representation("optional_reg", _Square, supervision="optional") + assert "optional_reg" not in registry.TRANSFORMER_REGISTRY + + def test_register_makes_method_selectable_and_discoverable(): register_representation("square_reg", _Square) assert "square_reg" in registry.NUMERICAL_METHODS