After matching taxonomic names to a reference, some may match synonyms. This function resolves synonyms to their accepted names.
ts_resolve_names(
query,
ref,
max_dist = 3,
max_dist_genus = 2,
transpositions = FALSE,
match_canon = FALSE,
match_autonyms = FALSE,
match_autonyms_exclude = NULL,
tbl_out = getOption("ts_tbl_out", default = FALSE),
strip_qualifiers = FALSE,
exclude_placeholders = TRUE,
closest_only = FALSE,
collapse_infra = NULL,
collapse_infra_exclude = NULL,
ref_taxonomy = NULL,
match_no_auth = NULL
)Character vector or dataframe; taxonomic names to be resolved.
If a character vector, missing values not allowed and all values must be
unique. If a dataframe, should be taxonomic names matched with
ts_match_names().
Dataframe; reference taxonomic data adhering to the Darwin Core standard with the following columns:
taxonID: Unique identifier for each taxon.
acceptedNameUsageID: If the taxon is a synonym, the unique identifier for the accepted name
taxonomicStatus: The status of the use of the scientificName as a label for the taxon.
scientificName: The full scientific name of the taxon,
with authorship and date information if known.
Can also be the output of ts_optimize_ref() applied to
such a dataframe, which saves the work of preparing the reference when
resolving several times against the same large reference.
Max Levenshtein distance to allow during fuzzy matching (total insertions, deletions and substitutions). The distance is computed on the whole name, including the author string, after removing punctuation and converting to lower case. Default: 3.
Max Levenshtein distance between the genus of a query
and a genus in the reference, for correcting misspelled genera. Only used
for queries whose genus is not in the reference; the candidates are then the
names in reference genera within this distance, and the whole name (or the
canonical name, for a query without an author) must still be within
max_dist. Matches have the type auto_fuzzy_genus. Set to 0 to turn
genus-level fuzzy matching off. See ts_match_names().
Default: 2.
Logical; count a swap of two adjacent letters (e.g.
Qurecus for Quercus, a common typing error) as one edit instead of two
when computing fuzzy-match distances (optimal string alignment distance
rather than plain Levenshtein distance). Set to FALSE for plain
Levenshtein distance, which is somewhat faster. See
ts_match_names(). Default: FALSE.
Logical; Allow a "canonical name" match if only the genus,
species epithet, and infraspecific epithet (if present) match exactly.
Default: to not allow such a match (FALSE).
Logical; match autonyms (names whose specific epithet
and infraspecific epithet are the same) with the species name. For more
information, see ts_match_names(). Default: FALSE.
Character vector; taxonomic names to exclude
from match_autonyms. Any names used must match those in query exactly, or
they won't be excluded.
Logical vector of length 1; should a tibble be returned?
If FALSE (default), output will be a data.frame. This argument can
be controlled via the option ts_tbl_out; see Examples.
Logical; if TRUE, remove standalone
open-nomenclature qualifiers (cf., aff., s.l./sensu lato,
s.str./sensu stricto) from names before parsing. See
ts_parse_names() and its References section. Only has an
effect when query is a character vector. Default: FALSE.
Logical; exclude placeholder names such as
"Genus sp." or "Genus indet." (identification stopped above species
rank) with a warning, instead of matching them as if they were species. See
ts_parse_names(). Only has an effect when query is a
character vector. Default: TRUE.
Logical; for each query with fuzzy matches, keep only
the fuzzy hits at the smallest distance (ties are all kept, so real ambiguity
still shows) and drop the more distant ones, which can be unrelated names
when epithets are short. Default: FALSE.
Aliases of match_autonyms and
match_autonyms_exclude, kept so that existing code keeps working.
Alias of ref, the name used before taxastand 3.0.0; it
will be deprecated in a future version.
Alias of match_canon, kept so that existing code keeps
working. It was an option of earlier versions that match_canon now covers;
note that match_canon also allows canonical-name matches for queries that
have an author.
Dataframe; results of resolving synonyms in matched taxonomic names. Includes the following columns:
query: Query name
resolved_name: Accepted name after resolving synonyms
matched_name: Name matched to query
resolved_status: Taxonomic status of the resolved name (same as
taxonomicStatus in ref)
matched_status: Taxonomic status of the matched name (same as
taxonomicStatus in ref)
match_type: Type of match (see the "Match types" section of
ts_match_names())
dist: Edit distance between the query and the matched name for fuzzy
matches, NA otherwise
Names that could not be matched or resolve to multiple, different synonyms
have NA for resolved_name.
query can take as input either a character vector of taxonomic names, or
the output of ts_match_names(). If the former, it will run
ts_match_names() to match the query to ref, then
resolve synonyms. If the latter, the scientific names in ref
should be the same used as reference with ts_match_names()
(this is not checked).
If multiple queries will be made against the same large reference (e.g., a
database such as World Flora Online), prepare it once with
ts_optimize_ref() and use the result as ref,
so that the reference is not parsed again on every call.
ref must be taxonomic data adhering to the Darwin Core standard.
Darwin Core includes many terms, but only four (taxonID,
acceptedNameUsageID, taxonomicStatus, and scientificName) are required
for this function.
Sigovini, M., Keppel, E., & Tagliapietra, D. (2016). Open Nomenclature in the biodiversity era. Methods in Ecology and Evolution, 7(10), 1217-1225. doi:10.1111/2041-210X.12594
# Load reference taxonomy in Darwin Core format
data(filmy_taxonomy)
ts_resolve_names("Gonocormus minutum", filmy_taxonomy)
#> # A tibble: 1 × 7
#> query resolved_name matched_name resolved_status matched_status match_type
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 Gonocorm… Crepidomanes… Gonocormus … accepted name synonym auto_fuzz…
#> # ℹ 1 more variable: dist <int>
# If you always want tibble output without specifying `tbl_out = TRUE`
# every time, set the option:
options(ts_tbl_out = TRUE)
ts_resolve_names("Gonocormus minutum", filmy_taxonomy)
#> # A tibble: 1 × 7
#> query resolved_name matched_name resolved_status matched_status match_type
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 Gonocorm… Crepidomanes… Gonocormus … accepted name synonym auto_fuzz…
#> # ℹ 1 more variable: dist <int>