Attempts to match each name in original_name to a name in resources (produced by
prepare_taxonomic_resources()), trying, in order, exact matches (scientific name with
authorship, then canonical name), then progressively more lenient fuzzy matches, at species level
first and then at each higher taxonomic rank present in resources. See match_taxa() for the
full sequence of match attempts.
Usage
align_taxa(
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,
full = FALSE,
quiet = FALSE
)Arguments
- original_name
Character vector of raw taxon names to align.
- resources
The taxonomic reference to align against: the nested list produced by
prepare_taxonomic_resources(), or a reference table (or a list of them, such asload_taxonomic_resources()'s output), which is run throughprepare_taxonomic_resources()automatically. Preparing it yourself first saves repeating that work when aligning several name lists against the same reference.- identifier
A dataset, location or other identifier associated with each name in
original_name– used only to disambiguategenus sp.-style aligned names (seeprepare_taxonomic_resources()/match_taxa()) as belonging to a specific dataset/location. Recycled if length 1; otherwise must be the same length asoriginal_name. Defaults toNA.- fuzzy_abs_dist
The number of characters allowed to differ for a fuzzy match.
- fuzzy_rel_dist
The proportion of characters allowed to differ for a fuzzy match.
- fuzzy_matches
Logical; whether fuzzy matching is attempted at all. Defaults to
TRUE.- imprecise_fuzzy_matches
Logical; reserved for a more lenient fuzzy-matching pass (not yet implemented – see
match_taxa()). Defaults toFALSE.- taxon_ranks_to_check
Optional character vector of taxonomic ranks (besides species) to attempt higher-rank matches against. Defaults to
NULL, which uses every higher rank present inresources.- hybrids
Logical; if
TRUE(the default, as APCalign always does), a hybrid name (Genus x species) that isn't itself a listed name is resolved to genus rank ("Genus x [original name]") rather than left for later match attempts – withFALSE,"Banksia serrata x ericifolia"aligns to Banksia serrata. See?match_taxa.- intergrades_affinis
Logical; if
TRUE(the default, as APCalign always does), names suggesting an intergrade (--), an indecision between taxa (/), or a graded/"affinis"/"cf." identification are resolved to genus rank the same way, unless the whole name is a listed name. See?match_taxa.- consider_english_name_endings
Logical; if
TRUE, before any fuzzy matching, try substituting a recognised informal English vernacular name ending (e.g."-id","-ine","-oid") for its formal Latin equivalent and attempt an exact match on the corrected name. Defaults toFALSE. See?match_taxa.- include_bracketed_info
Logical;
TRUE(the default) gives every higher-rank-only match APCalign's"<rank name> sp. [<original name>; <identifier>]"form, e.g."Banksia sp. [Banksia]"for a bare"Banksia".FALSEdrops the brackets when the name is nothing more than the matched rank's own name (a bare single word, or a bare"Genus (Subgenus)"), giving just"Banksia";original_namekeeps the raw input either way, and a name with anything more keeps the brackets regardless. See?match_taxa.- progress
Logical; if
TRUE, prints a text progress bar tracking what fraction oforiginal_namehas been resolved so far. Useful for large inputs, where matching can take a while. Defaults toFALSE. See?match_taxa.- full
Logical; if
TRUE, return every intermediate columnmatch_taxa()computes (useful for inspecting why a name matched the way it did). IfFALSE(the default), return just the key output columns.- quiet
Accepted for compatibility with APCalign's function of the same name; this function prints nothing either way.
Value
A tibble with one row per element of original_name (preserving its length, order and any
duplicates/NAs), with columns original_name, cleaned_name, aligned_name,
taxonomic_dataset, taxon_rank, taxonomic_status, taxon_ID, accepted_name_usage_ID,
aligned_reason, alignment_code, chars_changed and identifier (or, if full = TRUE, every
column match_taxa() computes along the way). taxon_ID/accepted_name_usage_ID identify which
row of resources a name matched to, and are what update_taxa() uses to resolve a matched
synonym forward to its current accepted name. chars_changed is the number of characters that
differed between the name being matched and the reference name it matched – 0 for every exact
match, the actual edit distance (Damerau-Levenshtein) for a fuzzy match, and NA when nothing
matched at all.
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")
)
# a misspelling and a synonym
aligned <- align_taxa(c("Boronia serulata", "Boronia oldname"), reference)
aligned[, c("original_name", "aligned_name", "taxonomic_status", "aligned_reason")]
#> # A tibble: 2 × 4
#> original_name aligned_name taxonomic_status aligned_reason
#> <chr> <chr> <chr> <chr>
#> 1 Boronia serulata Boronia serrulata accepted Fuzzy match of taxon name…
#> 2 Boronia oldname Boronia oldname synonym Exact match of taxon name…