pretab.transformers.NaturalCubicSplineTransformer

class pretab.transformers.NaturalCubicSplineTransformer(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

Natural Cubic Spline Transformer for continuous features.

This transformer expands each input feature using a natural cubic spline basis. Natural cubic splines are piecewise cubic polynomials that are linear beyond the boundary knots, ensuring smooth extrapolation. The basis stacks a linear term with one constrained non-linear term per interior knot (and, optionally, a bias column).

Let \(m := \mathtt{output\_dim}\) be the number of non-bias output columns per feature and \(T\) the total number of (spanning) knots including the two boundary knots. The natural-spline basis drops the intercept, so

\[m = T - 1,\]

and the requested output_dim is inverted to \(T = \mathtt{output\_dim} + 1\) spanning knots (both endpoints retained for the linear-tail constraint). 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 2. The number of spanning knots placed is output_dim + 1.

  • degree (int, default=3) – Degree of the spline. Natural cubic splines are cubic by definition, so this is fixed at 3 and included only for API parity with the other splines.

  • include_bias (bool, default=False) – If True, includes a constant bias (intercept) column in the output.

  • target_aware (bool, default=False) – If True, 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" reproduces the historical evenly spaced knots, "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) – Spanning knot vectors used for each feature (length output_dim + 1 on the default, non-selector path).

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

  • designs (list of ndarray) – Cached spline basis design matrices, 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 is constructed to satisfy the natural spline constraint: the second derivative of the spline is zero at the boundary knots. This reduces overfitting at the boundaries and improves extrapolation. Each feature is transformed independently and the outputs are concatenated.

Examples

>>> import numpy as np
>>> from pretab.transformers import NaturalCubicSplineTransformer
>>> X = np.linspace(0, 1, 20).reshape(-1, 1)
>>> transformer = NaturalCubicSplineTransformer(output_dim=4)
>>> Xt = transformer.fit_transform(X)
>>> Xt.shape
(20, 4)
>>> transformer.n_knots_
[3]
>>> transformer.total_output_dim_
4
__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 approximating the integrated squared second derivative of the natural cubic spline basis.