[ChrisW09]

Fixes #84.

The B-, M-, I-, P-spline and tensor-product transformers clip out-of-range values by default, but a policy mapping that named only constant switched them to "extrapolate", and under "extrapolate" or "warn" the B-, M-, P-spline and tensor-product bases returned all-zero rows for out-of-range values. A standalone spline with such a policy silently lost every out-of-range value.

Root cause

Two independent causes:

• BasePreTabTransformer._resolved_policy passed an explicit policy to RepresentationPolicy.resolve, which builds RepresentationPolicy(**mapping). Every axis the mapping did not name took the dataclass default (out_of_range="extrapolate"), not the family default ("clip").
• "extrapolate" and "warn" pass out-of-range values through to bases that are zero outside the knot span: BSpline(..., extrapolate=False) followed by nan_to_num in the B- and M-spline transformers, and the Cox-de Boor recursion bspline_basis in the P-spline and tensor-product transformers.

Fix

• BasePreTabTransformer._resolved_policy first builds the family policy from _policy, _constant_policy and _out_of_range_policy, then merges a mapping onto it with RepresentationPolicy.merge, so a mapping changes only the axes it names. A RepresentationPolicy instance is still used verbatim.
• BSplineTransformer._design_matrix and MSplineTransformer._mspline_basis evaluate with BSpline(..., extrapolate=True). In-range values are identical either way.
• New helper pretab.core.knots.extrapolate_bspline_rows re-evaluates the rows whose value lies outside the knot span with BSpline(..., extrapolate=True), which extends the boundary polynomial pieces. PSplineTransformer and TensorProductSplineTransformer apply it to their Cox-de Boor basis; rows inside the span are left untouched.

Behaviour changes

• A policy mapping on any transformer that exposes policy keeps the family default for every axis it does not name. For the clipping families this keeps "clip". Natural-cubic and cubic-regression splines are unaffected, because their family default equals the dataclass default.
• A mapping with an unknown axis (for example {"missing": "error"}) raises InvalidParamError (a ValueError) instead of a bare TypeError. A mapping value of None is ignored instead of raising.
• Under "extrapolate" or "warn", out-of-range rows of the B-spline, M-spline, P-spline and tensor-product bases are extrapolated values instead of zeros. The B-spline, P-spline and tensor-product rows sum to 1. The I-spline still returns 0 below and 1 above the range. The default ("clip") output is unchanged.

Documentation

• policy parameter docstrings of BaseSplineTransformer (B/M/I), PSplineTransformer and TensorProductSplineTransformer: "warn" / "extrapolate" evaluate an out-of-range value on the extended boundary polynomial pieces (the I-spline stays at 0/1), and a mapping such as {"constant": "warn"} keeps the clipping.
• _resolved_policy docstring and the pretab/core/policy.py module docstring: a mapping overrides only the axes it names on top of the family defaults; an instance is used verbatim.
• Docstring of the new extrapolate_bspline_rows.
• docs/representations/choosing_a_method.md, "Out-of-range input at transform": "extrapolate" is available for the clipping families, what "extrapolate" / "warn" evaluate, and that a mapping keeps the family's other defaults.

Tests

• test_partial_policy_mapping_keeps_the_family_out_of_range_default[BSplineTransformer|MSplineTransformer|PSplineTransformer]: policy={"constant": "warn"} gives the same out-of-range rows as the default policy. Fails on main, passes here.
• test_partial_policy_mapping_keeps_the_family_out_of_range_default[ISplineTransformer]: the same for the I-spline, whose out-of-range rows are 0/1 under both clip and extrapolate. Guard test: passes on both by design.
• test_tensorproduct_partial_policy_mapping_keeps_clipping: the same for the tensor product. Fails on main, passes here.
• test_policy_mapping_with_an_unknown_axis_is_rejected: {"missing": "error"} raises InvalidParamError. Fails on main (TypeError), passes here.
• test_extrapolated_bspline_rows_are_not_zeroed[extrapolate|warn x BSplineTransformer|PSplineTransformer]: out-of-range rows sum to 1, and an in-range row equals the clipped transformer's. Fails on main, passes here.
• test_extrapolated_mspline_and_tensor_rows_are_not_zeroed: the M-spline out-of-range row is non-zero, and the tensor-product row with one out-of-range coordinate sums to 1. Fails on main, passes here.

Reproduction

Output of the script from #84 on this branch (the last case also emits DataWarning: BSplineTransformer received values outside the fitted range at transform time.):

