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
10 changes: 10 additions & 0 deletions docs/core_concepts/target_awareness.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,16 @@ held-out fold, so every training row is transformed by a model that never saw it
`transform` on genuinely new data (a validation or test set) instead uses one model fit on all
the training data, since there is no leakage risk there.

A wrapped `Preprocessor` is not refit from scratch on each fold: every fold reuses its all-data
fit and refits only the blocks whose representations use `y`. Column types and the blocks that
do not use `y`, including their category vocabularies, are shared. Their out-of-fold values match `transform` exactly;
target-aware values can differ because they exclude the held-out targets.

The entire target-aware block is currently refit, including its imputer and missing-indicator
branch. Each refitted block must retain its all-data output width. If adaptive sizing or
fold-specific missing-indicator columns change that width, cross-fitting raises an error
instead of mixing incompatible feature layouts.

```python
import numpy as np

Expand Down
34 changes: 31 additions & 3 deletions pretab/compose/inspection.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,13 @@

from ..core.logging import get_logger
from ..core.representation import FeatureLineage
from .registry import TRANSFORMER_REGISTRY

logger = get_logger(__name__)

__all__ = [
"block_name",
"block_uses_target",
"build_feature_info",
"build_feature_lineage",
"build_transformer_summary",
Expand Down Expand Up @@ -366,20 +368,46 @@ def _resolve_block_representation(pipeline, columns):
"""Return ``(family, component, uses_target, is_interaction)`` for a block.

The representation-bearing step is the last pipeline step exposing a
``get_representation_spec`` (a PreTab transformer) or a known scikit-learn
step name; helper steps such as imputers and float casts are skipped.
``get_representation_spec`` (a PreTab transformer), a known scikit-learn
step name, or a registered method that consumes the target; helper steps
such as imputers and float casts are skipped. ``columns`` names the spec's
inputs; with None the step names its own.
"""
steps = pipeline.steps if hasattr(pipeline, "steps") else [("_", pipeline)]
for step_name, transformer in reversed(steps):
if hasattr(transformer, "get_representation_spec"):
spec = transformer.get_representation_spec(input_features=list(columns))
spec = transformer.get_representation_spec(input_features=None if columns is None else list(columns))
return spec.family, spec.component_kind, spec.uses_target, spec.is_interaction
registered = TRANSFORMER_REGISTRY.get(step_name)
if (
registered is not None
and isinstance(transformer, registered.transformer_cls)
and registered.target_usage != "forbidden"
):
# A registered class without a RepresentationSpec (e.g. scikit-learn's
# TargetEncoder): its declared supervision says whether it used y, so
# cross-fitting refits it per fold instead of reusing the all-data fit.
uses_target = registered.target_usage == "required" or bool(getattr(transformer, "target_aware", False))
component = "category" if registered.is_categorical else "basis"
return step_name, component, uses_target, registered.is_multivariate
if step_name in _STEP_FAMILY:
family, component = _STEP_FAMILY[step_name]
return family, component, False, False
return "passthrough", "raw", False, False


def block_uses_target(transformer) -> bool:
"""Whether a fitted per-column block's representation consumed the target ``y``.

For a separate-state / missing-indicator union the representation branch decides; helper steps
such as imputers and scalers never use the target. The spec is read without
input names, since only its target use matters here.
"""
separate_state = _separate_state_branches(transformer)
representation = separate_state[0] if separate_state is not None else transformer
return bool(_resolve_block_representation(representation, None)[2])


def _passthrough_source(columns, offset, feature_names_in):
"""Resolve the source feature name for a passthrough / remainder column."""
column = columns[offset] if offset < len(columns) else columns[-1]
Expand Down
33 changes: 26 additions & 7 deletions pretab/core/supervised.py
Original file line number Diff line number Diff line change
Expand Up @@ -124,9 +124,13 @@ class CrossFittedTransformer(RepresentationSpecMixin, TransformerMixin, BaseEsti
----------
transformer : estimator
A supervised (target-aware) PreTab transformer to cross-fit, or an
estimator such as a :class:`~pretab.Preprocessor` or ``Pipeline`` built from
them. A pandas DataFrame ``X`` is passed to it unchanged (each fold is a row
subset), so column names, dtypes and index labels are preserved. Polars
estimator such as a :class:`~pretab.Preprocessor` or ``Pipeline`` built
from them. For a :class:`~pretab.Preprocessor`, only its target-aware blocks are refit per
fold: column types and the blocks that do not use ``y``, including their
category vocabularies, come from the all-data fit, so their out-of-fold features use exactly the
encoding of :meth:`transform`. Any other estimator is cloned and refit
from scratch on each fold. A pandas DataFrame ``X`` is passed through
unchanged (each fold is a row subset), so column names, dtypes and index labels are preserved. Polars
DataFrames are converted once to pandas before selecting fold rows.
n_folds : int, default=5
Number of cross-fitting folds. Must be at least 2.
Expand Down Expand Up @@ -193,6 +197,21 @@ def transform(self, X):
check_is_fitted(self, "estimator_")
return self.estimator_.transform(_as_2d(X))

def _fit_fold(self, X, y):
"""Return the model that encodes one held-out fold, fit on the other rows.

A wrapped estimator that implements ``_cross_fit_fold`` (the
:class:`~pretab.Preprocessor`) derives the fold model from ``estimator_``
and refits only its target-aware parts, so the out-of-fold features share
the encoding ``transform`` uses. Any other estimator is cloned and refit.
"""
cross_fit_fold = getattr(self.estimator_, "_cross_fit_fold", None)
if cross_fit_fold is not None:
return cast(TransformerLike, cross_fit_fold(X, y))
fold = cast(TransformerLike, clone(self.transformer))
fold.fit(X, y)
return fold

def fit_transform(self, X, y=None):
"""Fit and return leakage-free out-of-fold features for the training data."""
X_arr, y_arr = self._fit_full(X, y)
Expand All @@ -202,14 +221,14 @@ def fit_transform(self, X, y=None):
token = _cross_fit_active.set(True)
try:
for train_idx, test_idx in splitter.split(X_arr, y_arr):
fold = cast(TransformerLike, clone(self.transformer))
fold.fit(_take_rows(X_arr, train_idx), y_arr[train_idx])
fold = self._fit_fold(_take_rows(X_arr, train_idx), y_arr[train_idx])
fold_out = np.asarray(fold.transform(_take_rows(X_arr, test_idx)))
if fold_out.shape[1] != width:
raise IncompatibleParamsError(
"Cross-fitting requires a fixed output width across folds; expected "
f"{width}, got {fold_out.shape[1]}. Disable adaptive sizing on the "
"wrapped transformer."
f"{width}, got {fold_out.shape[1]}. The wrapped transformer's width "
"depends on the training rows (e.g. adaptive sizing); fix it, for "
"example by disabling adaptive sizing."
)
out[test_idx] = fold_out
finally:
Expand Down
8 changes: 7 additions & 1 deletion pretab/extension.py
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,13 @@ def register_representation(
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``.
class without one raises ``TypeError``. For a class without a
``get_representation_spec`` (a plain scikit-learn transformer such as
``TargetEncoder``), this declaration decides whether a fitted block used
``y``: ``"supervised"``, or ``"optional"`` with ``target_aware`` set on the
instance, counts as target-aware. The feature lineage then reports
``uses_target``, and :class:`~pretab.CrossFittedTransformer` refits the
block on every fold of a wrapped :class:`~pretab.Preprocessor`.
allowed_args : iterable of str, default=()
Constructor argument names the shared Preprocessor keyword arguments are
filtered down to for this method.
Expand Down
47 changes: 44 additions & 3 deletions pretab/preprocessor.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
import copy
import hashlib
import json
import logging
import os
import time
import warnings
from typing import Any, cast
from typing import cast

import numpy as np
from scipy import sparse as sp
Expand All @@ -23,6 +24,7 @@
)
from .compose.inspection import (
block_name,
block_uses_target,
build_feature_info,
build_feature_lineage,
build_transformer_summary,
Expand All @@ -39,13 +41,15 @@
validate_embedding_request,
)
from .compose.serialize import SCHEMA_VERSION, preprocessor_from_spec, preprocessor_to_spec
from .core._typing import TransformerLike
from .core.logging import configure_logging, get_logger
from .core.parameters import UNSET, validate_task
from .core.policy import RepresentationPolicy, apply_constant_policy
from .exceptions import (
ConfigWarning,
DataWarning,
FrozenRepresentationError,
IncompatibleParamsError,
OutputBudgetError,
PretabConfigError,
PretabDataError,
Expand Down Expand Up @@ -1113,6 +1117,43 @@ def estimate_memory(self, X) -> int:
n_rows, n_cols = self.estimate_output_shape(X)
return int(n_rows * n_cols * self._output_itemsize())

def _cross_fit_fold(self, X, y):
"""Return a copy of this fit whose target-aware blocks are refit on ``(X, y)``.

Used by :class:`~pretab.CrossFittedTransformer` for its out-of-fold
features. Only the blocks that consume the target are refit on the fold;
column types and target-free blocks, including their category vocabularies, are shared
with this all-data fit, so an out-of-fold row is encoded exactly like
``transform`` encodes it, except that no target-aware placement has seen
that row's target. Refitting the whole preprocessor per fold would
re-detect column types and relearn categories on fewer rows, shifting
integer codes and one-hot columns between the folds and ``transform``.
"""
check_is_fitted(self)
# Each block sees the fold rows exactly as the internal ColumnTransformer
# routed the training rows to it in ``fit``.
X_ct = self._column_transformer_input(self._align_input(X))
column_transformer = copy.copy(self.column_transformer_)
column_transformer.transformers_ = []
for name, transformer, columns in self.column_transformer_.transformers_:
fold_transformer = transformer
if name != "remainder" and block_uses_target(transformer):
fold_transformer = cast(TransformerLike, clone(transformer))
fold_transformer.fit(X_ct[list(columns)], y)
span = self.column_transformer_.output_indices_[name]
expected_width = span.stop - span.start
width = len(fold_transformer.get_feature_names_out(list(columns)))
if width != expected_width:
raise IncompatibleParamsError(
f"Cross-fitting requires a fixed output width for block {block_name(name, columns)!r}; "
f"expected {expected_width}, got {width}. The block's width depends on the training rows; "
"use a fixed-width representation and stable missing-indicator columns."
)
column_transformer.transformers_.append((name, fold_transformer, columns))
fold = copy.copy(self)
fold.column_transformer_ = column_transformer
return fold

def _reject_missing(self, X) -> None:
"""Raise when ``missing_policy="error"`` but ``X`` contains missing values."""
na_columns = [col for col in X.columns if X[col].isna().any()]
Expand Down Expand Up @@ -1144,7 +1185,7 @@ def _raise_for_empty_features(self, X, y, empty_features, config) -> None:
feature = empty[columns[0]]
is_numerical = feature in self.numerical_features_
try:
cast(Any, clone(transformer)).fit(X[columns], y)
cast(TransformerLike, clone(transformer)).fit(X[columns], y)
except PretabConfigError:
continue # a configuration problem, not one of the empty column
except ValueError as exc:
Expand All @@ -1155,7 +1196,7 @@ def _raise_for_empty_features(self, X, y, empty_features, config) -> None:
else np.resize(np.array(["a", "b"], dtype=object), len(X))
)
try:
cast(Any, clone(transformer)).fit(stand_in, y)
cast(TransformerLike, clone(transformer)).fit(stand_in, y)
except ValueError:
continue # the block fails with observed values too: not the emptiness
method = config.method_for(feature, is_numerical=is_numerical)
Expand Down
Loading
Loading