Skip to contents

Convert a published taxonomy crosswalk into an overrides table

Source: R/reconcile_crosswalk.R
reconcile_crosswalk.Rd

Turn a curated species-name crosswalk (e.g. the BirdLife–BirdTree crosswalk bundled as crosswalk_birdlife_birdtree, or Clements updates released each year) into a data frame that can be passed straight to the overrides argument of reconcile_tree(), reconcile_data() and friends.

Usage

reconcile_crosswalk(
  crosswalk,
  from_col,
  to_col,
  match_type_col = NULL,
  notes_col = NULL,
  one_to_one_only = FALSE
)

Arguments

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, keeps only one-to-one matches (e.g., "1BL to 1BT"). Default FALSE for backwards compatibility; TRUE is recommended for automatic workflows.

Value

A data frame with columns name_x, name_y, and user_note, ready to be passed as the overrides argument.

Details

The returned table is an override table, not an extra matching stage. Overrides are applied before the exact -> normalised -> synonym -> fuzzy cascade, so a crosswalk row can preempt a name pair that would otherwise match exactly or after normalisation. For unattended workflows, restrict automatic crosswalk use to clean one-to-one rows with one_to_one_only = TRUE. Treat split/lump rows such as "1BL to many BT" and "Many BL to 1BT" as review candidates, because they represent competing species concepts rather than formatting fixes. If you keep competing rows as overrides, they are tried sequentially and the first applicable row wins.

Using a crosswalk is preferable to automated synonym resolution when an authoritative mapping exists — it is reproducible, does not depend on taxadb being available, and you can point to the published source in the methods section of your paper.

See also

reconcile_override_batch() for applying this table directly to an existing reconciliation; crosswalk_birdlife_birdtree for the bundled example.

Other reconciliation functions: reconcile_apply(), reconcile_augment(), reconcile_crosswalk_supplement(), 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

data(crosswalk_birdlife_birdtree)
overrides <- reconcile_crosswalk(
  crosswalk_birdlife_birdtree,
  from_col = "Species1",
  to_col = "Species3",
  match_type_col = "Match.type",
  one_to_one_only = TRUE
)
#> ! Removed 2158 non-one-to-one entries from crosswalk
#> ✔ Crosswalk: 1643 overrides (7317 identical pairs skipped)
head(overrides)
#>                      name_x                 name_y              user_note
#> 1        Acanthidops bairdi    Acanthidops bairdii crosswalk [1BL to 1BT]
#> 2         Acanthiza cinerea       Gerygone cinerea crosswalk [1BL to 1BT]
#> 3   Acanthoptila nipalensis   Turdoides nipalensis crosswalk [1BL to 1BT]
#> 4 Acridotheres melanopterus   Sturnus melanopterus crosswalk [1BL to 1BT]
#> 5         Acritillas indica            Iole indica crosswalk [1BL to 1BT]
#> 6    Acrocephalus rimitarae Acrocephalus rimatarae crosswalk [1BL to 1BT]