From ba60c075642c940201f2efda8cb7f399512515fc Mon Sep 17 00:00:00 2001 From: luizfernandolj Date: Wed, 28 Oct 2026 16:36:30 -0300 Subject: [PATCH 1/3] HDx: bin raw features on their own scale HDx bins the raw features, but it inherited the histogram range of its score-space siblings: HistogramRepresentation defaults to range=(0, 1) with bin_edges="fixed", which is right for HDy and DyS, whose input is a posterior, and wrong for feature values. np.histogram drops whatever falls outside the range, so on unscaled data most of every feature was discarded and the estimate stopped depending on the test sample. Measured on make_classification with 6 features, a balanced training split and a shifted test sample. Positive-class estimate, before: true 0.1 -> 0.637 true 0.5 -> 0.632 true 0.9 -> 0.708 Close to a constant predictor. Only 25% of the feature cells were inside [0, 1]. After: true 0.1 -> 0.097 true 0.5 -> 0.486 true 0.9 -> 0.842 which matches QuaPy's DMx, QuantificationLib's HDX and qunfold's HDx at the same bin count to within 0.01, and a from-the-paper reference implementation (Gonzalez-Castro et al., 2013) to within 0.01 as well. Before the change mlquantify was the only one of the four that did not track the shift. MatchingHistogramQuantifier takes bin_edges, defaulting to "fixed" so that HDy, DyS and anything else in score space are untouched, and HDx asks for "auto": per-feature edges fitted on the training features, with the outer edges opened to +/-inf so test values beyond the training range land in the end bins instead of being dropped. The mechanism already existed in HistogramRepresentation; HDx simply never asked for it. GHDx was never affected: it fits its own edges. Four regression tests: that the estimate tracks the test prevalence at 0.1, 0.5 and 0.9 on unscaled features, and that it is invariant to min-max scaling. All three of the first fail on 0.5.1, off by 0.54, 0.13 and 0.19. The existing HDx test only asserted that the output was a valid prevalence vector, which a constant predictor satisfies. Co-Authored-By: Claude Opus 5 --- mlquantify/matching/_histogram.py | 10 +++++ tests/test_matching.py | 63 +++++++++++++++++++++++++++++++ 2 files changed, 73 insertions(+) diff --git a/mlquantify/matching/_histogram.py b/mlquantify/matching/_histogram.py index 8c199750..46e8a647 100644 --- a/mlquantify/matching/_histogram.py +++ b/mlquantify/matching/_histogram.py @@ -110,6 +110,7 @@ def __init__( histogram_features=None, bin_strategy=None, laplace_smoothing=False, + bin_edges="fixed", ): if bins_size is None: bins_size = np.append(np.linspace(2, 20, 10), 30).astype(int) @@ -122,6 +123,7 @@ def __init__( self.histogram_features = histogram_features self.bin_strategy = bin_strategy self.laplace_smoothing = laplace_smoothing + self.bin_edges = bin_edges super().__init__( representation=HistogramRepresentation( bins=bins_size, @@ -129,6 +131,7 @@ def __init__( features=histogram_features, partition_blocks=bin_strategy in {"median", "mean"}, laplace_smoothing=laplace_smoothing, + bin_edges=bin_edges, ), normalize=True, ) @@ -636,6 +639,13 @@ def __init__( distance="hellinger", solver="ternary", strategy=strategy, + # HDx bins raw features, which are on the data's own scale, so the + # bin edges come from the training features. The score-space + # siblings (HDy, DyS) keep the fixed [0, 1] edges, which is right + # for posteriors. With fixed edges here every feature value + # outside [0, 1] fell out of the histogram, and the estimate + # stopped depending on the test sample. + bin_edges="auto", ) def fit(self, X, y, sample_weight=None): diff --git a/tests/test_matching.py b/tests/test_matching.py index 9a636043..19d3ad46 100644 --- a/tests/test_matching.py +++ b/tests/test_matching.py @@ -57,6 +57,69 @@ def test_histogram_feature_matching_binary(binary_dataset): assert q.best_distance_ is not None +def _shifted_split(prevalence, seed=0, n_train=800, n_test=600): + """Balanced training split and a test sample at the given prevalence.""" + from sklearn.datasets import make_classification + + X, y = make_classification( + n_samples=4000, n_features=6, n_informative=4, n_redundant=0, + n_classes=2, random_state=seed, + ) + rng = np.random.default_rng(seed) + order = rng.permutation(len(y)) + X, y = X[order], y[order] + + train = np.concatenate([ + np.where(y == 0)[0][:n_train // 2], + np.where(y == 1)[0][:n_train // 2], + ]) + rest = np.setdiff1d(np.arange(len(y)), train) + n_pos = int(round(n_test * prevalence)) + test = np.concatenate([ + rest[y[rest] == 1][:n_pos], + rest[y[rest] == 0][:n_test - n_pos], + ]) + return X[train], y[train], X[test], y[test] + + +@pytest.mark.parametrize("prevalence", [0.1, 0.5, 0.9]) +def test_hdx_tracks_the_test_prevalence_on_unscaled_features(prevalence): + """HDx must bin raw features on their own scale. + + The bin edges used to be fixed to [0, 1], which is right for the + score-space siblings but discards every feature value outside that range. + The estimate then stopped depending on the test sample: it came out near + 0.64 whether the true prevalence was 0.1 or 0.9. + """ + X_train, y_train, X_test, y_test = _shifted_split(prevalence) + true_prevalence = float(np.mean(y_test == 1)) + + q = HDx(bins_size=[8]).fit(X_train, y_train) + with config_context(prevalence_return_type="array"): + estimate = np.asarray(q.predict(X_test), dtype=float) + + _assert_valid_prevalence(estimate, n_classes=2) + assert abs(estimate[1] - true_prevalence) < 0.1 + + +def test_hdx_is_invariant_to_feature_scaling(): + """Binning on the data's own scale makes a monotone rescaling irrelevant.""" + from sklearn.preprocessing import MinMaxScaler + + X_train, y_train, X_test, _ = _shifted_split(0.3) + scaler = MinMaxScaler().fit(X_train) + + def estimate(A, B): + q = HDx(bins_size=[8]).fit(A, y_train) + with config_context(prevalence_return_type="array"): + return np.asarray(q.predict(B), dtype=float) + + raw = estimate(X_train, X_test) + scaled = estimate(scaler.transform(X_train), scaler.transform(X_test)) + + np.testing.assert_allclose(raw, scaled, atol=0.05) + + def test_hdy_matches_median_grid_recipe(): train_scores = np.asarray( [ From ecb73d3f1a635d357325485ac9d8a70ad442cdb0 Mon Sep 17 00:00:00 2001 From: luizfernandolj Date: Mon, 9 Nov 2026 11:03:20 -0300 Subject: [PATCH 2/3] HDx: document bin_edges and qualify what auto edges fix bin_edges became a public constructor parameter of MatchingHistogramQuantifier without an entry in its Parameters section. Also narrows the claim in the HDx comment. Fitted edges come from the training features, so test values beyond the training range still fall out of the histogram -- a tail, where fixed [0, 1] edges discarded most of the data. And names the precedent: GHDx and GHDy already passed bin_edges="auto", so HDx was the one feature-space Hellinger quantifier still binning raw features into fixed edges. Co-Authored-By: Claude Opus 5 --- mlquantify/matching/_histogram.py | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/mlquantify/matching/_histogram.py b/mlquantify/matching/_histogram.py index 46e8a647..e3421d2e 100644 --- a/mlquantify/matching/_histogram.py +++ b/mlquantify/matching/_histogram.py @@ -77,6 +77,10 @@ class MatchingHistogramQuantifier(BaseMatchingQuantifier): Number of score columns used to build histograms. bin_strategy : str or None, default=None Aggregation strategy across bin sizes (``'median'`` or ``'mean'``). + bin_edges : {'fixed', 'auto'}, default='fixed' + Where the bin edges are placed. ``'fixed'`` spans ``[0, 1]``, which + is right for histograms of posteriors; ``'auto'`` fits the edges to + the range of the training data, which is what raw features need. Attributes ---------- @@ -639,12 +643,15 @@ def __init__( distance="hellinger", solver="ternary", strategy=strategy, - # HDx bins raw features, which are on the data's own scale, so the - # bin edges come from the training features. The score-space - # siblings (HDy, DyS) keep the fixed [0, 1] edges, which is right - # for posteriors. With fixed edges here every feature value - # outside [0, 1] fell out of the histogram, and the estimate - # stopped depending on the test sample. + # HDx bins raw features, which are on the data's own scale, so + # the bin edges come from the training features -- as GHDx and + # GHDy, the generalized siblings, already did. The score-space + # siblings (HDy, DyS) keep the fixed [0, 1] edges, which is + # right for posteriors. With fixed edges here every feature + # value outside [0, 1] fell out of the histogram, and the + # estimate stopped depending on the test sample. Edges fitted + # to the training range still drop test values beyond it, but + # that is a tail rather than most of the data. bin_edges="auto", ) From 7cf82624a858314feb9b8f9e858de4e179be9584 Mon Sep 17 00:00:00 2001 From: luizfernandolj Date: Mon, 9 Nov 2026 11:20:50 -0300 Subject: [PATCH 3/3] HDx: the outer bins are open, so nothing is dropped Corrects the previous commit, which claimed fitted edges still drop test values beyond the training range. They do not: _compute_histogram replaces the outer edges with -inf and +inf before calling np.histogram, so values past either end land in the end bins. The claim came from reading _fit_edges without reading where the edges are consumed. The Parameters entry now says so too, and stops asserting that 'fixed' is [0, 1] when it actually spans whatever `range` holds. Co-Authored-By: Claude Opus 5 --- mlquantify/matching/_histogram.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/mlquantify/matching/_histogram.py b/mlquantify/matching/_histogram.py index e3421d2e..d0c0f69f 100644 --- a/mlquantify/matching/_histogram.py +++ b/mlquantify/matching/_histogram.py @@ -78,9 +78,10 @@ class MatchingHistogramQuantifier(BaseMatchingQuantifier): bin_strategy : str or None, default=None Aggregation strategy across bin sizes (``'median'`` or ``'mean'``). bin_edges : {'fixed', 'auto'}, default='fixed' - Where the bin edges are placed. ``'fixed'`` spans ``[0, 1]``, which - is right for histograms of posteriors; ``'auto'`` fits the edges to - the range of the training data, which is what raw features need. + Where the bin edges are placed. ``'fixed'`` spans ``range``, + ``[0, 1]`` by default, which is right for histograms of posteriors. + ``'auto'`` fits per-feature edges to the training data and leaves + the outer bins unbounded, which is what raw features need. Attributes ---------- @@ -649,9 +650,10 @@ def __init__( # siblings (HDy, DyS) keep the fixed [0, 1] edges, which is # right for posteriors. With fixed edges here every feature # value outside [0, 1] fell out of the histogram, and the - # estimate stopped depending on the test sample. Edges fitted - # to the training range still drop test values beyond it, but - # that is a tail rather than most of the data. + # estimate stopped depending on the test sample. Fitted edges + # keep their outer bins open, at -inf and +inf, so test values + # beyond the training range land in the end bins instead of + # being dropped. bin_edges="auto", )