pretab.transformers.PLETransformer

class pretab.transformers.PLETransformer(output_dim=UNSET, placement_strategy='cart', task='regression', adaptive=False, min_output_dim=UNSET, max_output_dim=UNSET, random_state=51, handle_missing='median', max_depth=None, min_samples_split=2, min_samples_leaf=1)[source]

Bases: AdaptiveResolutionMixin, AliasResolverMixin, TransformerMixin, BaseEstimator

Piecewise Linear Encoding (PLE) transformer for numerical features.

Each feature is discretized by a target-aware location selector ("cart" by default, optionally "lightgbm") whose split thresholds define the bin edges. Every input feature is expanded into one column per bin. Within the bin that a value falls into, the value is encoded linearly; all lower bins are set to 1 and all higher bins to 0. This preserves an ordinal, piecewise linear signal that downstream models can exploit while keeping the representation interpretable.

Parameters:

output_dim (int, default=6) – Maximum number of bins per feature, i.e. an upper bound on the number of output columns produced for each feature. This caps the number of leaf nodes (and therefore thresholds) the decision tree may produce. The actual number of output columns is data-dependent and may be smaller (see Notes).
placement_strategy ({"cart", "lightgbm"}, default="cart") – Which target-aware location selector places the bin thresholds. PLE is inherently target-aware, so only the supervised selectors apply. "cart" fits a single decision tree (always available); "lightgbm" fits a gradient-boosted ensemble and requires the optional lightgbm dependency (pip install pretab[knots]).
task ({"regression", "classification"}, default="regression") – Whether to fit a DecisionTreeRegressor or DecisionTreeClassifier to locate the split thresholds.
adaptive (bool, default=False) – If True, allow the number of bins per feature to be data-driven, bounded by min_output_dim and max_output_dim. If False, every feature is capped by output_dim.
min_output_dim (int or None, default=None) – Minimum number of bins per feature when adaptive=True.
max_output_dim (int or None, default=None) – Maximum number of bins per feature when adaptive=True.
random_state (int or None, default=51) – Random state for reproducible tree fitting.
handle_missing ({"error", "median"}, default="median") –
How to handle NaN values.
- "error": raise an error when a NaN is encountered.
- "median": drop NaN rows during fit and, at transform time, replace NaN with the median of that feature’s thresholds (or 0 when the feature produced no thresholds).
max_depth (int or None, default=None) – Maximum depth of the decision tree.
min_samples_split (int, default=2) – Minimum number of samples required to split an internal node.
min_samples_leaf (int, default=1) – Minimum number of samples required at a leaf node.

Variables:

thresholds (list of ndarray) – Sorted threshold values for each feature.
n_features_in (int) – Number of features seen during fit.
n_bins_per_feature (list of int) – Number of output bins produced for each feature (len(thresholds) + 1).
total_output_dim (int) – Total number of output columns across all features (fitted); equals sum(n_bins_per_feature_).
fill_values (list of float) – Per-feature fill value used to replace NaN during transform.

Notes

The number of output columns per feature equals len(thresholds) + 1 and is therefore data-dependent: a feature whose tree finds fewer splits will expand into fewer columns than a feature with many splits. output_dim is an upper bound (bin cap), not an exact width; this is a documented exception to the exact-width contract that the fixed-basis families follow.

The max_depth / min_samples_split / min_samples_leaf parameters are retained for backward-compatible construction but no longer affect threshold placement: the placement_strategy selector fits its own model with its own settings. They are slated for reconciliation in a later cleanup.

Examples

>>> from sklearn.datasets import make_regression
>>> X, y = make_regression(n_samples=100, n_features=5, noise=10, random_state=51)
>>> ple = PLETransformer(output_dim=10, task="regression")
>>> X_transformed = ple.fit_transform(X, y)

__init__(output_dim=UNSET, placement_strategy='cart', task='regression', adaptive=False, min_output_dim=UNSET, max_output_dim=UNSET, random_state=51, handle_missing='median', max_depth=None, min_samples_split=2, min_samples_leaf=1)[source]

Methods

`__init__`([output_dim, placement_strategy, ...])
`fit`(X, y)	Fit the transformer by learning per-feature bin thresholds.
`fit_transform`(X[, y])	Fit to data, then transform it.
`get_feature_names_out`([input_features])	Return output feature names.
`get_metadata_routing`()	Get metadata routing of this object.
`get_n_features_out`()	Return the total number of output columns across all features.
`get_params`([deep])	Get parameters for this estimator.
`set_output`(*[, transform])	Set output container.
`set_params`(**params)	Set the parameters of this estimator.
`transform`(X)	Encode features with vectorized piecewise linear binning.

Attributes

adaptive

fit(X, y)[source]

Fit the transformer by learning per-feature bin thresholds.

Parameters:

X (array-like of shape (n_samples, n_features)) – Training data.
y (array-like of shape (n_samples,)) – Target values used to grow the per-feature decision trees.

Returns:

self (PLETransformer) – The fitted transformer.

get_feature_names_out(input_features=None)[source]

Return output feature names.

Parameters:: input_features (array-like of str or None, default=None) – Input feature names. If None, generic names x0, x1 … are used.
Returns:: feature_names_out (ndarray of str) – One name per output column, formatted {name}_ple_piece{j}.

get_n_features_out()[source]: Return the total number of output columns across all features.

transform(X)[source]

Encode features with vectorized piecewise linear binning.

Parameters:: X (array-like of shape (n_samples, n_features)) – Data to transform.
Returns:: X_transformed (ndarray of shape (n_samples, n_features_out)) – The piecewise linear encoding, cast to float32.