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
5 changes: 3 additions & 2 deletions docs/representations/spline_expansions.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,9 @@ knot positions by `placement_strategy` (see
Without explicit knots, `output_dim` is the number of output columns for a univariate spline
**per input feature**, not the total. A `(n_samples, 3)` input produces
`(n_samples, 3 * output_dim)` output (plus one extra column per feature if
`include_bias=True`). Feature names are suffixed per input, for example `x0_bs0, x0_bs1, ...`
for a B-spline on column `x0`. For B/M/I splines with explicit `knot_locations`, a feature
`include_bias=True`). Feature names are suffixed per input, for example `age_bs0, age_bs1, ...`
for a B-spline fitted on a DataFrame column `age` (`x0_bs0, x0_bs1, ...` for array input).
For B/M/I splines with explicit `knot_locations`, a feature
with `K` retained unique interior knots instead gets `K + degree + 1` non-bias columns;
different feature ranges can therefore produce different widths.
```
Expand Down
4 changes: 3 additions & 1 deletion docs/tutorials/custom_representation.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ A complete, installable version of this example lives in the repository under

`BaseRepresentation` gives you the shared scikit-learn contract: NaN-aware validation, estimator
tags, `get_feature_names_out`, and a typed `RepresentationSpec`. You implement `fit`,
`transform`, and one sizing hook, and declare a small amount of metadata.
`transform`, and one sizing hook, and declare a small amount of metadata. Fitted on a DataFrame,
`self._validate` records the column names as `feature_names_in_` and checks them at `transform`,
and the output names use them (`length_f0` rather than `x0_f0`).

```python
import numpy as np
Expand Down
26 changes: 23 additions & 3 deletions pretab/compose/inspection.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
from typing import Any, cast

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

Expand Down Expand Up @@ -184,6 +185,19 @@ def _separate_state_branches(transformer):
return branches["representation"], branches["missing"]


def _probe_input(step, value):
"""Return a one-row probe input for measuring a fitted step's output width.

A step fitted directly on the ColumnTransformer's DataFrame column records
``feature_names_in_`` and, like scikit-learn, warns on input without feature
names, so its probe is a DataFrame carrying the fitted names.
"""
names = getattr(step, "feature_names_in_", None)
if names is None:
return np.full((1, 1), value)
return pd.DataFrame(np.full((1, len(names)), value), columns=names)


def representation_leaf(transformer):
"""Return the last step of a fitted per-column block's representation.

Expand Down Expand Up @@ -250,7 +264,7 @@ def build_feature_info(column_transformer, *, embeddings, embedding_dimensions):
):
last_step = representation_pipeline.steps[-1][1]
if hasattr(last_step, "transform"):
dummy_input = np.zeros((1, 1)) + 1e-05
dummy_input = _probe_input(last_step, 1e-05)
try:
transformed_feature = last_step.transform(dummy_input)
dimension = transformed_feature.shape[1]
Expand Down Expand Up @@ -298,7 +312,7 @@ def build_feature_info(column_transformer, *, embeddings, embedding_dimensions):
else:
last_step = representation_pipeline.steps[-1][1]
if hasattr(last_step, "transform"):
dummy_input = np.zeros((1, 1))
dummy_input = _probe_input(last_step, 0.0)
try:
transformed_feature = last_step.transform(dummy_input)
dimension = transformed_feature.shape[1]
Expand Down Expand Up @@ -384,7 +398,13 @@ def _locate_block_representation(pipeline, columns):
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))
# A step fitted on more inputs than the block has columns (behind the
# imputer's built-in missing indicator) names its own inputs; its
# get_feature_names_out rejects the block's shorter column list.
input_features = None
if columns is not None and getattr(transformer, "n_features_in_", len(columns)) == len(columns):
input_features = list(columns)
spec = transformer.get_representation_spec(input_features=input_features)
return index, (spec.family, spec.component_kind, spec.uses_target, spec.is_interaction)
registered = TRANSFORMER_REGISTRY.get(step_name)
if (
Expand Down
31 changes: 19 additions & 12 deletions pretab/compose/serialize.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
from ..core.parameters import UNSET
from ..core.policy import RepresentationPolicy
from ..core.representation import FeatureLineage, RepresentationSpec
from ..exceptions import PretabError, PretabSerializationError
from ..exceptions import PretabSerializationError
from ..placement.base import PlacementResult
from .inspection import representation_leaf
from .registry import TransformerSpec
Expand Down Expand Up @@ -228,12 +228,17 @@ def _library_versions() -> dict:


def _representation_summary(preprocessor) -> list:
"""Best-effort declarative per-representation summary (family/columns/locations).

