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: 3 additions & 1 deletion docs/tutorials/custom_representation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 10 additions & 9 deletions pretab/compose/factory.py
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
28 changes: 25 additions & 3 deletions pretab/extension.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@

from __future__ import annotations

import inspect
import warnings

import numpy as np
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
10 changes: 9 additions & 1 deletion tests/compose/test_factory.py
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down Expand Up @@ -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
# --------------------------------------------------------------------------- #
Expand Down
57 changes: 57 additions & 0 deletions tests/extension/test_registration_discovery.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading