Extract the per-name mapping table from a reconciliation

Returns the mapping tibble inside a reconciliation object. Use this when you want to filter matches programmatically (e.g. pull all unresolved species, all fuzzy matches above a given score, or join the mapping back to the original data frame).

Usage

reconcile_mapping(reconciliation, include_unused_overrides = FALSE)

Arguments

reconciliation

A reconciliation object returned by reconcile_tree(), reconcile_data(), reconcile_trees(), reconcile_to_trees(), or reconcile_multi().

include_unused_overrides

Logical. Appends the rejected override rows to the returned tibble when TRUE, with match_type = "override_unused", match_score = NA, and the notes column carrying the rejection reason (name_x_not_in_data, name_y_not_in_target, or already_matched). Default FALSE for backward compatibility — the bare mapping tibble has the same shape as before.

Value

A tibble with one row per unique name seen in either source and the following columns:

name_x

Statement: this column holds the original name as it appeared in source x (your data). NA for rows that exist only in source y (e.g. tree tips not in your data).

name_y

Statement: this column holds the original name as it appeared in source y (the reference dataset or tree). NA for rows that exist only in source x.

name_resolved

The accepted/canonical name returned by the taxonomic authority, when synonym resolution was used. NA when authority = NULL or no synonym was found.

match_type

One of "exact", "normalized", "synonym", "fuzzy", "manual" (set via reconcile_override()), "flagged" (low-confidence, needs review), "unresolved", or — when include_unused_overrides = TRUE — "override_unused" (override row not applied because of missing names or prior matches).

match_score

Numeric in [0, 1]. 1 for exact/normalized/synonym/manual matches; a genus-weighted Levenshtein score for fuzzy matches; NA for unresolved and for unused-override rows.

match_source

Where the match came from: "exact", "normalisation", the taxadb authority code (e.g. "col"), "fuzzy", or "user_override".

in_x

Logical. This column records whether the name was present in source x.

in_y

Logical. This column records whether the name was present in source y.

notes

Free-text notes, populated e.g. when a name is flagged for review or when an override carries a user comment. For match_type = "override_unused" rows this column carries the rejection reason.

See also

reconcile_summary() for a printed breakdown; reconcile_suggest() for near-miss candidates for unresolved names; reconcile_apply() to turn the mapping into an aligned data-tree pair. The unused-override rows surfaced by include_unused_overrides = TRUE mirror the unused_overrides slot on the reconciliation object.

Other reconciliation functions: reconcile_apply(), reconcile_augment(), reconcile_crosswalk(), reconcile_data(), reconcile_diff(), reconcile_export(), 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

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
mapping <- reconcile_mapping(rec)

# How many species matched?
sum(mapping$in_x & mapping$in_y)
#> [1] 657

# Which species are in the data but missing from the tree?
head(mapping[mapping$in_x & !mapping$in_y, c("name_x", "match_type")])
#> # A tibble: 6 × 2
#>   name_x                   match_type
#>   <chr>                    <chr>     
#> 1 Acanthiza cinerea        unresolved
#> 2 Calamanthus cautus       unresolved
#> 3 Calamanthus montanellus  unresolved
#> 4 Calamanthus pyrrhopygius unresolved
#> 5 Gerygone citrina         unresolved
#> 6 Pyrrholaemus sagittatus  unresolved

# Append rejected overrides for audit
mapping_full <- reconcile_mapping(rec, include_unused_overrides = TRUE)