One entry per block whose representation ends in a PreTab transformer. For a
missing-indicator / separate-state block that is the last step of its
representation branch (see :func:`~pretab.compose.inspection.representation_leaf`),
not the union itself.
"""Declarative per-representation summary (family/columns/locations).

One entry per block whose representation ends in a PreTab transformer, built from its
:class:`RepresentationSpec` with the block's column names as input features
(as the feature lineage does). For a missing-indicator / separate-state block,
this is the last step of its representation branch (see
:func:`~pretab.compose.inspection.representation_leaf`), not the union itself.
Blocks whose representation ends in a step without
``get_representation_spec`` (scikit-learn scalers and encoders, embeddings)
have no entry. The steps are fitted, so a spec that fails to build is a bug:
its error propagates instead of silently dropping the entry.
"""
summary: list = []
column_transformer = getattr(preprocessor, "column_transformer_", None)
Expand All @@ -246,11 +251,13 @@ def _representation_summary(preprocessor) -> list:
spec_fn = getattr(leaf, "get_representation_spec", None)
if spec_fn is None:
continue
try:
entry = spec_fn().to_dict()
except (PretabError, ValueError, AttributeError, TypeError, KeyError):
continue
entry["columns"] = [str(col) for col in columns]
block_columns = [str(col) for col in columns]
# A leaf with more inputs than its block has columns (one fitted behind
# the imputer's built-in missing indicator, add_missing_indicator=True)
# names its own inputs.
fits_block = getattr(leaf, "n_features_in_", len(block_columns)) == len(block_columns)
entry = spec_fn(input_features=block_columns if fits_block else None).to_dict()
entry["columns"] = block_columns
summary.append(entry)
return summary

Expand Down
41 changes: 29 additions & 12 deletions pretab/core/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,11 @@
from sklearn.base import BaseEstimator, TransformerMixin
from sklearn.utils.validation import check_is_fitted

from ..exceptions import invalid_param_error
from .adaptive import AdaptiveResolutionMixin
from .parameters import AliasResolverMixin
from .policy import RepresentationPolicy, apply_constant_policy
from .representation import RepresentationSpecMixin
from .validation import validate_2d_allow_nan
from .validation import resolve_input_features, validate_2d_allow_nan

__all__ = ["BasePreTabTransformer"]

Expand All @@ -37,6 +36,11 @@ class BasePreTabTransformer(
means "inherit the shared policy"); :meth:`_resolved_policy` merges them.
Transformers that expose their own ``policy`` constructor parameter let a
caller override those defaults per-instance; see :meth:`_resolved_policy`.

Like scikit-learn's transformers, a transformer fitted on a DataFrame with
string column names records ``feature_names_in_``, names its outputs after the
columns, and checks the columns at ``transform``: renamed or reordered columns
raise a ``ValueError``, and input without column names warns.
"""

_allow_nan: bool = True
Expand Down Expand Up @@ -93,17 +97,30 @@ def _output_sizes(self) -> list[int]:
raise NotImplementedError

def get_feature_names_out(self, input_features=None):
"""Return output feature names of the form ``{feature}_{suffix}{j}``."""
"""Return output feature names of the form ``{feature}_{suffix}{j}``.

Parameters
----------
input_features : array-like of str or None, default=None
Input feature names. ``None`` uses ``feature_names_in_`` when the
transformer was fitted on a DataFrame, else ``x0, x1, ...``. Explicit
names need one entry per input feature and, after a DataFrame fit,
must equal ``feature_names_in_``.

