Apply a taxonomy crosswalk as a post-baseline supplement

Use this after an initial reconcile_data() or reconcile_tree() run when you want a taxonomy crosswalk to add matches without overwriting exact, normalised, synonym, or fuzzy matches that the baseline cascade already made.

Usage

reconcile_crosswalk_supplement(
  reconciliation,
  crosswalk,
  from_col,
  to_col,
  match_type_col = NULL,
  notes_col = NULL,
  one_to_one_only = TRUE,
  quiet = FALSE
)

Arguments

reconciliation

A reconciliation object returned by reconcile_data(), reconcile_tree(), or a related matcher.

crosswalk

A data frame, or a file path. File format is inferred from the extension: .csv (comma-separated), .tsv (tab-separated), or .txt (tab-separated). For other delimited formats, read the file yourself with read.delim() or read.table() and pass the resulting data frame.

from_col

A length-1 character vector. Column name for source names (e.g., "Species1" for BirdLife names).

to_col

A length-1 character vector. Column name for target names (e.g., "Species3" for BirdTree names).

match_type_col

A length-1 character vector or NULL. Name of an optional column in crosswalk that classifies each row's relationship between the two taxonomies — e.g. "1BL to 1BT" (one BirdLife species mapped to one BirdTree species; a clean one-to-one match), "Many BL to 1BT" (a lump: several BirdLife species mapped to a single BirdTree species), "1BL to many BT" (a split). When supplied, the contents of this column are appended to each override's user_note so the audit trail records the relationship; if you also pass one_to_one_only = TRUE, only the rows whose match type starts "1...to 1..." are kept. Pass NULL (default) when your crosswalk has no such classification column — every row is then kept and notes carry no provenance label.

notes_col

A length-1 character vector or NULL. Column containing additional notes.

one_to_one_only

Logical. If TRUE (default), keeps only one-to-one crosswalk rows before supplementing the baseline result.

quiet

Logical. Suppresses informational messages when TRUE.

Value

An updated reconciliation object. If no unambiguous crosswalk rows can supplement the baseline result, the returned object is the input reconciliation with a meta$crosswalk_supplement audit entry.

Details

Passing the output of reconcile_crosswalk() directly to the overrides argument of a reconcile_*() call treats every row as a locked manual decision. Those overrides are applied before the matching cascade, so they can preempt exact or normalised matches. That is correct for reviewed manual corrections, but risky when using a whole published crosswalk automatically.

reconcile_crosswalk_supplement() implements the safer pattern:

1. run the baseline reconciliation first;

2. convert the crosswalk to candidate overrides;

3. keep only rows whose source name is still unresolved in x and whose target name is still unresolved in y;

4. drop duplicate source or target candidates rather than choosing by row order;

5. apply the remaining rows with reconcile_override_batch().

By default, one_to_one_only = TRUE, so split/lump rows such as "1BL to many BT" and "Many BL to 1BT" are not applied automatically. If you set one_to_one_only = FALSE, duplicate source or target candidates are still skipped and should be reviewed manually.

See also

reconcile_crosswalk() for converting a crosswalk to an override table; reconcile_override_batch() for applying reviewed batches.

Other reconciliation functions: reconcile_apply(), reconcile_augment(), reconcile_crosswalk(), reconcile_data(), reconcile_diff(), reconcile_export(), reconcile_mapping(), reconcile_merge(), reconcile_multi(), reconcile_override(), reconcile_override_batch(), reconcile_plot(), reconcile_report(), reconcile_review(), reconcile_splits_lumps(), reconcile_suggest(), reconcile_summary(), reconcile_to_trees(), reconcile_tree(), reconcile_trees()

Examples

x <- data.frame(species = c("Species old", "Species exact"))
y <- data.frame(species = c("Species new", "Species exact"))
crosswalk <- data.frame(
  from = "Species old",
  to = "Species new",
  type = "1BL to 1BT"
)

baseline <- reconcile_data(
  x, y,
  x_species = "species",
  y_species = "species",
  authority = NULL,
  quiet = TRUE
)

supplemented <- reconcile_crosswalk_supplement(
  baseline,
  crosswalk,
  from_col = "from",
  to_col = "to",
  match_type_col = "type",
  quiet = TRUE
)
reconcile_mapping(supplemented)
#> # A tibble: 2 × 9
#>   name_x    name_y name_resolved match_type match_score match_source in_x  in_y 
#>   <chr>     <chr>  <chr>         <chr>            <dbl> <chr>        <lgl> <lgl>
#> 1 Species … Speci… NA            exact                1 exact_string TRUE  TRUE 
#> 2 Species … Speci… NA            manual               1 user_overri… TRUE  TRUE 
#> # ℹ 1 more variable: notes <chr>