pretab.transformers.CubicSplineTransformer

class pretab.transformers.CubicSplineTransformer(output_dim=UNSET, degree=3, include_bias=False, target_aware=False, placement_strategy='uniform', task=None, adaptive=False, min_output_dim=UNSET, max_output_dim=UNSET, random_state=None)[source]

Bases: SplineBasisMixin, TransformerMixin, BaseEstimator

Cubic Spline Transformer for one-dimensional or multi-dimensional input features.

This transformer applies a truncated-power cubic spline basis to each continuous feature. The basis stacks the polynomial terms \(x, x^2, x^3\) with one truncated cubic term \((x - \kappa)^3_+\) per interior knot \(\kappa\). Optionally a bias (intercept) column is prepended.

Let \(m := \mathtt{output\_dim}\) be the number of non-bias output columns produced per feature. A cubic truncated-power basis with \(K\) interior knots has

\[m = 3 + K,\]

so the requested output_dim is inverted to \(K = \mathtt{output\_dim} - 3\) interior knots. include_bias=True adds one further column on top of output_dim.

Parameters:

  • output_dim (int, default=6) – Number of non-bias output columns per feature (\(m\)). Must be at least 3 (the three polynomial terms; output_dim == 3 places no interior knots). The number of interior knots is output_dim - 3.

  • degree (int, default=3) – Degree of the polynomial spline. Currently fixed to 3 (cubic), included for compatibility.

  • include_bias (bool, default=False) – Whether to include a bias (intercept) term in the output feature set.

  • target_aware (bool, default=False) – If True, interior knots are placed by a target-aware selector built from placement_strategy (requires y during fit). If False, knots use the unsupervised placement_strategy spacing.

  • placement_strategy ({"cart", "lightgbm", "uniform", "quantile"}, default="uniform") – When target_aware=True, the selector: "cart" or "lightgbm". When target_aware=False, the spacing: "uniform" spaces knots evenly across the range, "quantile" places them at evenly spaced data quantiles.

  • task ({"regression", "classification"} or None, default=None) – Task forwarded to the target-aware selector when target_aware=True.

  • adaptive (bool, default=False) – If True (with target_aware=True), the per-feature output dimension may vary within [min_output_dim, max_output_dim] instead of being fixed to output_dim.

  • min_output_dim (int or None, default=None) – Lower bound on the per-feature output dimension in adaptive mode.

  • max_output_dim (int or None, default=None) – Upper bound on the per-feature output dimension in adaptive mode.

  • random_state (int or None, default=None) – Random state forwarded to the target-aware selector for reproducibility.

Variables:

  • knots (list of ndarray) – Interior knots used for each feature (length output_dim - 3 on the default, non-selector path).

  • n_knots (list of int) – Number of interior knots placed for each feature (len(knots_[i])).

  • designs (list of ndarray) – Cached design matrices (spline basis evaluations) for each input feature, each of shape (n_samples, output_dim (+1 if include_bias)).

  • n_basis (list of int) – Number of output columns per feature, including the optional bias.

  • n_features_in (int) – Number of input features seen during fit.

  • total_output_dim (int) – Total number of output columns across all features (fitted); equals n_features * (output_dim (+1 if include_bias)).

Notes

The basis includes the polynomial terms x, x^2, x^3 followed by the truncated power terms (x - knot)^3_+ for each interior knot. Each feature is expanded independently and the results are stacked horizontally.

Examples

>>> import numpy as np
>>> from pretab.transformers import CubicSplineTransformer
>>> X = np.linspace(0, 1, 20).reshape(-1, 1)
>>> transformer = CubicSplineTransformer(output_dim=8)
>>> Xt = transformer.fit_transform(X)
>>> Xt.shape
(20, 8)
>>> transformer.n_knots_
[5]
>>> transformer.total_output_dim_
8
__init__(output_dim=UNSET, degree=3, include_bias=False, target_aware=False, placement_strategy='uniform', task=None, adaptive=False, min_output_dim=UNSET, max_output_dim=UNSET, random_state=None)[source]

Methods

__init__([output_dim, degree, include_bias, ...])

fit(X[, y])

fit_transform(X[, y])

Fit to data, then transform it.

get_feature_names_out([input_features])

Return output feature names of the form {feature}_{suffix}{j}.

get_metadata_routing()

Get metadata routing of this object.

get_params([deep])

Get parameters for this estimator.

get_penalty_matrix([feature_index])

Return the curvature penalty matrix for a fitted feature.

set_output(*[, transform])

Set output container.

set_params(**params)

Set the parameters of this estimator.

transform(X)

Attributes

total_output_dim_

Total number of output columns produced across all input features.

n_basis_

n_features_in_

adaptive

fit_transform(X, y=None)[source]

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Input samples.

  • y (array-like of shape (n_samples,) or (n_samples, n_outputs), default=None) – Target values (None for unsupervised transformations).

  • **fit_params (dict) – Additional fit parameters. Pass only if the estimator accepts additional params in its fit method.

Returns:

X_new (ndarray array of shape (n_samples, n_features_new)) – Transformed array.

get_penalty_matrix(feature_index=0)[source]

Return the curvature penalty matrix for a fitted feature.

Parameters:

feature_index (int, default=0) – Index of the feature whose penalty matrix is returned.

Returns:

P (ndarray of shape (n_basis, n_basis)) – Penalty matrix that penalizes the second derivative (curvature) of the spline basis for smoothness.