Returns
-------
feature_names_out : ndarray of str
One name per output column.

Raises
------
InvalidParamError
If ``input_features`` does not have one entry per input feature.
ValueError
If ``input_features`` differs from ``feature_names_in_``.
"""
check_is_fitted(self, "n_features_in_")
if input_features is None:
input_features = [f"x{i}" for i in range(self.n_features_in_)]
elif len(input_features) != self.n_features_in_:
raise invalid_param_error(
type(self).__name__,
"get_feature_names_out.input_features",
len(input_features),
f"must have exactly {self.n_features_in_} entries (one per input feature)",
)
input_features = resolve_input_features(self, input_features)
suffix = self._feature_suffix()
names = []
for feature, n_cols in zip(input_features, self._output_sizes(), strict=False):
Expand Down
14 changes: 8 additions & 6 deletions pretab/core/representation.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@
import numpy as np
from sklearn.utils.validation import check_is_fitted

from .validation import resolve_input_features

__all__ = [
"FeatureLineage",
"RepresentationSpec",
Expand Down Expand Up @@ -297,19 +299,19 @@ def get_representation_spec(self, input_features=None) -> RepresentationSpec:
Parameters
----------
input_features : list of str or None
Names of the input features. When ``None``, names of the form
``x0, x1, ...`` are generated.
Names of the input features, resolved as in ``get_feature_names_out``:
explicit names need one entry per input feature and, after a fit on
named (DataFrame) columns, must equal ``feature_names_in_``. When
``None``, ``feature_names_in_`` is used if it was recorded at fit,
else names of the form ``x0, x1, ...`` are generated.

Returns
-------
RepresentationSpec
The representation metadata describing the produced columns.
"""
check_is_fitted(self, "n_features_in_")
if input_features is None:
inputs = tuple(f"x{i}" for i in range(self.n_features_in_))
else:
inputs = tuple(str(feature) for feature in input_features)
inputs = tuple(resolve_input_features(self, input_features))
output_features = tuple(str(name) for name in self.get_feature_names_out(list(inputs)))
location_kind, locations = self._representation_locations()
periodic, period = self._representation_periodic()
Expand Down
37 changes: 30 additions & 7 deletions pretab/core/validation.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,35 @@

import sys
import warnings
from typing import Literal
from typing import Literal, cast

import numpy as np
import pandas as pd
from sklearn.utils.validation import check_array
from sklearn.utils.validation import _check_feature_names, _check_feature_names_in, check_array

from ..exceptions import DataWarning, IncompatibleParamsError, PretabDataError
from ..exceptions import DataWarning, IncompatibleParamsError, PretabDataError, invalid_param_error

__all__ = ["is_polars_frame", "polars_to_pandas", "single_target", "validate_2d_allow_nan"]
__all__ = ["is_polars_frame", "polars_to_pandas", "resolve_input_features", "single_target", "validate_2d_allow_nan"]


def resolve_input_features(estimator, input_features) -> list:
"""Return the input feature names that a transformer's output names are built from.

Follows scikit-learn's ``get_feature_names_out`` contract: explicit
``input_features`` need one entry per input feature and, when the estimator was
fitted on named (DataFrame) columns, must equal ``feature_names_in_``; ``None``
falls back to ``feature_names_in_``, else to ``x0, x1, ...``.
"""
n_features_in_ = getattr(estimator, "n_features_in_", None)
if input_features is not None and n_features_in_ is not None and len(input_features) != n_features_in_:
raise invalid_param_error(
type(estimator).__name__,
"get_feature_names_out.input_features",
len(input_features),
f"must have exactly {n_features_in_} entries (one per input feature)",
)
names = cast(np.ndarray, _check_feature_names_in(estimator, input_features))
return [str(name) for name in names]


