fix(placement): return distinct quantile locations on tied data

[ChrisW09]

Fixes #82.

With unsupervised "quantile" placement, which is the default for the standalone feature maps, the RBF, ReLU, sigmoid and tanh expansions repeated centers on tied features (zero-inflated, top-coded or discrete) and produced exactly duplicated output columns. On the issue's zero-inflated feature only 4 of 8 columns were distinct. This also applied through Preprocessor(numerical_method="rbf", target_aware=False, placement_strategy="quantile").

Root cause

QuantilePlacement._place returned the data quantiles verbatim: spanning_knots(x, n, "quantile") with endpoints, or quantile_knots(x, n) without them. On tied data many of these quantiles coincide, and nothing removed the duplicates.

Fix

QuantilePlacement._place (pretab/placement/unsupervised.py) now makes the locations distinct with pretab.core.knots.supplement_interior_knots, the helper that the PR for #56 (#101) adds for the spline knots:

• With include_endpoints=True, the feature-map path, the minimum and maximum are kept once. The interior is made unique and strictly inside the range, then topped up to n_units - 2 with strictly interior quantile / uniform candidates.
• With include_endpoints=False, the quantiles are made unique and strictly interior and topped up to n_units in the same way.
• A zero-range feature has no interior, so it keeps its repeated location and the output width holds. With include_endpoints=True and n_units <= 2, the locations are the same as before.

Behaviour changes

• Unsupervised "quantile" centers of the RBF, ReLU, sigmoid and tanh expansions move on tied data. They are now distinct, with the range endpoints kept once and the remaining centers strictly interior. On the issue's zero-inflated feature the centers change from [0.0, 0.0, 0.0, 0.0, 0.0, 1.77, 5.33, 35.36] to [0.0, 1.77, 5.05, 5.33, 15.16, 20.21, 30.31, 35.36]. Untied data and zero-range features give the same centers as before, and the golden regression baselines pass unchanged.
• The public QuantilePlacement(include_endpoints=False) also returns unique, strictly interior locations on tied data.
• The output width is unchanged.

Documentation

• QuantilePlacement class docstring (public in pretab.placement): the tied-data rule and the zero-range case.
• placement_strategy of RBFExpansionTransformer, ReLUExpansionTransformer, SigmoidExpansionTransformer and TanhExpansionTransformer: "quantile" centers stay distinct on tied data.
• docs/core_concepts/resolution_and_placement.md: the tied-data paragraph added by the PR for 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) now also covers the feature maps.

Tests

All tests are in tests/placement/test_placement.py.

• test_quantile_placement_returns_distinct_locations_on_tied_data[{True,False}-{zero-inflated,discrete,top-coded}]: 8 distinct locations. With include_endpoints=True the endpoints are kept; without them the locations are strictly interior. Fails on main and on Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56's branch, passes here.
• test_quantile_feature_map_has_no_duplicate_columns_on_tied_data[{RBF,ReLU,Sigmoid,Tanh}-{zero-inflated,discrete,top-coded}]: 8 of 8 distinct output columns at output_dim=8. Fails on main and on Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56's branch, passes here.
• test_preprocessor_rbf_has_no_duplicate_columns_on_tied_data: the issue's Preprocessor case gives no duplicated column. Fails on main and on Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56's branch, passes here.

Reproduction

Output of the script from #82 on this branch. The script is extended with the two further cases from the issue text, 5 equally likely levels and a top capped at about 30 %, for all four feature maps:

centers: [0.0, 1.77, 5.05, 5.33, 15.16, 20.21, 30.31, 35.36]
distinct output columns: 8 of 8
Preprocessor rbf: distinct output columns: 7 of 7
5 levels
  RBF: distinct output columns: 8 of 8
  ReLU: distinct output columns: 8 of 8
  Sigmoid: distinct output columns: 8 of 8
  Tanh: distinct output columns: 8 of 8
top 30% capped (capped share 0.32)
  RBF: distinct output columns: 8 of 8
  ReLU: distinct output columns: 8 of 8
  Sigmoid: distinct output columns: 8 of 8
  Tanh: distinct output columns: 8 of 8

On main the same script prints 4 of 8, 4 of 7, 5 of 8 for every map, and 6 of 8 for every map.

Checks

• just test: 1478 passed, 59 skipped, 7 xfailed; coverage 93.55% (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): 1465 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

• This PR is stacked on Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56's branch fix/56-unique-interior-knots. The fix calls supplement_interior_knots, which the PR for 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) introduces in pretab/core/knots.py. On main alone this change fails at import. Adding the helper here as well would duplicate Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56's code and cause an add/add conflict in pretab/core/knots.py. GitHub shows only this issue's commit. The PR must be retargeted to main after the PR for 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) merges.
• The PR for Unsupervised ReLUExpansionTransformer puts its last center at the training maximum, giving a dead column #83 (fix(feature-maps): drop the unsupervised relu center at the data maximum #120) merges cleanly with this branch, because its hunks in relu.py are separate. ReLU with "quantile" centers on tied data needs both fixes. On the zero-inflated, discrete and top-coded features of the tests here, at output_dim=8:
  • With only this PR, the centers are distinct, but the last ramp still starts at the training maximum, so one column per feature is zero on the training data.
  • With only Unsupervised ReLUExpansionTransformer puts its last center at the training maximum, giving a dead column #83, tied quantiles still repeat. The top-coded feature, for example, keeps 2 zero columns and has 7 of 8 distinct columns.
  • With both, no column is zero and all 8 are distinct.
• Through Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56's commit, this branch also carries Spline knots on tied data land on the range boundary or repeat, producing dead columns and all-zero rows #56's conflict with the PR for 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) in pretab/expansion/spline/base.py. Resolve it as described in the PR for 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). This commit's own files conflict with no other per-issue PR.

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