Takes the output of align_taxa() and, for every row that matched something in resources
(whether an accepted name or a synonym), looks up the current record for that match via
accepted_name_usage_ID and reports its accepted name (when it resolves to one).
Usage
update_taxa(
aligned_data,
resources = NULL,
taxonomic_splits = c("most_likely_species", "collapse_to_higher_taxon"),
quiet = FALSE
)Arguments
- aligned_data
A tibble in the shape
align_taxa()returns – in particular, it must havealigned_name,taxonomic_status,taxon_rank,taxonomic_dataset,taxon_IDandaccepted_name_usage_IDcolumns (bothalign_taxa()'s default,full = FALSE, output and itsfull = TRUEoutput include these).- resources
The nested list of reference tibbles produced by
prepare_taxonomic_resources()(the same one passed toalign_taxa()), or a reference table (or list of them) – seealign_taxa().- taxonomic_splits
How to report a name that leads to more than one accepted name:
"most_likely_species"(the default) suggests one and lists the others in brackets;"collapse_to_higher_taxon"collapses it to genus when all candidates share one. See Details.- quiet
Accepted for compatibility with APCalign's function of the same name; this function prints nothing either way.
Value
aligned_data with taxon_rank/genus/family/taxonomic_dataset refreshed to whatever
the current record has (a synonym's may be outdated), the pre-update taxonomic_status renamed to
taxonomic_status_aligned, and new columns accepted_name (the current accepted name, when the
match resolves to one, otherwise NA), suggested_name (accepted_name if available, otherwise
falls back to aligned_name), taxonomic_status (the current record's status) and
update_reason (a short explanation, mirroring aligned_reason's style), and
alternative_possible_names (the other candidates for a name that leads to more than one accepted
name, otherwise NA).
It also has every column APCalign's update_taxonomy() returns, meaning the same thing, all
describing the taxon suggested_name names (its accepted record, or for a split collapsed to genus,
that genus's):
taxon_ID: that accepted record's ID (NAwhen the name doesn't resolve to an accepted name). The ID of the record the name matched (a synonym's own ID, say), whichalign_taxa()returns astaxon_ID, is kept asaligned_taxon_ID.taxon_ID_genus: the ID of its genus's accepted record.scientific_nameandscientific_name_ID: its name with authorship, and the reference'sscientific_name_IDfor it (e.g. an IPNI LSID for the WCVP;NAif the reference has none). For a name that matched but doesn't resolve to an accepted name (an unplaced name, say), those of the matched record.subclass,taxon_distribution: the reference's own columns of those names,NAif it has none.canonical_name: the same assuggested_name, as in APCalign.row_number: the row's position inaligned_data.number_of_collapsed_taxa: for a name leading to more than one accepted name, 1 when one is suggested, or the number of candidates when they're collapsed to genus;NAotherwise.
Details
Unlike APCalign's update_taxonomy() – five separate
functions, each hand-written for one specific rank/dataset combination (update_taxonomy_APC_genus,
update_taxonomy_APC_family, ...) – this is a single, rank-agnostic lookup: every rank present
in resources is resolved the same way, by matching each row's accepted_name_usage_ID against a
taxon_ID in a table combining every rank/status sublist in resources. A row that's already
accepted resolves to itself (its own accepted_name_usage_ID is self-referential, per
prepare_taxonomic_resources()'s requirements); a synonym resolves to whatever its
accepted_name_usage_ID points to.
A synonym that leads to more than one accepted taxon (a species or infraspecific name listed as
a synonym of two or more different accepted taxa – a split, or a pro parte synonym) follows
APCalign's taxonomic_splits convention. One accepted name is chosen – by taxonomic status
precedence, then (for a tie) an accepted name sharing the name's epithet, then one of the same rank,
then one published no later than the name itself, then the oldest, then the order resources lists
them in – and the others are listed with their status, both in suggested_name
("X [alternative possible names: Y (synonym) | Z (misapplied)]") and in a separate
alternative_possible_names column. With taxonomic_splits = "collapse_to_higher_taxon", a name
whose candidates all share one genus is collapsed to that genus instead
("Genus sp. [collapsed names: ...]", taxon_rank = "genus", accepted_name = NA). Only a match
to a synonym record is treated this way: a match to an accepted name, or to a name given with its
authorship (which identifies one record, e.g. one of two homonyms), is not.
One thing this deliberately does not do, relative to APCalign's update_taxonomy():
No genus-substring surgery. APCalign's
update_taxonomy_APC_genus()reconstructs a species' suggested name by splicing just the updated genus portion into the aligned name, when only the genus (not the species) has changed. That's a nice refinement but doesn't obviously generalize across arbitrary ranks the way the rest of this does, so it's omitted here.
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")
)
aligned <- align_taxa(c("Boronia serulata", "Boronia oldname"), reference)
# "Boronia oldname" is a synonym, updated to its accepted name
updated <- update_taxa(aligned, reference)
updated[, c("original_name", "aligned_name", "accepted_name", "update_reason")]
#> # A tibble: 2 × 4
#> original_name aligned_name accepted_name update_reason
#> <chr> <chr> <chr> <chr>
#> 1 Boronia serulata Boronia serrulata Boronia serrulata Aligned name is already …
#> 2 Boronia oldname Boronia oldname Boronia serrulata Updated to the current a…