Skip to content
Open
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
33 changes: 32 additions & 1 deletion docs/core_concepts/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,35 @@ Don't infer the resolved method per column from the constructor arguments alone.
[Fit-time logging](outputs_and_inspection.md#fit-time-logging).
```

## Representation parameters

Use `representation_params` to set options for every feature that selects a given
representation. To override those options for one feature, give its
`feature_preprocessing` entry a `method` and the options to change.

```python
pre = Preprocessor(
numerical_method="quantile",
representation_params={
"quantile": {"n_quantiles": 128, "output_distribution": "normal"},
},
feature_preprocessing={
"income": {"method": "quantile", "n_quantiles": 32},
"city": {"method": "one-hot", "drop": "first"},
},
)
```

`income` uses 32 quantiles and inherits the normal output distribution. Other
quantile features use 128 quantiles. `city` drops the first category from its
one-hot output. Method names and aliases follow the same rules as the global
method selectors.

PreTab applies shared constructor defaults first, then `representation_params`,
then options for the individual feature. It validates explicit options against
the representation's registered `allowed_args`. `task`, `target_aware`, and
`placement_strategy` are set on the `Preprocessor` and apply across features.

## Presets

Presets are transparent, named bundles of parameters for common intents. They set the same
Expand Down Expand Up @@ -218,7 +247,8 @@ The resolution order is deterministic. Later layers win.
1. Library defaults.
2. A `preset`, if given.
3. Explicit constructor arguments (`numerical_method`, `output_dim`, and so on).
4. Per-column `feature_preprocessing` entries, for the columns they name.
4. `representation_params`, for the methods they name.
5. Per-column `feature_preprocessing` entries, for the columns they name.

```{warning}
Configuration is validated at `fit` time, not silently coerced. An invalid combination, such
Expand All @@ -237,6 +267,7 @@ in depth.
| ------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| `numerical_method`, `categorical_method` | `"ple"`, `"int"` | this page |
| `feature_preprocessing` | `None` | this page |
| `representation_params` | `None` | this page |
| `output_dim` | `7` | [Resolution and placement](resolution_and_placement.md) |
| `adaptive`, `min_output_dim`, `max_output_dim` | `False`, `5`, `10` | [Resolution and placement](resolution_and_placement.md) |
| `target_aware`, `placement_strategy` | `True`, `"cart"` | [Target awareness](target_awareness.md) |
Expand Down
67 changes: 67 additions & 0 deletions pretab/compose/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

from __future__ import annotations

from collections.abc import Mapping
from dataclasses import dataclass

from ..core.parameters import validate_placement, validate_task
Expand All @@ -25,6 +26,7 @@
CATEGORICAL_METHODS,
NUMERICAL_ALIASES,
NUMERICAL_METHODS,
get_spec,
resolve_method,
)

Expand All @@ -33,6 +35,7 @@
# Valid values for the high-level ``missing_policy`` orchestration knob. ``None``
# keeps the explicit imputation parameters authoritative (historical behaviour).
MISSING_POLICIES = frozenset({"error", "propagate", "impute", "impute_with_indicator", "separate_state"})
_SHARED_PLACEMENT_PARAMS = frozenset({"task", "target_aware", "placement_strategy"})


def _normalize_method(method, canonical, aliases) -> str:
Expand All @@ -42,6 +45,49 @@ def _normalize_method(method, canonical, aliases) -> str:
return resolve_method(method, canonical, aliases)


def _validate_representation_params(method, params, source):
"""Check explicit overrides against the same registry used by the factory."""
allowed = set(get_spec(method).allowed_args) - _SHARED_PLACEMENT_PARAMS
unknown = params.keys() - allowed
if unknown:
raise invalid_param_error(
"Preprocessor",
source,
params,
f"unsupported parameters for {method!r}: {sorted(unknown, key=str)}",
valid=allowed,
)


def _normalize_representation_params(overrides):
if overrides is None:
return {}
if not isinstance(overrides, Mapping):
raise invalid_param_error("Preprocessor", "representation_params", overrides, "must be a mapping")

