confound-controls 0.3.2__tar.gz → 0.4.0__tar.gz

{confound_controls-0.3.2 → confound_controls-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confound-controls
-Version: 0.3.2
+Version: 0.4.0
 Summary: Confound-matched controls for classifier claims: 1:1 matching, bootstrap AUROC, anchored verdicts, and a refusal when the control is vacuous.
 Author: Jaret Arnold
 License: GPL-3.0-or-later
@@ -81,6 +81,49 @@ comparison equals the unmatched one and will report the confound as ruled out.
 Pass `require_selective_match=False` if you mean it; the result then carries
 `match_selective=False` and `format_battery` prints `[VACUOUS CONTROL]`.
 
+## The same failure, one size up
+
+A pool bigger than the positive set passes that check and can fail the same
+way. Greedy matching spends the negatives that sit near the positives first;
+the rest of the positives are paired with whatever is left. The match is
+complete and selective, and still confounded. Through 0.3.2 this library
+scored it anyway: 300 positives, 900 negatives, a score computed from nothing
+but GC, matched on GC — verdict `confound-robust`, AUROC 0.807, battery PASS.
+
+`evaluate_confound` now measures what the match achieved and refuses when it
+achieved too little:
+
+```
+ValueError: gc: matching did not balance 'gc': |SMD| = 0.987 after matching
+(was 2.010) exceeds 0.1. The matched set is still confounded, so a classifier
+that separates it has not been shown to be robust to this confound.
+```
+
+The standardized mean difference is the difference in group means in units of
+a standard deviation, measured against the unmatched groups' spread before and
+after. `max_smd=0.1` is the conventional line; `max_smd=None` reports instead of
+raising (`result.balance`, and `[IMBALANCED]` in `format_battery`).
+
+Balance is bought with a **caliper**: a positive with no negative within
+`caliper` standard deviations is left unmatched and reported, rather than paired
+with something that does not resemble it. Only matched positives are scored.
+The same data with `caliper=0.1`:
+
+```
+gc   AUROC=0.5015 CI[0.4350,0.5652] recovery=0.00 npos=148 -> confound-driven
+     SMD before 2.010   SMD after 0.005   var ratio 1.017
+```
+
+With many confounds every sample is far from every other, and nearest-neighbour
+matching stops finding anyone. `method="propensity"` matches on the logit of
+P(positive | confounds) instead, hardest positives first, with the caliper in
+standard deviations of that logit (0.2 is the usual width). On the `lalonde`
+data it fits the same logits as R's MatchIt (to 1e-7), picks the same 184 pairs
+up to exact ties, and reports the same post-match SMDs to six decimals;
+`tests/data/` holds MatchIt's output and `tests/test_balance.py` compares
+against it. `standardized_mean_differences`, `balance_report` and
+`propensity_logit` are usable on their own.
+
 ## Verdicts
 
 | verdict           | meaning                                                                             |

{confound_controls-0.3.2 → confound_controls-0.4.0}/README.md

@@ -46,6 +46,49 @@ comparison equals the unmatched one and will report the confound as ruled out.
 Pass `require_selective_match=False` if you mean it; the result then carries
 `match_selective=False` and `format_battery` prints `[VACUOUS CONTROL]`.
 
+## The same failure, one size up
+
+A pool bigger than the positive set passes that check and can fail the same
+way. Greedy matching spends the negatives that sit near the positives first;
+the rest of the positives are paired with whatever is left. The match is
+complete and selective, and still confounded. Through 0.3.2 this library
+scored it anyway: 300 positives, 900 negatives, a score computed from nothing
+but GC, matched on GC — verdict `confound-robust`, AUROC 0.807, battery PASS.
+
+`evaluate_confound` now measures what the match achieved and refuses when it
+achieved too little:
+
+```
+ValueError: gc: matching did not balance 'gc': |SMD| = 0.987 after matching
+(was 2.010) exceeds 0.1. The matched set is still confounded, so a classifier
+that separates it has not been shown to be robust to this confound.
+```
+
+The standardized mean difference is the difference in group means in units of
+a standard deviation, measured against the unmatched groups' spread before and
+after. `max_smd=0.1` is the conventional line; `max_smd=None` reports instead of
+raising (`result.balance`, and `[IMBALANCED]` in `format_battery`).
+
+Balance is bought with a **caliper**: a positive with no negative within
+`caliper` standard deviations is left unmatched and reported, rather than paired
+with something that does not resemble it. Only matched positives are scored.
+The same data with `caliper=0.1`:
+
+```
+gc   AUROC=0.5015 CI[0.4350,0.5652] recovery=0.00 npos=148 -> confound-driven
+     SMD before 2.010   SMD after 0.005   var ratio 1.017
+```
+
+With many confounds every sample is far from every other, and nearest-neighbour
+matching stops finding anyone. `method="propensity"` matches on the logit of
+P(positive | confounds) instead, hardest positives first, with the caliper in
+standard deviations of that logit (0.2 is the usual width). On the `lalonde`
+data it fits the same logits as R's MatchIt (to 1e-7), picks the same 184 pairs
+up to exact ties, and reports the same post-match SMDs to six decimals;
+`tests/data/` holds MatchIt's output and `tests/test_balance.py` compares
+against it. `standardized_mean_differences`, `balance_report` and
+`propensity_logit` are usable on their own.
+
 ## Verdicts
 
 | verdict           | meaning                                                                             |

{confound_controls-0.3.2 → confound_controls-0.4.0}/confound_controls/__init__.py

@@ -14,6 +14,7 @@ from .ablation import (
     ablation_control,
     assert_ablation_changed_input,
 )
+from .balance import BalanceReport, balance_report, standardized_mean_differences
 from .battery import (
     ConfoundResult,
     battery_passes,
@@ -30,7 +31,7 @@ from .incremental import (
     incremental_validity,
     paired_delta_auroc,
 )
-from .matching import MatchResult, match_negatives
+from .matching import MatchResult, match_negatives, propensity_logit
 from .metrics import (
     DRIVEN,
     INCONCLUSIVE,
@@ -56,7 +57,7 @@ from .sequence import (
     sample_control_span,
 )
 
-__version__ = "0.3.2"
+__version__ = "0.4.0"
 
 __all__ = [
     "ABLATION_INCONCLUSIVE",
@@ -75,6 +76,7 @@ __all__ = [
     "UNDERPOWERED",
     "AblationResult",
     "AurocCI",
+    "BalanceReport",
     "ConfoundResult",
     "ControlSpan",
     "DeltaResult",
@@ -83,6 +85,7 @@ __all__ = [
     "ShuffleResult",
     "ablation_control",
     "assert_ablation_changed_input",
+    "balance_report",
     "battery_passes",
     "bootstrap_auroc",
     "confirm_knockout",
@@ -95,8 +98,10 @@ __all__ = [
     "knockout_span",
     "match_negatives",
     "paired_delta_auroc",
+    "propensity_logit",
     "recovery",
     "run_battery",
     "sample_control_span",
+    "standardized_mean_differences",
     "verdict",
 ]

confound_controls-0.4.0/confound_controls/balance.py

@@ -0,0 +1,174 @@
+"""Did the match balance the confound, or only pair things up?
+
+`MatchResult.complete` and `.selective` answer "did every positive get its own
+negative" and "did matching choose". Neither asks the question matching exists
+to answer. Greedy 1:1 matching without replacement spends the negatives that
+sit near the positives first; whoever is left is paired with whatever is left.
+The result is a complete, selective match that is still confounded -- and a
+classifier that still separates it is then reported as having survived the
+control. On a classifier that was NOTHING BUT the confound, 0.3.2 returned
+"confound-robust".
+
+The standardized mean difference, with the variance ratio for continuous
+confounds, is the usual check on a matched sample (Austin 2009,
+doi:10.1002/sim.3697): the difference in group means in units of a standard
+deviation, which unlike a t-test does not shrink just because matching threw
+samples away. |SMD| < 0.1 is the conventional line for "balanced"; it is a
+convention, and `max_smd` is a parameter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+_DENOMINATORS = ("pooled", "positives")
+
+
+def _as_matrix(x) -> np.ndarray:
+    a = np.asarray(x, dtype=float)
+    if a.ndim == 1:
+        a = a.reshape(-1, 1)
+    if a.ndim != 2:
+        raise ValueError(f"expected a 2-D (n_samples, n_confounds) array, got {a.ndim}-D")
+    return a
+
+
+def _is_binary(*columns: np.ndarray) -> bool:
+    return bool(np.isin(np.concatenate(columns), (0.0, 1.0)).all())
+
+
+def _variance(col: np.ndarray, binary: bool) -> float:
+    """Variance of one group's column. A 0/1 column uses p(1-p): its spread is a
+    function of its mean, and the sample estimate only adds noise to that."""
+    if binary:
+        p = float(col.mean())
+        return p * (1.0 - p)
+    return float(col.var(ddof=1)) if len(col) > 1 else 0.0
+
+
+def standardized_mean_differences(pos, neg, *, denominator: str = "pooled", reference=None) -> list:
+    """Per-confound (mean_pos - mean_neg) / sd.
+
+    Args:
+        pos, neg: (n, n_confounds) confound values of the two groups compared.
+        denominator: "pooled" -- sqrt((var_pos + var_neg) / 2), symmetric in the
+            groups; or "positives" -- the positives' SD, which is
+            what MatchIt's `summary()` reports for 1:1 matching to a fixed group.
+        reference: optional (pos, neg) pair the SD is taken FROM. Pass the
+            unmatched groups when measuring a matched sample, so that before and
+            after share one yardstick; otherwise matching can "improve" an SMD
+            merely by changing the spread it is divided by.
+
+    A confound with no spread gives 0.0 when the means agree and inf when they
+    do not: the groups differ by something no amount of standardising can scale.
+    """
+    if denominator not in _DENOMINATORS:
+        raise ValueError(f"denominator must be one of {_DENOMINATORS}, got {denominator!r}")
+    pos, neg = _as_matrix(pos), _as_matrix(neg)
+    if pos.shape[1] != neg.shape[1]:
+        raise ValueError(f"confound count differs: {pos.shape[1]} vs {neg.shape[1]}")
+    if not len(pos) or not len(neg):
+        raise ValueError(f"need both groups; got {len(pos)} positives and {len(neg)} negatives")
+    ref_pos, ref_neg = (pos, neg) if reference is None else map(_as_matrix, reference)
+    out = []
+    for j in range(pos.shape[1]):
+        binary = _is_binary(ref_pos[:, j], ref_neg[:, j])
+        v_pos = _variance(ref_pos[:, j], binary)
+        v_neg = _variance(ref_neg[:, j], binary)
+        sd = np.sqrt((v_pos + v_neg) / 2.0) if denominator == "pooled" else np.sqrt(v_pos)
+        diff = float(pos[:, j].mean() - neg[:, j].mean())
+        if sd == 0:
+            out.append(0.0 if diff == 0 else float(np.copysign(np.inf, diff)))
+        else:
+            out.append(diff / float(sd))
+    return out
+
+
+@dataclass(frozen=True)
+class BalanceReport:
+    """Confound balance before and after matching, one entry per column."""
+
+    columns: list
+    smd_before: list
+    smd_after: list
+    variance_ratio_after: list
+    n_positives_after: int
+    n_negatives_after: int
+    denominator: str = "pooled"
+
+    @property
+    def max_abs_smd_before(self) -> float:
+        return float(np.max(np.abs(self.smd_before)))
+
+    @property
+    def max_abs_smd_after(self) -> float:
+        return float(np.max(np.abs(self.smd_after)))
+
+    @property
+    def worst_column(self):
+        return self.columns[int(np.argmax(np.abs(self.smd_after)))]
+
+    def balanced(self, threshold: float = 0.1) -> bool:
+        return self.max_abs_smd_after <= threshold
+
+    def require_balanced(self, threshold: float = 0.1, *, name: str = "match") -> BalanceReport:
+        if not self.balanced(threshold):
+            raise ValueError(
+                f"{name}: matching did not balance '{self.worst_column}': "
+                f"|SMD| = {self.max_abs_smd_after:.3f} after matching "
+                f"(was {self.max_abs_smd_before:.3f}) exceeds {threshold}. The matched "
+                f"set is still confounded, so a classifier that separates it has not "
+                f"been shown to be robust to this confound. Pass caliper=... to drop "
+                f"positives with no close negative (try 0.2), supply a larger negative "
+                f"pool, or pass max_smd=None to inspect the result anyway."
+            )
+        return self
+
+    def format(self) -> str:
+        width = max(len(str(c)) for c in self.columns)
+        lines = [f"  {'confound':{width}s}  SMD before  SMD after  var ratio"]
+        for c, b, a, v in zip(
+            self.columns, self.smd_before, self.smd_after, self.variance_ratio_after
+        ):
+            ratio = "      -" if np.isnan(v) else f"{v:7.3f}"
+            lines.append(f"  {c!s:{width}s}  {b:10.3f}  {a:9.3f}  {ratio}")
+        return "\n".join(lines)
+
+
+def balance_report(
+    pos, neg, matched_pos, matched_neg, *, columns=None, denominator: str = "pooled"
+) -> BalanceReport:
+    """Balance of `matched_pos` vs `matched_neg`, against the unmatched `pos` vs `neg`.
+
+    Both SMDs are standardised by the UNMATCHED groups' spread. The variance
+    ratio (positives / negatives, after matching) is nan for a 0/1 column, where
+    it is a restatement of the mean difference and reads as extra evidence.
+    """
+    names = list(columns) if columns is not None else list(getattr(pos, "columns", []))
+    pos, neg = _as_matrix(pos), _as_matrix(neg)
+    matched_pos, matched_neg = _as_matrix(matched_pos), _as_matrix(matched_neg)
+    if not names:
+        names = [f"x{j}" for j in range(pos.shape[1])]
+    if len(names) != pos.shape[1]:
+        raise ValueError(f"{len(names)} column names for {pos.shape[1]} confounds")
+    ratios = []
+    for j in range(pos.shape[1]):
+        if _is_binary(pos[:, j], neg[:, j]):
+            ratios.append(float("nan"))
+            continue
+        v_neg = _variance(matched_neg[:, j], False)
+        v_pos = _variance(matched_pos[:, j], False)
+        ratios.append(v_pos / v_neg if v_neg > 0 else float("inf" if v_pos > 0 else "nan"))
+    return BalanceReport(
+        columns=names,
+        smd_before=standardized_mean_differences(pos, neg, denominator=denominator),
+        smd_after=standardized_mean_differences(
+            matched_pos, matched_neg, denominator=denominator, reference=(pos, neg)
+        ),
+        variance_ratio_after=ratios,
+        n_positives_after=len(matched_pos),
+        n_negatives_after=len(matched_neg),
+        denominator=denominator,
+    )

{confound_controls-0.3.2 → confound_controls-0.4.0}/confound_controls/battery.py

@@ -25,6 +25,7 @@ from dataclasses import dataclass, field
 import numpy as np
 import pandas as pd
 
+from .balance import BalanceReport, balance_report
 from .matching import match_negatives
 from .metrics import AurocCI, bootstrap_auroc, recovery, verdict
 
@@ -40,6 +41,8 @@ class ConfoundResult:
     match_complete: bool
     match_selective: bool
     unmatched_positions: list = field(default_factory=list)
+    # None only on results built by hand; `evaluate_confound` always fills it.
+    balance: BalanceReport | None = None
 
 
 def evaluate_confound(
@@ -52,12 +55,32 @@ def evaluate_confound(
     id_column: str = "id",
     label_column: str = "label",
     recovery_threshold: float = 0.70,
-    require_complete_match: bool = True,
+    method: str = "nearest",
+    caliper: float | None = None,
+    max_smd: float | None = 0.1,
+    smd_denominator: str = "pooled",
+    require_complete_match: bool | None = None,
     require_selective_match: bool = True,
     bootstrap_n: int = 2000,
     seed: int = 42,
 ) -> ConfoundResult:
-    """Match negatives to positives on `columns`, then re-score on the subset."""
+    """Match negatives to positives on `columns`, then re-score on the matched pairs.
+
+    `max_smd` is the balance the match must reach before its AUROC means
+    anything: above it the matched set is still confounded, and a classifier
+    that separates it has survived nothing. None reports the imbalance in
+    `.balance` instead of raising. A `caliper` is how balance is bought -- by
+    dropping the positives that have no close negative -- so with one set an
+    incomplete match is the design, not a failure: `require_complete_match`
+    defaults to True without a caliper and False with one.
+
+    Only matched positives are scored. 0.3.2 scored every positive against the
+    fewer matched negatives, which put the unmatched positives -- the ones in the
+    region the pool could not cover -- back into a comparison that claimed to be
+    1:1 matched.
+    """
+    if require_complete_match is None:
+        require_complete_match = caliper is None
     missing = [c for c in list(columns) + [id_column, label_column] if c not in df.columns]
     if missing:
         raise ValueError(
@@ -85,13 +108,34 @@ def evaluate_confound(
         pos[list(columns)].to_numpy(),
         neg[id_column].tolist(),
         neg[list(columns)].to_numpy(),
+        method=method,
+        caliper=caliper,
     )
     if require_complete_match:
         match.require_complete()
     if require_selective_match:
         match.require_selective()
+    if not match.matched_ids:
+        raise ValueError(
+            f"{name}: no positive found a negative"
+            + (f" within caliper {caliper}" if caliper is not None else "")
+            + "; there is nothing to evaluate"
+        )
+
+    matched_pos = pos.iloc[match.matched_positions]
+    matched_neg = neg.set_index(id_column, drop=False).loc[match.matched_ids]
+    balance = balance_report(
+        pos[list(columns)].to_numpy(),
+        neg[list(columns)].to_numpy(),
+        matched_pos[list(columns)].to_numpy(),
+        matched_neg[list(columns)].to_numpy(),
+        columns=list(columns),
+        denominator=smd_denominator,
+    )
+    if max_smd is not None:
+        balance.require_balanced(max_smd, name=name)
 
-    eval_ids = set(pos[id_column].tolist()) | set(match.matched_ids)
+    eval_ids = set(matched_pos[id_column].tolist()) | set(match.matched_ids)
     sub = df[df[id_column].isin(eval_ids)]
 
     unknown = [g for g in sub[id_column] if g not in prob_map]
@@ -115,6 +159,7 @@ def evaluate_confound(
         match_complete=match.complete,
         match_selective=match.selective,
         unmatched_positions=list(match.unmatched_positions),
+        balance=balance,
     )
 
 
@@ -153,9 +198,15 @@ def battery_passes(results: Mapping[str, ConfoundResult]) -> bool:
 def format_battery(results: Mapping[str, ConfoundResult], anchor: float) -> str:
     lines = [f"confound battery (anchor AUROC={anchor:.4f})", ""]
     for name, r in results.items():
-        flag = "" if r.match_complete else "  [INCOMPLETE MATCH]"
+        flag = (
+            ""
+            if r.match_complete
+            else f"  [INCOMPLETE MATCH: {len(r.unmatched_positions)} positives left out]"
+        )
         if not r.match_selective:
             flag += "  [VACUOUS CONTROL: whole pool used]"
+        if r.balance is not None and not r.balance.balanced():
+            flag += f"  [IMBALANCED: max |SMD| = {r.balance.max_abs_smd_after:.3f}]"
         lines.append(
             f"  {name:18s} AUROC={r.ci.point:.4f} "
             f"CI[{r.ci.lo:.4f},{r.ci.hi:.4f}] "

confound_controls-0.4.0/confound_controls/matching.py

@@ -0,0 +1,259 @@
+"""Match negatives to positives on confounds, and say so when you cannot.
+
+Extracted from an internal matched-negatives script (also present
+byte-identical in a second internal project -- the code was copied between two
+independent repos, which is what marked it as worth extracting).
+
+The matching itself is unchanged. What changed is that it now reports whether
+it achieved the 1:1 match it advertises. The original looped
+
+    while True:
+        ...
+        if pick is not None: ...; break
+        if k >= len(neg_ids): break     # <- silently gives up on this positive
+        k *= 2
+
+so once the negative pool was exhausted it returned FEWER negatives than
+positives and said nothing. A caller comparing AUROC before and after matching
+could not tell a clean 1:1 design from one that quietly dropped a third of its
+positives -- and the drop is not random, it hits the positives in the densest
+region of confound space, exactly where matching matters most.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy.spatial import cKDTree
+
+
+@dataclass(frozen=True)
+class MatchResult:
+    """Outcome of a matching attempt.
+
+    `complete` is the question a caller actually needs answered: did every
+    positive get its own negative? `unmatched_positions` gives the indices of
+    the positives that did not, so the caller can inspect rather than guess.
+    """
+
+    matched_ids: list
+    unmatched_positions: list
+    n_positives: int
+    n_pool: int = 0
+    # Parallel to `matched_ids`: which positive each negative was matched to, and
+    # how far apart they are in the space that was matched on (standardised
+    # confounds, or the propensity logit). Without these a caller cannot rebuild
+    # the pairs, and so cannot check what the match achieved.
+    matched_positions: list = field(default_factory=list)
+    distances: list = field(default_factory=list)
+    # The caliper actually applied, in the units of `distances`; None = none.
+    caliper: float | None = None
+
+    @property
+    def complete(self) -> bool:
+        return not self.unmatched_positions
+
+    @property
+    def n_matched(self) -> int:
+        return len(self.matched_ids)
+
+    @property
+    def selective(self) -> bool:
+        """Did matching actually CHOOSE, or take the whole pool?
+
+        1:1 matching without replacement from a pool the same size as the
+        positive set consumes every negative, whatever the confound values are.
+        The "matched" comparison is then byte-identical to the unmatched one,
+        so the control is vacuous -- and a vacuous control does not report
+        "inconclusive", it reports the original result, which reads as the
+        confound having been ruled out.
+        """
+        return self.n_matched < self.n_pool
+
+    def require_complete(self) -> MatchResult:
+        if not self.complete:
+            raise ValueError(
+                f"matched only {self.n_matched} of {self.n_positives} positives; "
+                f"the negative pool ran out. Unmatched positive positions: "
+                f"{self.unmatched_positions[:10]}"
+                f"{'...' if len(self.unmatched_positions) > 10 else ''}"
+            )
+        return self
+
+    def require_selective(self) -> MatchResult:
+        if not self.selective:
+            raise ValueError(
+                f"matching consumed the entire negative pool "
+                f"({self.n_matched} matched from {self.n_pool} available), so it "
+                f"selected nothing and the control is vacuous -- the matched "
+                f"comparison equals the unmatched one and will report the "
+                f"confound as ruled out. Supply more negatives than positives, "
+                f"or pass require_selective_match=False if you intend this."
+            )
+        return self
+
+
+METHODS = ("nearest", "propensity")
+_NEWTON_MAX_ITER = 100
+# |logit| this large is a fitted probability within 1e-13 of 0 or 1: separation.
+_LOGIT_LIMIT = 30.0
+
+
+def propensity_logit(pos_vecs, neg_vecs) -> tuple[np.ndarray, np.ndarray]:
+    """Logit of P(positive | confounds) for each positive and each negative.
+
+    An unpenalised logistic regression fitted by Newton's method, i.e. what R's
+    `glm(..., binomial)` fits (it agrees with MatchIt's to 1e-7 on the lalonde
+    data). Not scikit-learn's: its default L2 penalty shrinks the coefficients by
+    an amount that depends on the units the confounds happen to be in. The logit
+    rather than the probability because it is roughly normal, so a distance (and
+    a caliper) means the same thing in the tails as in the middle.
+
+    Raises if the confounds separate the classes perfectly. No propensity score
+    exists then -- the likelihood has no maximum -- and no negative resembles
+    any positive, which is an answer about the data and not something to match
+    through.
+    """
+    pos_vecs = np.asarray(pos_vecs, dtype=float)
+    neg_vecs = np.asarray(neg_vecs, dtype=float)
+    x = np.vstack([pos_vecs, neg_vecs])
+    y = np.r_[np.ones(len(pos_vecs)), np.zeros(len(neg_vecs))]
+    if not len(pos_vecs) or not len(neg_vecs):
+        raise ValueError("a propensity model needs both positives and negatives")
+    mu, sd = x.mean(0), x.std(0)
+    keep = sd > 0  # a constant column carries no information and is collinear with the intercept
+    design = np.column_stack([np.ones(len(x)), (x[:, keep] - mu[keep]) / sd[keep]])
+    beta = np.zeros(design.shape[1])
+    for _ in range(_NEWTON_MAX_ITER):
+        eta = design @ beta
+        p = 1.0 / (1.0 + np.exp(-eta))
+        w = p * (1.0 - p)
+        hessian = design.T @ (design * w[:, None])
+        try:
+            step = np.linalg.solve(hessian, design.T @ (y - p))
+        except np.linalg.LinAlgError:
+            step = None
+        if step is None or not np.isfinite(step).all() or np.abs(eta).max() > _LOGIT_LIMIT:
+            break
+        beta = beta + step
+        if np.abs(step).max() < 1e-10:
+            logit = design @ beta
+            return logit[: len(pos_vecs)], logit[len(pos_vecs) :]
+    raise ValueError(
+        "the propensity model did not converge: the confounds separate positives "
+        "from negatives (almost) perfectly, or are collinear. With no overlap "
+        "there is no negative that resembles a positive on these confounds, so "
+        "matching cannot control for them."
+    )
+
+
+def match_negatives(
+    pos_vecs, neg_ids, neg_vecs, *, method: str = "nearest", caliper: float | None = None
+) -> MatchResult:
+    """Greedy 1:1 nearest-neighbour match without replacement.
+
+    `method="nearest"` measures distance on the standardised confound columns
+    (standardised over positives and negatives jointly, so a confound on a wide
+    scale does not dominate through its units). `method="propensity"` collapses
+    the confounds to one number first -- the logit of the propensity score --
+    which is what keeps matching workable once there are many confounds and
+    every sample is far from every other. Positives are then taken in order of
+    decreasing propensity: the hardest to match choose first, while the
+    negatives that could serve them are still available.
+
+    A `caliper` refuses a pairing further apart than that many standard
+    deviations -- of the standardised columns (i.e. raw units of distance) for
+    "nearest", of the propensity logit for "propensity", where 0.2 standard
+    deviations of the logit is the recommended width (Austin 2011,
+    doi:10.1002/pst.433). A positive with no unused
+    negative inside the caliper is left unmatched and reported, not paired with
+    something that does not resemble it.
+
+    Args:
+        pos_vecs: (n_pos, n_confounds) confound values for the positives.
+        neg_ids: identifiers for the negatives, parallel to `neg_vecs`.
+        neg_vecs: (n_neg, n_confounds) confound values for the negatives.
+
+    Returns:
+        MatchResult -- inspect `.complete` before trusting a downstream metric,
+        or call `.require_complete()` to make an incomplete match an error.
+    """
+    pos_vecs = np.asarray(pos_vecs, dtype=float)
+    neg_vecs = np.asarray(neg_vecs, dtype=float)
+    neg_ids = list(neg_ids)
+
+    if pos_vecs.ndim != 2 or neg_vecs.ndim != 2:
+        raise ValueError("pos_vecs and neg_vecs must both be 2-D")
+    if pos_vecs.shape[1] != neg_vecs.shape[1]:
+        raise ValueError(
+            f"confound count differs: positives have {pos_vecs.shape[1]}, "
+            f"negatives have {neg_vecs.shape[1]}"
+        )
+    if len(neg_ids) != neg_vecs.shape[0]:
+        raise ValueError(
+            f"neg_ids has {len(neg_ids)} entries but neg_vecs has {neg_vecs.shape[0]} rows"
+        )
+    if method not in METHODS:
+        raise ValueError(f"method must be one of {METHODS}, got {method!r}")
+    if caliper is not None and not caliper > 0:
+        raise ValueError(f"caliper must be positive, got {caliper!r}")
+    if not len(neg_ids):
+        return MatchResult([], list(range(len(pos_vecs))), len(pos_vecs), 0)
+    if not len(pos_vecs):
+        return MatchResult([], [], 0, len(neg_ids))
+
+    order = range(len(pos_vecs))
+    limit = caliper
+    if method == "propensity":
+        pos_logit, neg_logit = propensity_logit(pos_vecs, neg_vecs)
+        pos_s, neg_s = pos_logit.reshape(-1, 1), neg_logit.reshape(-1, 1)
+        order = np.argsort(-pos_logit, kind="stable")
+        if caliper is not None:
+            # In SDs of the logit over every sample, positives and negatives
+            # together -- the scale MatchIt's `std.caliper` uses.
+            limit = float(caliper * np.r_[pos_logit, neg_logit].std(ddof=1))
+    else:
+        allv = np.vstack([pos_vecs, neg_vecs])
+        mu, sd = allv.mean(0), allv.std(0)
+        # A confound that is constant across every sample carries no information;
+        # dividing by its zero spread would produce nan distances and match at
+        # random, which looks exactly like a successful match.
+        sd = np.where(sd == 0, 1.0, sd)
+        pos_s = (pos_vecs - mu) / sd
+        neg_s = (neg_vecs - mu) / sd
+
+    tree = cKDTree(neg_s)
+    used: set[int] = set()
+    picks: dict[int, tuple[int, float]] = {}
+
+    for position in order:
+        p = pos_s[position]
+        k = 1
+        pick = None
+        while True:
+            k = min(k, len(neg_ids))
+            dists, idxs = tree.query(p, k=k)
+            dists, idxs = np.atleast_1d(dists), np.atleast_1d(idxs)
+            pick = next(((int(i), float(d)) for d, i in zip(dists, idxs) if i not in used), None)
+            # Neighbours come back nearest first, so once the furthest one seen
+            # is outside the caliper no unseen one can be inside it.
+            beyond = limit is not None and dists[-1] > limit
+            if pick is not None or k >= len(neg_ids) or beyond:
+                break
+            k *= 2
+        if pick is not None and (limit is None or pick[1] <= limit):
+            used.add(pick[0])
+            picks[int(position)] = pick
+
+    # Report in the positives' own order whatever order they were matched in.
+    positions = sorted(picks)
+    return MatchResult(
+        matched_ids=[neg_ids[picks[i][0]] for i in positions],
+        unmatched_positions=[i for i in range(len(pos_s)) if i not in picks],
+        n_positives=len(pos_s),
+        n_pool=len(neg_ids),
+        matched_positions=positions,
+        distances=[picks[i][1] for i in positions],
+        caliper=limit,
+    )

{confound_controls-0.3.2 → confound_controls-0.4.0}/confound_controls.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confound-controls
-Version: 0.3.2
+Version: 0.4.0
 Summary: Confound-matched controls for classifier claims: 1:1 matching, bootstrap AUROC, anchored verdicts, and a refusal when the control is vacuous.
 Author: Jaret Arnold
 License: GPL-3.0-or-later
@@ -81,6 +81,49 @@ comparison equals the unmatched one and will report the confound as ruled out.
 Pass `require_selective_match=False` if you mean it; the result then carries
 `match_selective=False` and `format_battery` prints `[VACUOUS CONTROL]`.
 
+## The same failure, one size up
+
+A pool bigger than the positive set passes that check and can fail the same
+way. Greedy matching spends the negatives that sit near the positives first;
+the rest of the positives are paired with whatever is left. The match is
+complete and selective, and still confounded. Through 0.3.2 this library
+scored it anyway: 300 positives, 900 negatives, a score computed from nothing
+but GC, matched on GC — verdict `confound-robust`, AUROC 0.807, battery PASS.
+
+`evaluate_confound` now measures what the match achieved and refuses when it
+achieved too little:
+
+```
+ValueError: gc: matching did not balance 'gc': |SMD| = 0.987 after matching
+(was 2.010) exceeds 0.1. The matched set is still confounded, so a classifier
+that separates it has not been shown to be robust to this confound.
+```
+
+The standardized mean difference is the difference in group means in units of
+a standard deviation, measured against the unmatched groups' spread before and
+after. `max_smd=0.1` is the conventional line; `max_smd=None` reports instead of
+raising (`result.balance`, and `[IMBALANCED]` in `format_battery`).
+
+Balance is bought with a **caliper**: a positive with no negative within
+`caliper` standard deviations is left unmatched and reported, rather than paired
+with something that does not resemble it. Only matched positives are scored.
+The same data with `caliper=0.1`:
+
+```
+gc   AUROC=0.5015 CI[0.4350,0.5652] recovery=0.00 npos=148 -> confound-driven
+     SMD before 2.010   SMD after 0.005   var ratio 1.017
+```
+
+With many confounds every sample is far from every other, and nearest-neighbour
+matching stops finding anyone. `method="propensity"` matches on the logit of
+P(positive | confounds) instead, hardest positives first, with the caliper in
+standard deviations of that logit (0.2 is the usual width). On the `lalonde`
+data it fits the same logits as R's MatchIt (to 1e-7), picks the same 184 pairs
+up to exact ties, and reports the same post-match SMDs to six decimals;
+`tests/data/` holds MatchIt's output and `tests/test_balance.py` compares
+against it. `standardized_mean_differences`, `balance_report` and
+`propensity_logit` are usable on their own.
+
 ## Verdicts
 
 | verdict           | meaning                                                                             |

{confound_controls-0.3.2 → confound_controls-0.4.0}/confound_controls.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 confound_controls/__init__.py
 confound_controls/ablation.py
+confound_controls/balance.py
 confound_controls/battery.py
 confound_controls/incremental.py
 confound_controls/matching.py
@@ -14,6 +15,7 @@ confound_controls.egg-info/dependency_links.txt
 confound_controls.egg-info/requires.txt
 confound_controls.egg-info/top_level.txt
 tests/test_ablation.py
+tests/test_balance.py
 tests/test_battery.py
 tests/test_incremental.py
 tests/test_matching.py

{confound_controls-0.3.2 → confound_controls-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "confound-controls"
-version = "0.3.2"
+version = "0.4.0"
 description = "Confound-matched controls for classifier claims: 1:1 matching, bootstrap AUROC, anchored verdicts, and a refusal when the control is vacuous."
 readme = "README.md"
 requires-python = ">=3.10"

confound_controls-0.4.0/tests/test_balance.py

@@ -0,0 +1,199 @@
+"""Balance diagnostics, calipers and propensity matching.
+
+The defect these exist for: 0.3.2 reported a match as `complete` and
+`selective` and never asked whether it had BALANCED anything. Greedy 1:1
+matching without replacement runs out of nearby negatives; the remaining
+positives are paired with whatever is left. The matched set is still confounded,
+the classifier still separates it, and the battery reads that as the signal
+having survived the control -- "confound-robust" -- for a classifier that is
+nothing but the confound.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from confound_controls import (
+    DRIVEN,
+    balance_report,
+    evaluate_confound,
+    format_battery,
+    match_negatives,
+    propensity_logit,
+    run_battery,
+    standardized_mean_differences,
+)
+
+DATA = Path(__file__).parent / "data"
+COVARIATES = ["age", "educ", "married", "nodegree", "re74", "re75"]
+
+# summary(matchit(...)) from MatchIt 4.5.5, copied from the R console.
+MATCHIT_SMD_ALL = [-0.309445, 0.054965, -0.826309, 0.244970, -0.721084, -0.290263]
+MATCHIT_SMD_MATCHED = [0.037219, -0.116229, 0.000000, 0.095634, -0.070019, -0.003952]
+MATCHIT_VARRATIO_ALL = {"age": 0.439995, "educ": 0.495893, "re74": 0.518128, "re75": 0.956293}
+MATCHIT_CALIPER = 0.2015685002
+
+
+@pytest.fixture(scope="module")
+def lalonde():
+    df = pd.read_csv(DATA / "lalonde.csv")
+    return df[df.treat == 1], df[df.treat == 0], df
+
+
+def confounded_frame(n_pos=300, n_neg=900, shift=2.0, seed=0):
+    rng = np.random.default_rng(seed)
+    gc = np.r_[rng.normal(shift, 1, n_pos), rng.normal(0, 1, n_neg)]
+    df = pd.DataFrame(
+        {
+            "id": [f"s{i}" for i in range(n_pos + n_neg)],
+            "label": [1] * n_pos + [0] * n_neg,
+            "gc": gc,
+        }
+    )
+    prob = dict(zip(df.id, 1 / (1 + np.exp(-gc))))  # the classifier IS the confound
+    y = df.label.to_numpy()
+    p = np.array([prob[i] for i in df.id])
+    from sklearn.metrics import roc_auc_score
+
+    return df, prob, float(roc_auc_score(y, p))
+
+
+def test_smd_and_variance_ratio_agree_with_matchit(lalonde):
+    pos, neg, _ = lalonde
+    smd = standardized_mean_differences(pos[COVARIATES], neg[COVARIATES], denominator="positives")
+    assert smd == pytest.approx(MATCHIT_SMD_ALL, abs=5e-6)
+    report = balance_report(pos[COVARIATES], neg[COVARIATES], pos[COVARIATES], neg[COVARIATES])
+    for col, want in MATCHIT_VARRATIO_ALL.items():
+        assert report.variance_ratio_after[COVARIATES.index(col)] == pytest.approx(want, abs=5e-6)
+    # A variance ratio is not defined for a 0/1 column; reporting one invites reading it.
+    assert np.isnan(report.variance_ratio_after[COVARIATES.index("married")])
+
+
+def test_pooled_denominator_is_the_mean_of_the_two_variances():
+    pos = np.array([[0.0], [2.0], [4.0]])  # var 4
+    neg = np.array([[0.0], [1.0], [2.0]])  # var 1, mean diff 1
+    assert standardized_mean_differences(pos, neg) == pytest.approx([1 / np.sqrt(2.5)])
+    assert standardized_mean_differences(pos, neg, denominator="positives") == pytest.approx([0.5])
+
+
+def test_constant_column_is_zero_when_equal_and_infinite_when_not():
+    same = standardized_mean_differences(np.ones((3, 1)), np.ones((4, 1)))
+    apart = standardized_mean_differences(np.ones((3, 1)), np.zeros((4, 1)))
+    assert same == [0.0]
+    assert apart == [np.inf]
+
+
+def test_propensity_logit_agrees_with_matchit_glm(lalonde):
+    pos, neg, _ = lalonde
+    ref = pd.read_csv(DATA / "lalonde_matchit_logit.csv").set_index("id").logit
+    pos_logit, neg_logit = propensity_logit(pos[COVARIATES], neg[COVARIATES])
+    assert np.max(np.abs(pos_logit - ref.loc[pos.id].to_numpy())) < 1e-6
+    assert np.max(np.abs(neg_logit - ref.loc[neg.id].to_numpy())) < 1e-6
+
+
+def test_perfectly_separated_confound_has_no_propensity_score():
+    with pytest.raises(ValueError, match="did not converge: the confounds separate"):
+        propensity_logit(np.array([[5.0], [6.0], [7.0]]), np.array([[0.0], [1.0], [2.0]]))
+    # Control: overlapping groups fit, and positives score higher on average.
+    rng = np.random.default_rng(1)
+    pos_logit, neg_logit = propensity_logit(rng.normal(1, 1, (60, 2)), rng.normal(0, 1, (90, 2)))
+    assert pos_logit.mean() > neg_logit.mean()
+
+
+def test_propensity_caliper_match_reproduces_matchit_pairs(lalonde):
+    pos, neg, _ = lalonde
+    ref = pd.read_csv(DATA / "lalonde_matchit_pairs.csv").dropna()
+    _, neg_logit = propensity_logit(pos[COVARIATES], neg[COVARIATES])
+    result = match_negatives(
+        pos[COVARIATES].to_numpy(), neg.id.tolist(), neg[COVARIATES].to_numpy(),
+        method="propensity", caliper=0.2,
+    )  # fmt: skip
+    assert result.caliper == pytest.approx(MATCHIT_CALIPER, rel=1e-7)
+    assert (result.n_matched, len(result.unmatched_positions)) == (184, 1)
+    ours = {pos.id.iloc[i]: c for i, c in zip(result.matched_positions, result.matched_ids)}
+    theirs = dict(zip(ref.treated, ref.control))
+    assert set(ours) == set(theirs)
+    # lalonde has duplicated rows, so several controls share a logit exactly and
+    # either is "the nearest". Every pair is MatchIt's, or a tie with MatchIt's.
+    logit_of = dict(zip(neg.id, neg_logit))
+    differing = [t for t in theirs if ours[t] != theirs[t]]
+    assert len(differing) <= 10
+    for t in differing:
+        assert logit_of[ours[t]] == pytest.approx(logit_of[theirs[t]], abs=1e-9), t
+    matched_pos = pos.iloc[result.matched_positions][COVARIATES]
+    matched_neg = neg.set_index("id").loc[result.matched_ids][COVARIATES]
+    smd = standardized_mean_differences(
+        matched_pos, matched_neg, denominator="positives", reference=(pos[COVARIATES], neg[COVARIATES])
+    )  # fmt: skip
+    assert smd == pytest.approx(MATCHIT_SMD_MATCHED, abs=5e-6)
+
+
+def test_caliper_leaves_far_positives_unmatched_and_reports_them():
+    pos = np.array([[0.0], [0.1], [9.0]])
+    neg = np.array([[0.05], [0.2], [0.3], [0.4]])
+    loose = match_negatives(pos, list("abcd"), neg)
+    assert (loose.complete, loose.matched_positions) == (True, [0, 1, 2])
+    tight = match_negatives(pos, list("abcd"), neg, caliper=0.5)
+    assert (tight.matched_positions, tight.unmatched_positions) == ([0, 1], [2])
+    assert tight.matched_ids == ["a", "b"]
+    assert max(tight.distances) <= 0.5
+    with pytest.raises(ValueError, match="caliper must be positive"):
+        match_negatives(pos, list("abcd"), neg, caliper=0)
+
+
+def test_classifier_that_is_the_confound_is_not_called_robust():
+    df, prob, anchor = confounded_frame()
+    with pytest.raises(ValueError, match=r"gc: .*\|SMD\| = 0\.\d+ .*exceeds 0\.1") as err:
+        evaluate_confound(df, prob, ["gc"], anchor, name="gc", bootstrap_n=200)
+    assert "caliper" in str(err.value)
+    # Positive control: the same data, matched within a caliper, IS evaluable --
+    # and the verdict is the true one.
+    result = evaluate_confound(df, prob, ["gc"], anchor, name="gc", caliper=0.1, bootstrap_n=200)
+    assert result.balance.max_abs_smd_after < 0.1
+    assert result.verdict == DRIVEN
+    assert 0 < result.n_positives < 300
+    assert result.n_positives == result.n_matched_negatives
+    assert result.n_positives + len(result.unmatched_positions) == 300
+
+
+def test_imbalance_can_be_inspected_instead_of_raised():
+    df, prob, anchor = confounded_frame()
+    results = run_battery(df, prob, {"gc": ["gc"]}, anchor, max_smd=None, bootstrap_n=200)
+    assert results["gc"].balance.max_abs_smd_after > 0.1
+    text = format_battery(results, anchor)
+    assert "[IMBALANCED: max |SMD| = 0." in text
+    # Control: a balanced battery carries no such flag.
+    balanced = run_battery(df, prob, {"gc": ["gc"]}, anchor, caliper=0.1, bootstrap_n=200)
+    text = format_battery(balanced, anchor)
+    assert "IMBALANCED" not in text
+    dropped = len(balanced["gc"].unmatched_positions)
+    assert dropped > 0 and f"[INCOMPLETE MATCH: {dropped} positives left out]" in text
+
+
+def test_incomplete_match_is_scored_as_the_one_to_one_design_it_claims():
+    # 0.3.2 scored ALL positives against the fewer matched negatives.
+    df, prob, anchor = confounded_frame(n_pos=40, n_neg=30, shift=1.0, seed=3)
+    result = evaluate_confound(
+        df, prob, ["gc"], anchor, require_complete_match=False,
+        require_selective_match=False, max_smd=None, bootstrap_n=100,
+    )  # fmt: skip
+    assert (result.n_positives, result.n_matched_negatives) == (30, 30)
+    assert len(result.unmatched_positions) == 10
+
+
+@pytest.mark.parametrize("method", ["nearest", "propensity"])
+def test_no_positives_means_no_caliper_was_applied(method):
+    # `caliper` reports the width APPLIED, in distance units. With nothing to
+    # match there is no propensity model to scale it by, so both methods say None
+    # rather than one echoing the argument and the other not.
+    neg = np.array([[0.0], [1.0], [2.0]])
+    empty = match_negatives(np.empty((0, 1)), list("abc"), neg, method=method, caliper=0.2)
+    assert (empty.matched_ids, empty.unmatched_positions, empty.n_pool) == ([], [], 3)
+    assert empty.caliper is None
+    # Control: with positives present the applied caliper is reported.
+    some = match_negatives(np.array([[0.1], [1.2]]), list("abc"), neg, method=method, caliper=0.2)
+    assert some.caliper is not None and some.caliper > 0

{confound_controls-0.3.2 → confound_controls-0.4.0}/tests/test_battery.py

@@ -138,10 +138,17 @@ def test_incomplete_match_raises_by_default_and_is_reported_when_allowed():
     with pytest.raises(ValueError, match="matched only"):
         evaluate_confound(small, probs, ["other"], anchor)
     res = evaluate_confound(
-        small, probs, ["other"], anchor, require_complete_match=False, require_selective_match=False
+        small,
+        probs,
+        ["other"],
+        anchor,
+        require_complete_match=False,
+        require_selective_match=False,
+        max_smd=None,
     )
     assert not res.match_complete
-    assert res.n_matched_negatives == 5
+    # Only the matched positives are scored: the design reported is the 1:1 one.
+    assert (res.n_positives, res.n_matched_negatives) == (5, 5)
 
 
 def test_format_battery_flags_an_incomplete_match_in_its_text():
@@ -156,6 +163,7 @@ def test_format_battery_flags_an_incomplete_match_in_its_text():
             name="other",
             require_complete_match=False,
             require_selective_match=False,
+            max_smd=None,
         )
     }
     assert "INCOMPLETE MATCH" in format_battery(results, 0.9)
@@ -205,7 +213,13 @@ def test_an_equal_sized_pool_is_refused_as_a_vacuous_control():
 
     # Opting out reproduces the original silent behaviour, and it is WRONG in
     # exactly the way described: a pure-GC signal survives GC matching.
-    res = evaluate_confound(df, probs, ["gc"], anchor, name="gc", require_selective_match=False)
+    # Opting out of the selectivity check alone no longer gets there: a match that
+    # selected nothing balanced nothing, and the balance check says so.
+    with pytest.raises(ValueError, match="did not balance 'gc'"):
+        evaluate_confound(df, probs, ["gc"], anchor, name="gc", require_selective_match=False)
+    res = evaluate_confound(
+        df, probs, ["gc"], anchor, name="gc", require_selective_match=False, max_smd=None
+    )
     assert not res.match_selective
     assert res.verdict == ROBUST, (
         "if this is no longer ROBUST the vacuity demonstration has changed"

confound_controls-0.3.2/confound_controls/matching.py

@@ -1,154 +0,0 @@
-"""Match negatives to positives on confounds, and say so when you cannot.
-
-Extracted from an internal matched-negatives script (also present
-byte-identical in a second internal project -- the code was copied between two
-independent repos, which is what marked it as worth extracting).
-
-The matching itself is unchanged. What changed is that it now reports whether
-it achieved the 1:1 match it advertises. The original looped
-
-    while True:
-        ...
-        if pick is not None: ...; break
-        if k >= len(neg_ids): break     # <- silently gives up on this positive
-        k *= 2
-
-so once the negative pool was exhausted it returned FEWER negatives than
-positives and said nothing. A caller comparing AUROC before and after matching
-could not tell a clean 1:1 design from one that quietly dropped a third of its
-positives -- and the drop is not random, it hits the positives in the densest
-region of confound space, exactly where matching matters most.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-import numpy as np
-from scipy.spatial import cKDTree
-
-
-@dataclass(frozen=True)
-class MatchResult:
-    """Outcome of a matching attempt.
-
-    `complete` is the question a caller actually needs answered: did every
-    positive get its own negative? `unmatched_positions` gives the indices of
-    the positives that did not, so the caller can inspect rather than guess.
-    """
-
-    matched_ids: list
-    unmatched_positions: list
-    n_positives: int
-    n_pool: int = 0
-
-    @property
-    def complete(self) -> bool:
-        return not self.unmatched_positions
-
-    @property
-    def n_matched(self) -> int:
-        return len(self.matched_ids)
-
-    @property
-    def selective(self) -> bool:
-        """Did matching actually CHOOSE, or take the whole pool?
-
-        1:1 matching without replacement from a pool the same size as the
-        positive set consumes every negative, whatever the confound values are.
-        The "matched" comparison is then byte-identical to the unmatched one,
-        so the control is vacuous -- and a vacuous control does not report
-        "inconclusive", it reports the original result, which reads as the
-        confound having been ruled out.
-        """
-        return self.n_matched < self.n_pool
-
-    def require_complete(self) -> MatchResult:
-        if not self.complete:
-            raise ValueError(
-                f"matched only {self.n_matched} of {self.n_positives} positives; "
-                f"the negative pool ran out. Unmatched positive positions: "
-                f"{self.unmatched_positions[:10]}"
-                f"{'...' if len(self.unmatched_positions) > 10 else ''}"
-            )
-        return self
-
-    def require_selective(self) -> MatchResult:
-        if not self.selective:
-            raise ValueError(
-                f"matching consumed the entire negative pool "
-                f"({self.n_matched} matched from {self.n_pool} available), so it "
-                f"selected nothing and the control is vacuous -- the matched "
-                f"comparison equals the unmatched one and will report the "
-                f"confound as ruled out. Supply more negatives than positives, "
-                f"or pass require_selective_match=False if you intend this."
-            )
-        return self
-
-
-def match_negatives(pos_vecs, neg_ids, neg_vecs) -> MatchResult:
-    """Greedy 1:1 nearest-neighbour match without replacement, on standardised columns.
-
-    Columns are standardised over positives and negatives jointly so that a
-    confound measured on a wide scale does not dominate the distance purely
-    through its units.
-
-    Args:
-        pos_vecs: (n_pos, n_confounds) confound values for the positives.
-        neg_ids: identifiers for the negatives, parallel to `neg_vecs`.
-        neg_vecs: (n_neg, n_confounds) confound values for the negatives.
-
-    Returns:
-        MatchResult -- inspect `.complete` before trusting a downstream metric,
-        or call `.require_complete()` to make an incomplete match an error.
-    """
-    pos_vecs = np.asarray(pos_vecs, dtype=float)
-    neg_vecs = np.asarray(neg_vecs, dtype=float)
-    neg_ids = list(neg_ids)
-
-    if pos_vecs.ndim != 2 or neg_vecs.ndim != 2:
-        raise ValueError("pos_vecs and neg_vecs must both be 2-D")
-    if pos_vecs.shape[1] != neg_vecs.shape[1]:
-        raise ValueError(
-            f"confound count differs: positives have {pos_vecs.shape[1]}, "
-            f"negatives have {neg_vecs.shape[1]}"
-        )
-    if len(neg_ids) != neg_vecs.shape[0]:
-        raise ValueError(
-            f"neg_ids has {len(neg_ids)} entries but neg_vecs has {neg_vecs.shape[0]} rows"
-        )
-    if not len(neg_ids):
-        return MatchResult([], list(range(len(pos_vecs))), len(pos_vecs), 0)
-
-    allv = np.vstack([pos_vecs, neg_vecs])
-    mu, sd = allv.mean(0), allv.std(0)
-    # A confound that is constant across every sample carries no information;
-    # dividing by its zero spread would produce nan distances and match at
-    # random, which looks exactly like a successful match.
-    sd = np.where(sd == 0, 1.0, sd)
-    pos_s = (pos_vecs - mu) / sd
-    neg_s = (neg_vecs - mu) / sd
-
-    tree = cKDTree(neg_s)
-    used: set[int] = set()
-    matched: list = []
-    unmatched: list[int] = []
-
-    for position, p in enumerate(pos_s):
-        k = 1
-        pick = None
-        while True:
-            k = min(k, len(neg_ids))
-            _, idxs = tree.query(p, k=k)
-            idxs = np.atleast_1d(idxs)
-            pick = next((int(i) for i in idxs if i not in used), None)
-            if pick is not None or k >= len(neg_ids):
-                break
-            k *= 2
-        if pick is None:
-            unmatched.append(position)
-        else:
-            used.add(pick)
-            matched.append(neg_ids[pick])
-
-    return MatchResult(matched, unmatched, len(pos_s), len(neg_ids))