pretab.preprocessor.Preprocessor

class pretab.preprocessor.Preprocessor(numerical_method='ple', categorical_method='int', feature_preprocessing=None, output_dim=7, degree=3, target_aware=True, placement_strategy='cart', task='regression', adaptive=False, min_output_dim=5, max_output_dim=10, random_state=None, scaling='minmax', cat_cutoff=0.03, treat_all_integers_as_numerical=False, handle_missing='median', verbose=0)[source]

Bases: TransformerMixin, BaseEstimator

Preprocessor class for automated tabular feature preprocessing using scikit-learn-compatible pipelines.

This class provides a flexible interface for preprocessing tabular datasets containing numerical and categorical features. It automatically detects feature types, applies user-defined or default preprocessing strategies, and supports both dictionary and array-style outputs. It also supports integration with external embedding vectors.

Features

  • Supports a wide range of preprocessing methods for numerical and categorical features.

  • Automatically detects feature types (numerical vs. categorical).

  • Compatible with both pandas DataFrames and NumPy arrays.

  • Handles external embedding arrays for models that require learned representations.

  • Returns either a dictionary of transformed feature blocks or a single NumPy array.

  • Fully compatible with scikit-learn transformers and pipelines.

param numerical_method:

Preprocessing strategy applied to every numerical column unless overridden per feature. Common choices: "ple" (piecewise-linear encoding), "minmax" / "standardization" / "robust" (scaling), "quantile" (rank transform), "rbf" / "relu" / "sigmoid" / "tanh" (feature maps), and "cubicspline" / "naturalspline" / "pspline" / "bspline" (spline bases). Pass None (resolved to "none") to leave numerical columns unchanged. See Notes for the complete list.

type numerical_method:

str, default=”ple”

param categorical_method:

Preprocessing strategy applied to every categorical column unless overridden per feature. Choices: "int" (contiguous integer codes), "one-hot" (dummy columns), "onehot_from_ordinal" (integer codes then one-hot), "pretrained" (sentence-transformer language embeddings), and "custombin" (discretized bin codes). Pass None (resolved to "none") to leave categorical columns unchanged.

type categorical_method:

str, default=”int”

param feature_preprocessing:

Mapping of individual column names to a method, overriding the global numerical_method / categorical_method for those columns only, e.g. {"age": "cubicspline", "city": "pretrained"}. Columns absent from the dict fall back to the global defaults.

type feature_preprocessing:

dict, optional

param output_dim:

The single width knob shared by every numerical method: the number of non-bias output columns produced per input feature (bins for PLE/binning, centers for the feature maps, basis functions for the splines). The B/M/I splines clamp it into their supported [5, 50] range. Used as the fixed per-feature width when adaptive is False.

type output_dim:

int, default=7

param degree:

Polynomial / spline basis degree, used by "polynomial" and the spline methods ("cubicspline", "pspline", "bspline", …). Ignored by methods without a degree.

type degree:

int, default=3

param target_aware:

Whether target-aware methods (feature maps and splines) use y to place their basis units, e.g. decision-tree knot/center selection. Requires y to be passed to fit; set to False for a purely unsupervised, y-free fit. Pairs with placement_strategy: when True the strategy must be "cart" or "lightgbm"; when False it must be "uniform" or "quantile".

type target_aware:

bool, default=True

param placement_strategy:

How basis units / knots are placed, interpreted according to target_aware. When target_aware is True: "cart" (a single decision tree, always available) or "lightgbm" (a gradient-boosted ensemble, requires the optional lightgbm dependency). When target_aware is False: "uniform" (evenly spaced across the feature range) or "quantile" (spaced by the data quantiles). Applies to the feature maps, PLE, and the knot-based splines ("bspline" / "mspline" / "ispline" / "cubicspline" / "naturalspline"); the always-target-aware "ple" only honors the supervised strategies, while the penalized "pspline" / "tensorspline" (which assume equally-spaced knots) and the kernel-based "tprs" only honor the unsupervised ones.

type placement_strategy:

str, default=”cart”

param task:

Supervised task ("regression" or "classification") used by target-aware methods to place basis units / knots against y. Only consulted when target_aware is True.

type task:

str, default=”regression”

param adaptive:

Whether adaptive-capable methods size each feature’s output dimension from the data (within [min_output_dim, max_output_dim]) instead of using the fixed output_dim. Fixed-width methods (e.g. plain scalers) ignore this flag.

type adaptive:

bool, default=False

param min_output_dim:

Lower bound on the per-feature output dimension when adaptive is True. Ignored by fixed-width methods and when adaptive is False.

type min_output_dim:

int, default=5

param max_output_dim:

Upper bound on the per-feature output dimension when adaptive is True. Ignored by fixed-width methods and when adaptive is False.

type max_output_dim:

int, default=10

param random_state:

Global seed forwarded to every stochastic numerical method (PLE and feature-map decision trees, the quantile transformer, and target-aware spline knot selectors) to make fit reproducible. When None (the default) each transformer keeps its own default seed, so the value is only propagated when explicitly set – preserving prior behavior while giving a single knob to pin reproducibility. Forwarded by get_params / clone so an embedding host (e.g. DeepTab) can pass it through.