normalized = {}
methods = NUMERICAL_METHODS.keys() | CATEGORICAL_METHODS
for name, params in overrides.items():
if not isinstance(name, str) or not isinstance(params, Mapping):
raise invalid_param_error(
"Preprocessor", "representation_params", overrides, "must map method names to parameter mappings"
)
method = resolve_method(name, NUMERICAL_METHODS, NUMERICAL_ALIASES)
if method not in NUMERICAL_METHODS:
method = resolve_method(name, CATEGORICAL_METHODS, CATEGORICAL_ALIASES)
if method not in methods or not get_spec(method).preprocessor_compatible:
raise invalid_param_error(
"Preprocessor", "representation_params", name, "must name a per-column method", valid=methods
)
if method in normalized:
raise invalid_param_error(
"Preprocessor", "representation_params", name, f"duplicates the settings for {method!r}"
)
_validate_representation_params(method, params, "representation_params")
normalized[method] = dict(params)
return normalized


@dataclass(frozen=True)
class PreprocessorConfig:
"""Frozen, normalized configuration derived from Preprocessor parameters.
Expand All @@ -54,6 +100,7 @@ class PreprocessorConfig:
numerical_method: str
categorical_method: str
feature_preprocessing: dict
representation_params: dict
output_dim: int
degree: int
target_aware: bool
Expand Down Expand Up @@ -96,6 +143,7 @@ def from_params(
add_missing_indicator,
missing_policy,
verbose,
representation_params=None,
) -> PreprocessorConfig:
"""Normalize and validate raw Preprocessor parameters into a config.

