Align and update a list of taxon names in one call
Source:R/create_taxonomic_update_lookup.R
create_taxonomic_update_lookup.RdThe one-call convenience pipeline: align_taxa() followed by update_taxa(). Matches each name in
original_name against resources, then resolves that match forward to its current accepted name.
Usage
create_taxonomic_update_lookup(
original_name,
resources = NULL,
identifier = NA_character_,
fuzzy_abs_dist = 3,
fuzzy_rel_dist = 0.2,
fuzzy_matches = TRUE,
imprecise_fuzzy_matches = FALSE,
taxon_ranks_to_check = NULL,
hybrids = TRUE,
intergrades_affinis = TRUE,
consider_english_name_endings = FALSE,
include_bracketed_info = TRUE,
progress = FALSE,
taxonomic_splits = c("most_likely_species", "collapse_to_higher_taxon"),
full = FALSE,
quiet = FALSE
)Arguments
- original_name
Character vector of raw taxon names to align and update.
- resources
The nested list of reference tibbles produced by
prepare_taxonomic_resources(), or a reference table (or list of them) – seealign_taxa().- identifier, fuzzy_abs_dist, fuzzy_rel_dist, fuzzy_matches, imprecise_fuzzy_matches, taxon_ranks_to_check, hybrids, intergrades_affinis, consider_english_name_endings, include_bracketed_info, progress
Forwarded to
align_taxa(); see its documentation.- taxonomic_splits
Passed to
update_taxa(): how to report a name that leads to more than one accepted name ("most_likely_species", the default, or"collapse_to_higher_taxon").- full
Logical; if
TRUE, return every intermediate columnalign_taxa()/update_taxa()compute. IfFALSE(the default), return just the key output columns:original_name,aligned_name,accepted_name,suggested_name,genus,family,taxon_rank,taxonomic_dataset,taxonomic_status,taxonomic_status_aligned,aligned_reason,update_reasonandchars_changed(the number of characters that differed between the name being matched and the reference name it matched –0for an exact match, the edit distance for a fuzzy match,NAwhen nothing matched).- quiet
Logical; if
FALSE(the default), ends by printing a summary, as APCalign's does: how many distinct names aligned to a species or infraspecific taxon (by dataset), only to a genus or a family, or to another rank; how many couldn't be aligned; how many were updated to a different name; and how many could refer to more than one accepted taxon.TRUEprints nothing.
Value
A tibble with one row per element of original_name; see update_taxa() for column
details.
Examples
reference <- data.frame(
canonical_name = c("Boronia", "Boronia serrulata", "Boronia oldname"),
scientific_name = c("Boronia Sm.", "Boronia serrulata Sm.", "Boronia oldname Sm."),
taxon_rank = c("genus", "species", "species"),
taxonomic_status = c("accepted", "accepted", "synonym"),
taxonomic_dataset = "MY_LIST", genus = "Boronia",
taxon_ID = c("1", "2", "3"), accepted_name_usage_ID = c("1", "2", "2")
)
create_taxonomic_update_lookup(
c("Boronia serulata", "Boronia oldname", "Boronia sp."),
reference
)
#> Summary of 3 names:
#> -> 2 aligned to a species or infraspecific taxon (2 in MY_LIST)
#> -> 1 aligned only to a genus and 0 only to a family
#> -> 0 could not be aligned
#> -> 1 aligned names were updated to a different name (e.g. a synonym to its accepted name, or an outdated genus to the current one)
#> # A tibble: 3 × 20
#> original_name aligned_name accepted_name suggested_name genus taxon_rank
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 Boronia serulata Boronia serrul… Boronia serr… Boronia serru… Boro… species
#> 2 Boronia oldname Boronia oldname Boronia serr… Boronia serru… Boro… species
#> 3 Boronia sp. Boronia sp. Boronia Boronia sp. Boro… genus
#> # ℹ 14 more variables: taxonomic_dataset <chr>, taxonomic_status <chr>,
#> # scientific_name <chr>, aligned_reason <chr>, update_reason <chr>,
#> # number_of_collapsed_taxa <int>, taxon_ID <chr>, taxon_ID_genus <chr>,
#> # scientific_name_ID <chr>, family <chr>, taxonomic_status_aligned <chr>,
#> # alternative_possible_names <chr>, chars_changed <int>, identifier <chr>