pretab.transformers.PSplineTransformer

class pretab.transformers.PSplineTransformer(output_dim=UNSET, degree=3, diff_order=2, include_bias=False, placement_strategy='uniform', adaptive=False, min_output_dim=UNSET, max_output_dim=UNSET)[source]

Bases: SplineBasisMixin, TransformerMixin, BaseEstimator

P-spline Transformer for smooth spline basis expansion with penalization.

This transformer expands each input feature into a set of B-spline basis functions and stores a corresponding difference-penalty matrix for regularization. It is useful in Generalized Additive Models (GAMs) where smoothness is enforced through penalties.

Let \(p\) be the degree and \(m := \mathtt{output\_dim}\) the number of non-bias output columns per feature. A B-spline basis with \(K\) interior knots (padded by \(p + 1\) repeated boundary knots on each side) has

\[m = \operatorname{len}(\mathtt{knots}) - p - 1 = K + p + 1,\]

so the requested output_dim is inverted to \(K = \mathtt{output\_dim} - p - 1\) 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 degree + 1. The number of interior knots is output_dim - degree - 1.

  • degree (int, default=3) – Degree of the B-spline basis functions (e.g., 3 for cubic splines).

  • diff_order (int, default=2) – The order of the difference penalty used to compute the smoothness penalty matrix. For example, 2 corresponds to a second-order difference penalty (encouraging smooth second derivatives).

  • include_bias (bool, default=False) – If True, prepend a constant intercept column per feature. The bias term is left unpenalized (a zero row/column is added to the penalty matrix).

  • placement_strategy ({"uniform", "quantile"}, default="uniform") –

    Interior-knot placement rule. "uniform" spaces knots evenly across the range; "quantile" places them at evenly spaced data quantiles.

    Note

    P-splines are penalized (difference-penalty) splines that assume equally-spaced knots, so this family is unsupervised-only: target-aware placement does not apply and only "uniform" / "quantile" spacing is accepted.

  • adaptive (bool, default=False) – Retained for API parity but a no-op for this unsupervised-only family: the per-feature width is always fixed to output_dim.

  • min_output_dim (int or None, default=None) – Unused for this unsupervised-only family (kept for API parity).

  • max_output_dim (int or None, default=None) – Unused for this unsupervised-only family (kept for API parity).

Variables:

  • knots (list of ndarray) – Full padded knot sequence (interior knots bracketed by degree + 1 repeated boundary knots on each side) for each feature.

  • n_knots (list of int) – Number of interior knots for each feature (output_dim - degree - 1 on the default, non-selector path).

  • penalty (list of ndarray) – Difference-penalty matrices (D^T D) for each feature.

  • n_basis (list of int) – Number of output columns per feature, including the optional bias (equals output_dim (+1 if include_bias) on the default path).

  • 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

  • Boundary knots are added automatically to ensure proper spline behavior near the edges.

  • Internally, this transformer uses recursive B-spline basis construction.

  • This implementation supports multi-dimensional inputs and stacks transformed features horizontally.

Examples

>>> import numpy as np
>>> from pretab.transformers import PSplineTransformer
>>> X = np.linspace(0, 1, 30).reshape(-1, 1)
>>> transformer = PSplineTransformer(output_dim=8)
>>> Xt = transformer.fit_transform(X)
>>> Xt.shape
(30, 8)
>>> transformer.n_knots_
[4]
>>> transformer.total_output_dim_
8
__init__(output_dim=UNSET, degree=3, diff_order=2, include_bias=False, placement_strategy='uniform', adaptive=False, min_output_dim=UNSET, max_output_dim=UNSET)[source]

Methods

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

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 difference 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

get_penalty_matrix(feature_index=0)[source]

Return the difference 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 D.T @ D built from the finite-difference operator, suitable for Tikhonov-style smoothness regularization.