Expand All @@ -121,6 +169,7 @@ def from_params(
numerical_method=_normalize_method(numerical_method, NUMERICAL_METHODS, NUMERICAL_ALIASES),
categorical_method=_normalize_method(categorical_method, CATEGORICAL_METHODS, CATEGORICAL_ALIASES),
feature_preprocessing=dict(feature_preprocessing or {}),
representation_params=_normalize_representation_params(representation_params),
output_dim=output_dim,
degree=degree,
target_aware=target_aware,
Expand Down Expand Up @@ -159,8 +208,26 @@ def method_for(self, feature, *, is_numerical: bool) -> str:
"""
default = self.numerical_method if is_numerical else self.categorical_method
raw = self.feature_preprocessing.get(feature, default)
if isinstance(raw, Mapping):
raw = raw.get("method")
if not isinstance(raw, str):
raise invalid_param_error(
"Preprocessor", "feature_preprocessing", raw, f"column {feature!r} requires a string method name"
)
return self.resolve_numerical(raw) if is_numerical else self.resolve_categorical(raw)

def representation_for(self, feature, *, is_numerical: bool) -> tuple[str, dict]:
"""Resolve a column's method and merge shared and feature-specific options."""
method = self.method_for(feature, is_numerical=is_numerical)
params = self.representation_params.get(method, {})
override = self.feature_preprocessing.get(feature)
methods = NUMERICAL_METHODS if is_numerical else CATEGORICAL_METHODS
if isinstance(override, Mapping) and method in methods:
feature_params = {name: value for name, value in override.items() if name != "method"}
_validate_representation_params(method, feature_params, f"feature_preprocessing[{feature!r}]")
params = params | feature_params
return method, params

@property
def seed_kwargs(self) -> dict:
"""Return ``{"random_state": ...}`` only when a seed was explicitly set.
Expand Down
31 changes: 21 additions & 10 deletions pretab/compose/factory.py
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,8 @@ def get_numerical_transformer_steps(
imputer_kwargs: dict | None = None,
add_missing_indicator: bool = False,
scaling: str | None = None,
*,
representation_params: dict | None = None,
**kwargs,
):
"""Return the ordered ``(name, transformer)`` steps for a numerical ``method``."""
Expand Down Expand Up @@ -176,6 +178,7 @@ def get_numerical_transformer_steps(
spec = get_spec(method)
cls = spec.transformer_cls
filtered = _filter_kwargs(spec.allowed_args, kwargs)
filtered.update(representation_params or {})
placement = _placement_kwargs(spec, kwargs)

if method == "box-cox":
Expand All @@ -191,7 +194,7 @@ def get_numerical_transformer_steps(
# can sit outside their [5, 50] basis range); the legacy families keep
# their own wider bounds, so only clamp for B/M/I.
if method in _BMI_SPLINE_METHODS:
output_dim = kwargs.get("output_dim")
output_dim = spline_kwargs.get("output_dim")
if output_dim is not None:
spline_kwargs["output_dim"] = _clamp_spline_basis(output_dim)

Expand All @@ -211,6 +214,8 @@ def get_categorical_transformer_steps(
imputer_strategy: str = "most_frequent",
imputer_kwargs: dict | None = None,
add_missing_indicator: bool = False,
*,
representation_params: dict | None = None,
**kwargs,
):
"""Return the ordered ``(name, transformer)`` steps for a categorical ``method``."""
Expand All @@ -234,13 +239,14 @@ def get_categorical_transformer_steps(

spec = get_spec(method)
cls = spec.transformer_cls
overrides = representation_params or {}

if method == "int":
steps.append(("continuous_ordinal", cls()))
steps.append(("continuous_ordinal", cls(**overrides)))
elif method == "one-hot":
# Default to ignoring unseen categories so transform never crashes on
# categories absent at fit time; callers can override via kwargs.
onehot_kwargs = {"handle_unknown": "ignore", **kwargs}
onehot_kwargs = {"handle_unknown": "ignore", **kwargs, **overrides}
categories = onehot_kwargs.get("categories", "auto")
drop = onehot_kwargs.get("drop")
if (
Expand All @@ -255,25 +261,28 @@ def get_categorical_transformer_steps(
steps.append(("onehot", cls(**onehot_kwargs)))
steps.append(("to_float", ToFloatTransformer()))
elif method == "pretrained":
steps.append(("pretrained", cls()))
steps.append(("pretrained", cls(**overrides)))
elif method == "none":
steps.append(("none", cls()))
steps.append(("none", cls(**overrides)))
elif method == "onehot_from_ordinal":
steps.append(("onehot_from_ordinal", cls()))
steps.append(("onehot_from_ordinal", cls(**overrides)))
else:
call_kwargs = _filter_kwargs(spec.allowed_args, kwargs)
call_kwargs.update(_placement_kwargs(spec, kwargs))
call_kwargs.update(overrides)
steps.append((method, cls(**call_kwargs)))

return steps


def create_transformer(method: str, *, is_numerical: bool, config: PreprocessorConfig) -> Pipeline | FeatureUnion:
def create_transformer(
method: str, *, is_numerical: bool, config: PreprocessorConfig, representation_params: dict | None = None
) -> Pipeline | FeatureUnion:
"""Build the per-column :class:`~sklearn.pipeline.Pipeline` for one feature.

``method`` is the resolved method name; ``is_numerical`` selects the numerical
or categorical construction path. All width / placement / seeding knobs are
taken from ``config``.
taken from ``config`` and then updated by validated representation parameters.

Raises
------
Expand Down Expand Up @@ -306,6 +315,7 @@ def create_transformer(method: str, *, is_numerical: bool, config: PreprocessorC
degree=config.degree,
scaling=config.scaling,
placement_strategy=config.placement_strategy,
representation_params=representation_params,
**config.seed_kwargs,
)
else:
Expand All @@ -328,6 +338,7 @@ def create_transformer(method: str, *, is_numerical: bool, config: PreprocessorC
method,
add_imputer=plan["add_imputer"],
imputer_strategy=plan["strategy"],
representation_params=representation_params,
**constructor_kwargs,
)

Expand Down Expand Up @@ -403,8 +414,8 @@ def build_column_transformer(
transformers = []
for (kind, feature), name in zip(blocks, _step_names(blocks), strict=True):
is_numerical = kind == "num"
method = config.method_for(feature, is_numerical=is_numerical)
pipeline = create_transformer(method, is_numerical=is_numerical, config=config)
method, params = config.representation_for(feature, is_numerical=is_numerical)
pipeline = create_transformer(method, is_numerical=is_numerical, config=config, representation_params=params)
transformers.append((name, pipeline, [str(feature)]))
return ColumnTransformer(
transformers=transformers,
Expand Down
5 changes: 2 additions & 3 deletions pretab/compose/inspection.py
Original file line number Diff line number Diff line change
Expand Up @@ -300,9 +300,8 @@ def build_feature_info(column_transformer, *, embeddings, embedding_dimensions):
step = representation_pipeline.named_steps["onehot"]
if hasattr(step, "categories_"):
categories = sum(len(cat) for cat in step.categories_)
dimension = categories
if separate_state_dimension is not None:
dimension = separate_state_dimension
span = column_transformer.output_indices_[name]
dimension = span.stop - span.start
categorical_feature_info[feature_name] = {
"preprocessing": preprocessing_type,
"dimension": dimension,
Expand Down
35 changes: 23 additions & 12 deletions pretab/compose/registry.py
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,8 @@ class TransformerSpec:
transforms prepend a positive-range scaler) record their primary class
here; the extra wiring lives in :mod:`pretab.compose.factory`.
allowed_args : tuple of str
Constructor argument names the method accepts. Used to filter the shared
Preprocessor keyword arguments down to what the class understands.
Constructor argument names exposed through the Preprocessor. Used to
filter shared arguments and validate representation-specific overrides.
feature_kind : frozenset of str
The feature kinds the method applies to (``"numerical"`` and/or
``"categorical"``). Only ``none`` (passthrough) applies to both.
Expand Down Expand Up @@ -195,13 +195,17 @@ def _spec(name, cls, allowed_args=(), **kwargs):
# ordering), then the categorical-only methods.
_SPECS: tuple[TransformerSpec, ...] = (
# --- numerical: scalers / distribution transforms (no placement) ---
_spec("standardization", StandardScaler),
_spec("minmax", MinMaxScaler),
_spec("quantile", QuantileTransformer, ("n_quantiles", "output_distribution", "random_state")),
_spec("standardization", StandardScaler, ("with_mean", "with_std")),
_spec("minmax", MinMaxScaler, ("feature_range", "clip")),
_spec(
"quantile",
QuantileTransformer,
("n_quantiles", "output_distribution", "random_state", "subsample", "ignore_implicit_zeros"),
),
_spec("polynomial", PolynomialFeatures, ("degree", "interaction_only", "include_bias")),
_spec("robust", RobustScaler),
_spec("box-cox", PowerTransformer),
_spec("yeo-johnson", PowerTransformer),
_spec("robust", RobustScaler, ("with_centering", "with_scaling", "quantile_range", "unit_variance")),
_spec("box-cox", PowerTransformer, ("standardize",)),
_spec("yeo-johnson", PowerTransformer, ("standardize",)),
# --- numerical: piecewise-linear encoding (always target-aware) ---
_spec(
"ple",
Expand Down Expand Up @@ -314,30 +318,37 @@ def _spec(name, cls, allowed_args=(), **kwargs):
_spec(
"bspline",
BSplineTransformer,
("degree", "task", "adaptive", "min_output_dim", "max_output_dim", "random_state"),
("output_dim", "degree", "task", "adaptive", "min_output_dim", "max_output_dim", "random_state"),
**_BOTH_MODE,
),
_spec(
"mspline",
MSplineTransformer,
("degree", "task", "adaptive", "min_output_dim", "max_output_dim", "random_state"),
("output_dim", "degree", "task", "adaptive", "min_output_dim", "max_output_dim", "random_state"),
**_BOTH_MODE,
),
_spec(
"ispline",
ISplineTransformer,
("degree", "task", "adaptive", "min_output_dim", "max_output_dim", "random_state"),
("output_dim", "degree", "task", "adaptive", "min_output_dim", "max_output_dim", "random_state"),
**_BOTH_MODE,
),
# --- numerical / categorical: passthrough ---
_spec("none", NoTransformer, feature_kind=frozenset({NUMERICAL, CATEGORICAL})),
# --- categorical-only methods ---
_spec("int", ContinuousOrdinalTransformer, feature_kind=frozenset({CATEGORICAL})),
_spec("one-hot", OneHotEncoder, feature_kind=frozenset({CATEGORICAL}), sparse_output=True),
_spec(
"one-hot",
OneHotEncoder,
("categories", "drop", "sparse_output", "dtype", "handle_unknown", "min_frequency", "max_categories"),
feature_kind=frozenset({CATEGORICAL}),
sparse_output=True,
),
_spec("onehot_from_ordinal", OneHotFromOrdinalTransformer, feature_kind=frozenset({CATEGORICAL})),
_spec(
"pretrained",
LanguageEmbeddingTransformer,
("model_name",),
feature_kind=frozenset({CATEGORICAL}),
optional_dependency="embeddings",
),
Expand Down
5 changes: 3 additions & 2 deletions pretab/extension.py
Original file line number Diff line number Diff line change
Expand Up @@ -167,8 +167,9 @@ class without one raises ``TypeError``. For a class without a
``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.
Constructor argument names exposed through the Preprocessor. They filter
shared arguments and allow overrides in ``representation_params`` and
``feature_preprocessing``.
placement_strategies : iterable of str, default=()
Placement strategies the method honours (empty for methods without
data-driven placement). ``Preprocessor`` passes its ``placement_strategy``
Expand Down
Loading