assign each ANON record to its best-scoring RAW record, independently

For every ANON record this picks the RAW record with the best (by default: smallest) SCORE. Assignments are made independently per ANON record, so the same RAW record may be claimed by several ANON records – that is what "greedy" means here. Enforcing a one-to-one assignment is [match_optimal()].

Usage

match_greedy(
  scores,
  seed = 0L,
  confidence = c("margin", "tie"),
  min_confidence = 0,
  tolerance = reid_tie_tolerance()
)

Arguments

scores: a score table: a data frame with columns RAW_ROW_NUMBER, ANON_ROW_NUMBER and SCORE, normally produced by a `score_*()` function or by [combine_scores()]. Its `score_type` attribute decides whether the best score is the smallest ("distance", the default) or the largest ("similarity").
seed: integer seed for the random tie-break (default 0L, so a plain call is reproducible). NULL uses the ambient RNG stream instead.
confidence: how to fill the CONFIDENCE column: `"margin"` (default since Issue #44: eccentricity, a fine-grained ranking but not a probability and with **no scale that carries between data sets**) or `"tie"` (`1 / tie size`, a calibrated probability with almost no resolution). See [reid_confidence()].
min_confidence: decline to guess for any ANON record whose CONFIDENCE falls below this (default 0, i.e. always guess). A declined record keeps its row but is reported with `RAW_ROW_NUMBER = NA` and `RESULT = FALSE`, so the trial count is unchanged and the reported rate cannot be inflated by simply attacking less.
tolerance: relative tolerance for deciding that two candidate scores are tied, default `sqrt(.Machine$double.eps)` (Issue #61). Scores agreeing to about the first 8 significant digits are treated as indistinguishable, so re-expressing the same data in different units does not turn a tie into a strict ordering. Pass `tolerance = 0` for the exact `==` comparison used before #61; see `docs/default-changes.md`.

Value

a data frame with exactly one row per ANON record, ordered by ANON_ROW_NUMBER, with columns ANON_ROW_NUMBER, RAW_ROW_NUMBER, CONFIDENCE (numeric; in (0, 1] for `confidence = "tie"`, non-negative and possibly unbounded for `"margin"`) and RESULT (logical: whether the guessed RAW record is in fact the one the ANON record came from).

Details

Ties are broken uniformly at random via [resolve_min_distance_ties()], so a record that is genuinely indistinguishable from `k` others is credited with a `1/k` chance rather than being deterministically awarded to whichever candidate happened to sort first (Issue #3). Two scores count as tied when they agree to within `tolerance` **relatively**, not only when they are bit-identical; see `tolerance` below and `docs/default-changes.md`.

By default `CONFIDENCE` is the **eccentricity** (`confidence = "margin"`): how far ahead of the runner-up the winner is, in units of the spread of that record's own candidate scores. `confidence = "tie"` gives the older measure, `1 / (number of RAW records tied at the best score)` – a calibrated probability, but 1 for every record whose best candidate is unique, which on a continuous score is nearly always. See [reid_confidence()] for both, and **Changed defaults** below.

Changed defaults

`confidence` defaulted to `"tie"` up to and including the release that introduced it (Issue #16), and defaults to `"margin"` from Issue #44 onwards. The same call therefore reports **different CONFIDENCE values than it used to**: `"tie"` values live in `(0, 1]` and are mostly exactly 1, while `"margin"` values are non-negative, unbounded and almost all distinct. Nothing else about the assignment changes – the guessed `RAW_ROW_NUMBER` and `RESULT` are untouched – but any code comparing `CONFIDENCE` against a literal, or `min_confidence` tuned against the old scale, has to be revisited. Pass `confidence = "tie"` to get the old numbers back. See `docs/default-changes.md`.

Examples

raw <- data.frame(ROW_NUMBER = 1:5, V = c(10, 20, 30, 40, 50))
d <- join_raw_anon_data(raw, raw)
match_greedy(score_num(d, "V"))
#>   ANON_ROW_NUMBER RAW_ROW_NUMBER CONFIDENCE RESULT
#> 1               1              1  0.6324555   TRUE
#> 2               2              2  0.8770580   TRUE
#> 3               3              3  1.1952286   TRUE
#> 4               4              4  0.8770580   TRUE
#> 5               5              5  0.6324555   TRUE