Manually override a single name in a reconciliation

Apply a single hand-curated decision to a reconciliation object. Use this to accept a match the matching cascade rejected (typically a flagged fuzzy hit), remove a spurious match, or force a new mapping that the cascade missed. ("Cascade" here means the four-stage matching pipeline run by reconcile_tree() and reconcile_data() — exact, normalised, synonym, fuzzy — as described in ?prepR4pcm.) The override is recorded in the provenance log so that you and your reviewers can audit every manual decision.

Usage

reconcile_override(
  reconciliation,
  name_x,
  name_y = NULL,
  action = c("accept", "reject", "replace"),
  note = ""
)

Arguments

reconciliation

A reconciliation object.

name_x

A length-1 character vector. The name as it appears in source x (your data). Must match a value already present in mapping$name_x.

name_y

A length-1 character vector or NULL. The name in source y (the tree or reference dataset) that name_x should be mapped to. NULL is only valid when action = "reject".

action

A length-1 character vector. What the override does:

"accept" (default)

Confirm a proposed match. Use after reviewing a flagged fuzzy or synonym hit.

"reject"

Remove an existing match and return both names to the unresolved pool. Use when the cascade over-matched (e.g. an aggressive fuzzy score linked the wrong species).

"replace"

Set a new match, overwriting whatever the cascade produced for name_x.

note

A length-1 character vector. A short justification for the override, stored in the provenance log and in mapping$notes. Strongly recommended — future you will want to know why this decision was made.

Value

An updated reconciliation object. The existing row for name_x is replaced with one whose match_type is "manual" and match_source is "user_override".

Details

For applying many overrides at once (e.g. from a curated CSV), see reconcile_override_batch(); for interactive decisions in the console, see reconcile_review(); for published taxonomy crosswalks, see reconcile_crosswalk().

See also

reconcile_override_batch() for bulk overrides; reconcile_suggest() for near-miss candidates; reconcile_crosswalk() for published taxonomy crosswalks.

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

Examples

data(avonet_subset)
data(tree_jetz)
rec <- reconcile_tree(avonet_subset, tree_jetz,
                      x_species = "Species1", authority = NULL)
#> ℹ Reconciling 919 data names vs 657 tree tips
#> ℹ Matching 919 x 657 names through 2 stages...
#> ℹ Stage 1/2: Exact matching...
#> ℹ Stage 2/2: Normalised matching (0 matched so far)...
#> ✔ Matched 657/919 data names to tree tips

# Pick an unresolved species and hand-assign it for illustration
unresolved <- reconcile_mapping(rec)
unresolved <- unresolved[unresolved$match_type == "unresolved" &
                           unresolved$in_x, ]
if (nrow(unresolved) > 0) {
  rec <- reconcile_override(
    rec,
    name_x = unresolved$name_x[1],
    name_y = tree_jetz$tip.label[1],
    note   = "Demo: manual assignment"
  )
}
#> ✔ Override applied: 'Acanthiza cinerea' -> 'Amytornis_barbatus' (accept)