Prepare a combined taxonomic reference table for name matching
Source:R/prepare_taxonomic_resources.R
prepare_taxonomic_resources.RdTakes one or more taxonomic reference tables – loaded with load_taxonomic_resources(), built
yourself, or any mix of these – and turns them into the single nested resources list that
align_taxa()/match_taxa() expect: tables are combined if more than one was supplied, and the
result is split by rank (and, for species-level rows, by taxonomic status). align_taxa(),
update_taxa() and create_taxonomic_update_lookup() call this themselves when given a table (or
a list of tables) rather than prepared resources; call it yourself to prepare once and reuse.
Arguments
- taxonomic_resources
A tibble, a path to a CSV file (read with readr, which must be installed), or a (optionally named) list of either – one element per taxonomic reference table to combine. Each table must be in taxonAlign's taxonomic reference format (see
taxonomic_reference_schema()): at least the columnscanonical_name,scientific_name,taxon_rank,taxonomic_status,taxonomic_dataset,genus,taxon_IDandaccepted_name_usage_ID, matching APCalign's own naming convention (see Details). A row whosecanonical_nameisNAhas no usable name and is dropped, with a warning.accepted_name_usage_IDmust be self-referential (equal totaxon_ID) for already-accepted rows, notNA– this is what letsupdate_taxa()resolve a matched name forward to its current accepted name regardless of whether it matched an accepted name or a synonym. To map a table with other column names onto this format interactively, seetaxonAlign.dataprep::build_taxonomic_reference().- taxon_ranks_to_check
Optional character vector restricting which taxonomic ranks (besides species/infraspecific ranks) are retained in the returned
resourcesfor higher-rank matching (e.g.c("genus", "family")). Defaults toNULL, which keeps every rank present intaxonomic_resources.
Value
A named list of tibbles (and, for species, a further named list split by
taxonomic_status): one element per taxonomic rank present in taxonomic_resources (after applying
taxon_ranks_to_check, if supplied), plus subgenus_v2 when subgenus-rank rows are present (see
Details).
Details
Unlike APCalign's load_taxonomic_resources(), which
only ever assembles the fixed APC/APNI combination, this function works on whatever combined
reference data the user supplies – at whatever set of taxonomic ranks it happens to contain, not
just genus/species/family.
Column names are normalised on the way in, exactly the way
APCalign::load_taxonomic_resources() normalises APC/APNI's raw Darwin Core column names to its
own convention – e.g. a raw canonicalName/taxonRank/taxonomicStatus/scientificName column
is renamed to canonical_name/taxon_rank/taxonomic_status/scientific_name. This keeps
canonical_name the only name field taxonAlign ever refers to.
When multiple tables are supplied, whichever is supplied first is preferred when a name exists in more than one, whatever taxonomic status each gives it. Within one table, a name listed more than once is matched to its most reliable status first (accepted, then the various kinds of synonym, then misapplications, ...).
Two matching conventions for subgenus names are supported side by side: some input name lists
write the subgenus alone (e.g. "Podosemum"), others write the Genus (Subgenus) bracketed
convention (e.g. "Boronia (Podosemum)"). To support both, when taxonomic_resources contains
subgenus-rank rows, resources$subgenus holds the plain subgenus names (used for the first
convention) and resources$subgenus_v2 additionally holds a genus_and_subgenus column (used for
the second).
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")
)
# prepare once, then reuse for several lookups
resources <- prepare_taxonomic_resources(reference)
names(resources)
#> [1] "species" "genus"
align_taxa("Boronia serulata", resources)
#> # A tibble: 1 × 12
#> original_name identifier cleaned_name aligned_name taxonomic_dataset
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Boronia serulata NA Boronia serulata Boronia serrul… MY_LIST
#> # ℹ 7 more variables: taxon_rank <chr>, taxonomic_status <chr>, taxon_ID <chr>,
#> # accepted_name_usage_ID <chr>, aligned_reason <chr>, alignment_code <chr>,
#> # chars_changed <int>