policy=None                                                              -> transform(1.5) = [[0.0, 0.0, 0.0, 0.0, 0.0, 1.0]]
policy={'constant': 'warn'}                                              -> transform(1.5) = [[0.0, 0.0, 0.0, 0.0, 0.0, 1.0]]
policy=RepresentationPolicy(constant='allow', out_of_range='extrapolate') -> transform(1.5) = [[0.0, 0.0, -0.78, 9.571, -31.603, 23.812]]
policy=RepresentationPolicy(constant='allow', out_of_range='warn')       -> transform(1.5) = [[0.0, 0.0, -0.78, 9.571, -31.603, 23.812]]

Checks

• just test: 1449 passed, 59 skipped, 7 xfailed; coverage 93.71% (gate 90%).
• Minimum dependencies (CI job: Python 3.10, numpy 1.24.4, pandas 2.0.3, scipy 1.10.1, scikit-learn 1.6.0): 1436 passed, 72 skipped, 7 xfailed; scripts/quickstart.py passes.
• just docs: strict build succeeds.
• just check: all pre-commit and pre-push hooks pass (ruff format, ruff lint, prettier, file hygiene, pyright with 0 errors).
• Import direction between subpackages is unchanged.

Merge notes

• Base: main.
• The PRs for ISplineTransformer: 200-point trapezoid integration produces wrong and all-zero basis columns #53 (fix(splines): evaluate the I-spline basis in closed form #98), Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56 (fix(splines): keep knots unique and strictly interior on tied data #101), MSplineTransformer: absolute clipping thresholds make the basis depend on feature scale #63 (fix(splines): drop absolute clipping thresholds from the M-spline basis #107), Target-aware splines trim selector knots by position, dropping the dominant split, and cap adaptive width at 15 #69 (fix(splines): search the resolved knot window in target-aware placement #109), B/M/I spline knot_locations are sized by output_dim and clipped to the data range instead of used as given #81 (fix(splines): honour explicit knot_locations regardless of output_dim #118), Unsupervised quantile placement repeats RBF/ReLU/sigmoid/tanh centers on tied data, duplicating columns #82 (fix(placement): return distinct quantile locations on tied data #119), Standalone transformers drop DataFrame feature names, so reordered columns are silently misaligned #85 (fix(transformers): record and check DataFrame feature names #135), B/M/I spline and two-feature thin-plate spline transformers encode a missing value as an all-zero row #87 (fix(splines): expand a missing value to a NaN row in the B/M/I and thin-plate bases #122), A 2-D y (multi-output target) crashes the B/M/I splines even when unsupervised, and target-aware methods with unrelated errors #88 (fix(splines): ignore y when unsupervised and reject a multi-output target #123) and An invalid task such as "Regression" is silently treated as classification by the splines and selectors #93 (fix(validation): reject an unknown task instead of using classification #128) also edit spline files or pretab/core/knots.py / pretab/core/base.py, and the PRs for Target-aware location selectors return too few, duplicate, or boundary locations on tied/discrete features #57 (fix(placement): fill tied-data locations with distinct interior points #102) and Preprocessor crashes on an all-missing column at fit (numerical, one-hot) or silently drops it (int) #95 (fix(preprocessor): keep a block for columns with no observed value at fit #130) also edit docs/representations/choosing_a_method.md. Each merges cleanly with this branch.
• B/M/I spline and two-feature thin-plate spline transformers encode a missing value as an all-zero row #87 turns missing inputs into NaN rows in the B/M/I transform and evaluates the basis only on the observed values, so the out-of-range rows extrapolated here are not affected. MSplineTransformer: absolute clipping thresholds make the basis depend on feature scale #63 rewrites the scaling in MSplineTransformer._mspline_basis a few lines below the extrapolate=True change. ISplineTransformer: 200-point trapezoid integration produces wrong and all-zero basis columns #53 evaluates the I-spline in closed form on values clipped to the knot range, so the I-spline still returns 0/1 outside the range, as the docstrings here state. With each of B/M/I spline and two-feature thin-plate spline transformers encode a missing value as an all-zero row #87, MSplineTransformer: absolute clipping thresholds make the basis depend on feature scale #63, ISplineTransformer: 200-point trapezoid integration produces wrong and all-zero basis columns #53, Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56 and Standalone transformers drop DataFrame feature names, so reordered columns are silently misaligned #85 merged onto this branch, tests/core/test_policy.py and tests/expansion/spline pass.

This change was previously part of #86, which is closed in favour of one pull request per issue.