def single_target(y, estimator: str, *, fix: str | None = None) -> np.ndarray:
Expand Down Expand Up @@ -112,9 +132,11 @@ def validate_2d_allow_nan(X, *, allow_nan: bool = True, reset: bool, estimator):
When True, missing values are preserved so a later imputer can handle
them; when False, NaN/inf values raise as usual.
reset : bool
When True (during ``fit``) record ``estimator.n_features_in_``; when
False (during ``transform``) verify the feature count matches the value
seen at ``fit`` and raise otherwise.
When True (during ``fit``) record ``estimator.n_features_in_`` and, for a
DataFrame, ``estimator.feature_names_in_``; when False (during
``transform``) verify the feature count matches the value seen at ``fit``
and raise otherwise, and check the column names as scikit-learn does
(renamed or reordered columns raise).
estimator : object
The calling transformer; used for the ``n_features_in_`` side effect and
the transform-time feature-count check.
Expand All @@ -124,6 +146,7 @@ def validate_2d_allow_nan(X, *, allow_nan: bool = True, reset: bool, estimator):
X : ndarray of shape (n_samples, n_features)
The validated float array.
"""
_check_feature_names(estimator, X, reset=reset)
input_shape = getattr(X, "shape", None)
original_dim = input_shape[1] if input_shape is not None and len(input_shape) == 2 else None
ensure_all_finite: Literal["allow-nan"] | bool = "allow-nan" if allow_nan else True
Expand Down
29 changes: 22 additions & 7 deletions pretab/embedding/language.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
from typing import cast

import numpy as np
from sklearn.base import BaseEstimator, TransformerMixin
from sklearn.utils.validation import check_is_fitted
from sklearn.utils.validation import _check_feature_names, _check_feature_names_in, check_is_fitted

from ..exceptions import OptionalDependencyError, PretabConfigError, PretabDataError

Expand All @@ -27,6 +29,10 @@ class LanguageEmbeddingTransformer(TransformerMixin, BaseEstimator):
``fit`` from ``model`` or by loading ``model_name``.
n_features_in_ : int
Number of input features seen during ``fit``.
feature_names_in_ : ndarray of str
Names of the input columns seen during ``fit``. Defined only when ``X``
was a DataFrame with string column names; ``transform`` then requires
the same columns in the same order.
embedding_dim_ : int
Dimensionality of the embeddings produced by ``model_``.

Expand Down Expand Up @@ -76,6 +82,7 @@ def fit(self, X, y=None):
self : object
Fitted transformer.
"""
_check_feature_names(self, X, reset=True)
X = np.asarray(X)
self.n_features_in_ = X.shape[1] if X.ndim > 1 else 1
self.model_ = self._resolve_model()
Expand Down Expand Up @@ -115,6 +122,7 @@ def transform(self, X):
"""
if getattr(self, "model_", None) is None:
raise PretabConfigError("Model is not initialized. Call `fit` before `transform`.")
_check_feature_names(self, X, reset=False)

# Normalise to a 2D array of strings so each column is encoded on its own
# and the row count is preserved (a flat encode would return
Expand Down Expand Up @@ -143,16 +151,23 @@ def get_feature_names_out(self, input_features=None):

Parameters
----------
input_features : array-like of str or None
Input feature names. When ``None``, names of the form ``x0, x1, ...``
are generated.
input_features : array-like of str or None, default=None
Input feature names. ``None`` uses ``feature_names_in_`` when the
transformer was fitted on a DataFrame, else ``x0, x1, ...``. Explicit
names need one entry per input feature and, after a DataFrame fit,
must equal ``feature_names_in_``.

Returns
-------
feature_names_out : ndarray of str, shape (n_features_in_ * embedding_dim_,)

Raises
------
ValueError
If ``input_features`` does not have one entry per input feature, or
differs from ``feature_names_in_``.
"""
check_is_fitted(self, ["n_features_in_", "embedding_dim_"])
if input_features is None:
input_features = [f"x{i}" for i in range(self.n_features_in_)]
names = [f"{col}_emb{j}" for col in input_features for j in range(self.embedding_dim_)]
columns = cast(np.ndarray, _check_feature_names_in(self, input_features))
names = [f"{col}_emb{j}" for col in columns for j in range(self.embedding_dim_)]
return np.asarray(names, dtype=object)
Loading
Loading