type random_state:

int or None, default=None

param scaling:

Optional scaler inserted before the numerical method: "minmax" (rescale to [-1, 1]) or "standardization" (zero mean, unit variance). Skipped automatically when the chosen method already scales (e.g. numerical_method="minmax").

type scaling:

str, default=”minmax”

param cat_cutoff:

Threshold deciding whether an integer column is treated as categorical. A float is a unique-ratio cutoff (n_unique / n_rows < cat_cutoff -> categorical); an int is an absolute unique-count cutoff (n_unique < cat_cutoff -> categorical).

type cat_cutoff:

float or int, default=0.03

param treat_all_integers_as_numerical:

If True, every integer-typed column is treated as numerical regardless of cardinality, bypassing the cat_cutoff heuristic.

type treat_all_integers_as_numerical:

bool, default=False

param handle_missing:

Missing-value policy. "median" keeps the default mean SimpleImputer that runs before every numerical method (so NaNs are filled and, e.g., PLE uses its median handling). "error" drops that imputer so missing values are not silently filled and reach the transformers, which then raise on NaN. Forwarded to the NaN-aware methods (currently PLE) via the numerical pipeline.

type handle_missing:

{“error”, “median”}, default=”median”

param verbose:

Verbosity level controlling fit-time logging, applied through the shared "pretab" logger so a single setting on this entry point governs the whole package (including the individual numerical/categorical transformers). Accepts an int 0-3 and also bool (True -> 1, False -> 0):

  • 0 – silent on the happy path (only PretabWarning data warnings).

  • 1 – one fit-summary line (feature counts, resolved methods, total output width, duration).

  • 2 – the per-feature table that get_feature_info() builds.

  • 3 – internal decisions (fitted bins / knots / centers).

Stored verbatim and forwarded by get_params / clone, so an embedding host (e.g. DeepTab) can pass it straight through Preprocessor(**kwargs). PreTab never configures the root logger or attaches a handler when the host already owns one, so verbose=0 keeps PreTab silent under a host’s own logging.

type verbose:

int, default=0

ivar column_transformer_:

The internal scikit-learn column transformer that handles feature-wise preprocessing. Set when the preprocessor is fitted.

vartype column_transformer_:

ColumnTransformer

ivar n_features_in_:

Number of input features seen during fit.

vartype n_features_in_:

int

ivar total_output_dim_:

Total number of output columns produced across all input features (equals the width of transform(..., return_array=True)).

vartype total_output_dim_:

int

ivar output_dims_:

Per-feature expanded output-column counts, keyed by input feature name. The values sum to total_output_dim_.

vartype output_dims_:

dict

ivar embeddings_:

Whether embedding vectors were provided at fit time and are expected in transformation.

vartype embeddings_:

bool

ivar embedding_dimensions_:

Dictionary of embedding feature names to their expected dimensionality.

vartype embedding_dimensions_:

dict

Notes

Available numerical_method values: "none", "minmax", "standardization", "robust", "quantile", "polynomial", "box-cox", "yeo-johnson", "ple", "custombin", "rbf", "relu", "sigmoid", "tanh", "cubicspline", "naturalspline", "pspline", "tensorspline", "tprs", "bspline", "mspline", "ispline".

Available categorical_method values: "int", "one-hot", "onehot_from_ordinal", "pretrained", "custombin", "none". The "pretrained" method requires the optional sentence-transformers dependency (pip install "pretab[embeddings]").

Method names are resolved case-insensitively and ignore - / _ / space separators, so "one-hot", "one_hot" and "OneHot" are equivalent. Common synonyms and abbreviations are also accepted, e.g. "std" / "standard" -> "standardization", "ohe" / "dummy" -> "one-hot", "ordinal" / "label" -> "int", "poly" -> "polynomial", "thin-plate" -> "tprs", and "passthrough" -> "none".

transform returns a dict of per-feature blocks keyed num_<col> / cat_<col> by default, or a single stacked array when return_array=True.

Examples

Basic usage – PLE for numerics and integer codes for categoricals (the defaults):

>>> import pandas as pd
>>> from pretab import Preprocessor
>>> df = pd.DataFrame({"age": [25, 32, 47, 51], "gender": ["M", "F", "F", "M"]})
>>> y = [0.1, 0.4, 0.9, 1.2]
>>> pre = Preprocessor()
>>> out = pre.fit_transform(df, y)
>>> sorted(out.keys())
['cat_gender', 'num_age']

Cubic-spline basis for numerics with one-hot encoded categoricals:

>>> pre = Preprocessor(numerical_method="cubicspline", categorical_method="one-hot",
...                    output_dim=10, degree=3)
>>> out = pre.fit_transform(df, y)

Radial-basis feature maps with target-aware center placement:

>>> pre = Preprocessor(numerical_method="rbf", target_aware=True, task="regression",
...                    output_dim=8)
>>> out = pre.fit_transform(df, y)

A different method per column via feature_preprocessing:

