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
14 changes: 8 additions & 6 deletions docs/core_concepts/target_awareness.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,14 +80,16 @@ held-out fold, so every training row is transformed by a model that never saw it
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;
fit and refits only the target-aware representations and subsequent pipeline steps. Column
types, target-free blocks and their category vocabularies, imputers, scalers before the
representation, and missing-indicator branches are shared. Target-free 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.
Missing indicators stay as raw columns next to the representation; they are not expanded into
basis functions and do not disappear when a fold's training rows contain no missing values.
Each refitted block must still retain its all-data output width. If a representation's
data-dependent sizing changes that width, cross-fitting raises an error instead of mixing
incompatible feature layouts.

```python
import numpy as np
Expand Down
65 changes: 55 additions & 10 deletions pretab/compose/inspection.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,13 @@
"""

import copy
from typing import Any
from typing import Any, cast

import numpy as np
from sklearn.base import clone
from sklearn.pipeline import FeatureUnion, Pipeline

from ..core._typing import TransformerLike
from ..core.logging import get_logger
from ..core.representation import FeatureLineage
from .registry import TRANSFORMER_REGISTRY
Expand All @@ -28,6 +30,7 @@
"clean_feature_names",
"feature_names_out",
"get_output_slices",
"refit_block_representation",
"representation_leaf",
]

Expand Down Expand Up @@ -364,20 +367,25 @@ def build_transformer_summary(numerical_info, categorical_info, embedding_info):
}


def _resolve_block_representation(pipeline, columns):
"""Return ``(family, component, uses_target, is_interaction)`` for a block.
def _locate_block_representation(pipeline, columns):
"""Return ``(step_index, (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), 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.
inputs; with None the step names its own. ``step_index`` is that step's
position in ``pipeline.steps`` (0 for a bare transformer), or None when the
block has no representation step. Known scikit-learn names are a fallback:
trailing scalers must not hide a representation's declared target use.
"""
steps = pipeline.steps if hasattr(pipeline, "steps") else [("_", pipeline)]
for step_name, transformer in reversed(steps):
legacy_step = None
for index in reversed(range(len(steps))):
step_name, transformer = steps[index]
if hasattr(transformer, "get_representation_spec"):
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
return index, (spec.family, spec.component_kind, spec.uses_target, spec.is_interaction)
registered = TRANSFORMER_REGISTRY.get(step_name)
if (
registered is not None
Expand All @@ -389,11 +397,16 @@ def _resolve_block_representation(pipeline, columns):
# 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:
return index, (step_name, component, uses_target, registered.is_multivariate)
if step_name in _STEP_FAMILY and legacy_step is None:
family, component = _STEP_FAMILY[step_name]
return family, component, False, False
return "passthrough", "raw", False, False
legacy_step = index, (family, component, False, False)
return legacy_step if legacy_step is not None else (None, ("passthrough", "raw", False, False))


def _resolve_block_representation(pipeline, columns):
"""Return ``(family, component, uses_target, is_interaction)`` for a block."""
return _locate_block_representation(pipeline, columns)[1]


def block_uses_target(transformer) -> bool:
Expand All @@ -408,6 +421,38 @@ def block_uses_target(transformer) -> bool:
return bool(_resolve_block_representation(representation, None)[2])


def refit_block_representation(transformer, X, y) -> TransformerLike:
"""Return a copy of a fitted per-column block whose representation is refit on ``(X, y)``.

Only the representation step and the steps after it are refit. The steps
before it (the imputer with its missing indicator, scalers) never use the
target, so they are kept from the all-data fit and transform ``X`` for the
refit: a ``SimpleImputer(add_indicator=True)`` refit on rows without missing
values would drop its indicator column and so change the block's width. For
a separate-state union the missing branch is kept as well. The fitted
``transformer`` itself is left untouched.
"""
separate_state = _separate_state_branches(transformer)
if separate_state is not None:
representation = refit_block_representation(separate_state[0], X, y)
union = copy.copy(transformer)
union.transformer_list = [
(name, representation if name == "representation" else branch)
for name, branch in transformer.transformer_list
]
return union
index = _locate_block_representation(transformer, None)[0]
if not isinstance(transformer, Pipeline) or index is None or index == 0:
refit = cast(TransformerLike, clone(transformer))
refit.fit(X, y)
return refit
refit = cast(Pipeline, clone(transformer[index:]))
refit.fit(transformer[:index].transform(X), y)
block = copy.copy(transformer)
block.steps = [*transformer.steps[:index], *refit.steps]
return cast(TransformerLike, block)


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
17 changes: 10 additions & 7 deletions pretab/core/supervised.py
Original file line number Diff line number Diff line change
Expand Up @@ -125,12 +125,14 @@ 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. 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 them. For a :class:`~pretab.Preprocessor`, only its target-aware
representations and subsequent steps are refit per fold. Column types,
target-free blocks and their vocabularies, imputers, scalers before the
representation and missing-indicator branches come from the all-data fit.
Target-free feature values match :meth:`transform`; target-aware values
exclude the held-out targets. 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
unchanged (each fold is a row subset), preserving column names, dtypes and index labels. 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 @@ -227,8 +229,9 @@ def fit_transform(self, X, y=None):
raise IncompatibleParamsError(
"Cross-fitting requires a fixed output width across folds; expected "
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."
"depends on the rows it is fit on (e.g. adaptive sizing, or category / "
"indicator columns learned from the data); configure it to produce the "
"same columns on every fold."
)
out[test_idx] = fold_out
finally:
Expand Down
20 changes: 12 additions & 8 deletions pretab/preprocessor.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
build_transformer_summary,
feature_names_out,
get_output_slices,
refit_block_representation,
representation_leaf,
)
from .compose.output import (
Expand Down Expand Up @@ -1118,16 +1119,20 @@ def estimate_memory(self, X) -> int:
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)``.
"""Return a copy of this fit whose target-aware representations 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
features. Only the representations that consume the target are refit on
the fold. Column types, target-free blocks and their vocabularies, and
preprocessing before the representation (imputers and scalers) are
shared with this all-data fit. Missing-indicator branches are shared too.
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``.
integer codes and one-hot columns between the folds and ``transform``;
refitting a block's missing indicator would drop its column on a fold
without missing values.
"""
check_is_fitted(self)
# Each block sees the fold rows exactly as the internal ColumnTransformer
Expand All @@ -1138,16 +1143,15 @@ def _cross_fit_fold(self, X, y):
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)
fold_transformer = refit_block_representation(transformer, 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."
"configure the representation to produce the same columns on every fold."
)
column_transformer.transformers_.append((name, fold_transformer, columns))
fold = copy.copy(self)
Expand Down
Loading
Loading