>>> pre = Preprocessor(feature_preprocessing={"age": "pspline", "gender": "one-hot"})
>>> out = pre.fit_transform(df, y)

Data-driven (adaptive) width, returned as a single stacked array:

>>> pre = Preprocessor(numerical_method="ple", adaptive=True,
...                    min_output_dim=4, max_output_dim=12)
>>> arr = pre.fit_transform(df, y, return_array=True)
>>> arr.ndim
2
__init__(numerical_method='ple', categorical_method='int', feature_preprocessing=None, output_dim=7, degree=3, target_aware=True, placement_strategy='cart', task='regression', adaptive=False, min_output_dim=5, max_output_dim=10, random_state=None, scaling='minmax', cat_cutoff=0.03, treat_all_integers_as_numerical=False, handle_missing='median', verbose=0)[source]

Initialize the Preprocessor with various transformation options for tabular data.

See the Preprocessor class docstring for the full parameter reference, available numerical_method / categorical_method values, and usage examples.

Methods

__init__([numerical_method, ...])

Initialize the Preprocessor with various transformation options for tabular data.

fit(X[, y, embeddings])

Fit the preprocessor to the input data and target labels.

fit_transform(X[, y, embeddings, return_array])

Convenience method that fits the preprocessor and transforms the data.

get_feature_info([verbose])

Retrieves metadata about the transformed features.

get_feature_names_out([input_features])

Get output feature names for transformation.

get_metadata_routing()

Get metadata routing of this object.

get_params([deep])

Get parameters for this estimator.

set_fit_request(*[, embeddings])

Configure whether metadata should be requested to be passed to the fit method.

set_output(*[, transform])

Set output container.

set_params(**params)

Set the parameters of this estimator.

set_transform_request(*[, embeddings, ...])

Configure whether metadata should be requested to be passed to the transform method.

transform(X[, embeddings, return_array])

Transform the input data using the fitted column transformer.

Attributes

output_dims_

Per-feature expanded output-column counts.

total_output_dim_

Total number of output columns produced across all input features.
fit(X, y=None, embeddings=None)[source]

Fit the preprocessor to the input data and target labels.

Parameters:

  • X (pandas.DataFrame, numpy.ndarray, or dict) – The input features.

  • y (array-like, default=None) – Target values (used for decision tree-based methods).

  • embeddings (np.ndarray or list of np.ndarray, optional) – External embedding arrays to be passed and validated.

Returns:

self (Preprocessor) – Fitted instance of the preprocessor.

fit_transform(X, y=None, embeddings=None, return_array=False)[source]

Convenience method that fits the preprocessor and transforms the data.

Parameters:

  • X (pandas.DataFrame, numpy.ndarray, or dict) – Input features.

  • y (array-like, optional) – Target values.

  • embeddings (np.ndarray or list of np.ndarray, optional) – Optional embedding arrays.

  • return_array (bool, default=False) – Whether to return a stacked NumPy array or a dictionary of arrays.

Returns:

dict or np.ndarray – Transformed dataset in the specified output format.

get_feature_info(verbose=True)[source]

Retrieves metadata about the transformed features.

Provides detailed information for each input feature, including: - preprocessing applied - output dimensionality - number of categories (for categorical features) - embedding dimensions (if any)

Parameters:

verbose (bool, default=True) – If True, renders an aligned per-feature table through the pretab logger (attaching a stream handler when none is configured). If False, the info dicts are returned silently.

Returns:

tuple of dicts –

numerical_feature_infodict

Metadata for numerical features.

categorical_feature_infodict

Metadata for categorical features.

embedding_feature_infodict

Metadata for embedding features, if used.

get_feature_names_out(input_features=None)[source]

Get output feature names for transformation.

Delegates to the fitted internal ColumnTransformer, returning one name per output column of the stacked array produced by transform(..., return_array=True).

Parameters:

input_features (array-like of str or None, default=None) – Input feature names. Passed through to the underlying column transformer.

Returns:

feature_names_out (numpy.ndarray of str) – Transformed feature names.

property output_dims_

Per-feature expanded output-column counts.

Fitted attribute (available only after fit). Maps each input feature (by name) to the number of columns it contributes to the transformed array, complementing the scalar total_output_dim_. The values sum to total_output_dim_. Useful when features get different output_dim values (via feature_preprocessing) or expand to a non-uniform width (e.g. one-hot encoded categoricals).

property total_output_dim_

Total number of output columns produced across all input features.

Fitted attribute (available only after fit). Defined as len(self.get_feature_names_out()) so it always equals the true width of the array returned by transform(..., return_array=True).

transform(X, embeddings=None, return_array=False)[source]

Transform the input data using the fitted column transformer.

Parameters:

  • X (pandas.DataFrame, numpy.ndarray, or dict) – Input features to transform.

  • embeddings (np.ndarray or list of np.ndarray, optional) – Optional external embeddings to attach to the transformation.

  • return_array (bool, default=False) – If True, return a single stacked NumPy array. If False, return a dict of transformed arrays.

Returns:

dict or np.ndarray – Transformed data. A dictionary if return_array=False, else a NumPy array.