Allows for orthographic differences between query and reference by using fuzzy matching on parsed taxonomic names.
ts_match_names(
query,
ref,
manual_match = NULL,
max_dist = 3,
max_dist_genus = 2,
transpositions = FALSE,
match_canon = FALSE,
match_autonyms = FALSE,
match_autonyms_exclude = NULL,
simple = FALSE,
tbl_out = getOption("ts_tbl_out", default = FALSE),
strip_qualifiers = FALSE,
exclude_placeholders = TRUE,
collapse_infra = NULL,
collapse_infra_exclude = NULL,
reference = NULL,
match_no_auth = NULL
)Character vector or dataframe; taxonomic names to be queried.
If a character vector, missing values not allowed and all values must be
unique.
If a dataframe, should be taxonomic names parsed with
ts_parse_names().
Character vector or dataframe; taxonomic names to use as
reference. If a character vector, missing values not allowed and all values
must be unique. If a dataframe, should be taxonomic names parsed with
ts_parse_names(). Can also be the output of
ts_optimize_ref(), which saves the work of preparing
the reference when matching several times against the same large reference.
Optional. Dataframe of manually matched names that will
override any results from the name-matching engine. Must include columns,
query and match. The values of query are compared with the query names
(the name column, when query is a dataframe).
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. 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. 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.
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; return the output in a simplified format with only the
query name, matched reference name, and match type. Default: FALSE.
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/reference is a character vector; ignored if
already-parsed data.frames are passed in. 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.
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 with the following columns (if simple is FALSE):
query: Query name
reference: Matched reference name
match_type: Type of match (see the "Match types" section)
dist: Edit distance between query and reference for fuzzy matches
(auto_fuzzy, auto_fuzzy_canon, auto_fuzzy_genus), NA otherwise
id_query: Unique ID of query
id_ref: Unique ID of reference
genus_hybrid_sign_query: Genus hybrid sign in query
genus_name_query: Genus name of query
species_hybrid_sign_query: Species hybrid sign in query
specific_epithet_query: Specific epithet of query
infraspecific_rank_query: Infraspecific rank of query
infraspecific_epithet_query: Infraspecific epithet of query
author_query: Taxonomic author of query
genus_hybrid_sign_ref: Genus hybrid sign in reference
genus_name_ref: Genus name of reference
species_hybrid_sign_ref: Species hybrid sign in reference
specific_epithet_ref: Specific epithet of reference
infraspecific_rank_ref: Infraspecific rank of reference
infraspecific_epithet_ref: Infraspecific epithet of reference
author_ref: Taxonomic author of reference
If simple is TRUE, only return the first three columns above.
Names are matched in two steps:
Scientific names are parsed into their component parts (genus, species, variety, author, etc).
Names are fuzzily matched following taxonomic rules using the component parts.
Parsing is fairly fast (much faster than matching) but can take some time if
the number of names is very large. If multiple queries will be made against
the same large reference (e.g., a database such as World Flora Online), it
is recommended to prepare the reference once with
ts_optimize_ref() and use the result as reference. That
saves parsing the reference and building its match keys on every call, so it
is the faster option. Alternatively, parse the names first using
ts_parse_names(), and use the results as input to query
and/or reference.
match_autonyms is useful when the query and the reference do not agree on
whether to use names that have the same specific epithet and infraspecific
epithet (autonyms).
The match_type column says how a query was matched. Types are tried in
the order listed below, and the first one that finds a match is reported, so
earlier types are more certain than later ones. Always check results that
are not exact. If several reference records are equally good at the
first type that matches (for example, two names that differ only in an ex
author), every one of them is returned, so the ambiguity is visible.
Identical after normalization (safe to accept)
exact: all parts of the name, including the author, are identical.
autonym: identical once an autonym (e.g. "Blechnum lunare var. lunare")
is collapsed to the species name, "Blechnum lunare" (only when
match_autonyms is TRUE).
auto_punct: identical after ignoring differences in spaces, periods,
capitalization, and accented or other non-ASCII characters.
Differences in how the author is cited (usually safe)
auto_basio-, auto_basio+: identical once the basionym author, e.g.
(Turcz.) in Cardaminopsis umbrosa (Turcz.) Czerep., is dropped from
the reference (-) or the query (+).
auto_in-, auto_in+: identical once "in" elements (Tagawa in Morton
becomes Tagawa) are dropped from the reference or the query.
auto_exauth-, auto_exauth+: identical once the first author of an
"ex" citation is dropped, keeping the author after ex, from the
reference (-) or the query (+). In Hook. ex Smith, Hook. proposed
the name but Smith validly published it, so under the botanical Code the
name belongs to Smith: Foo bar Hook. ex Smith and Foo bar Smith are
the same name. A basionym author in parentheses is kept.
auto_irank: identical except for the infraspecific rank (e.g. var.
vs. subsp.).
The author before "ex" is used (check the result)
In an ex citation such as Willd. ex Schkuhr, the author before ex
proposed the name but did not validly publish it; under the botanical Code
the author after ex is the author of the name. These matches keep the
author before ex, so they are usually, but not always, the same name:
Foo bar Willd. could be a different name by Willd. If a query matches in
this way, look at the reference name and its author to decide whether it is
the name you meant. They are tried after auto_exauth, so a reference name
with the author after ex is preferred when there is one.
auto_exauth_both: both names have an "ex" citation with the same author
after ex but different authors before it (Hook. ex Smith and
DC. ex Smith), or one has no author before it (ex Smith). Under the
Code this is one name, but the two sources do not agree about who first
ascribed it.
auto_ex-, auto_ex+: identical once "in" and "ex" elements are dropped
from the reference (-) or the query (+): Willd. ex Schkuhr becomes
Willd.
auto_basexin: identical once basionym authors and "in"/"ex" elements are
dropped from both query and reference.
Canonical-name matches (the author is ignored; check the result)
The canonical name is genus + specific epithet + infraspecific epithet.
auto_canon: canonical names are identical. Used automatically for
queries without an author; for queries with an author, only when
match_canon = TRUE. Several reference names can share a canonical name
(homonyms), giving multiple hits.
Latin spelling variants (check the result)
auto_orthvar: identical once standard Latin orthographic variants in the
epithets are folded together: ae/oe = e, y = i, ph = f,
rh = r, th = t, and a final ii = i (e.g. sylvestris and
silvestris, caerulea and coerulea). For queries without an author,
canonical names are compared. This can occasionally merge epithets that
are genuinely different.
Fuzzy matches (misspellings; always verify)
auto_fuzzy: query has an author; the whole name (author included) is
within max_dist of a reference name.
auto_fuzzy_canon: query has no author; the canonical names are within
max_dist.
Fuzzy genus matches (misspelled genus; always verify)
auto_fuzzy_genus: the genus of the query is not in the reference, but is
within max_dist_genus of a reference genus, and the rest of the name then
matches within max_dist (the total distance includes the genus edits).
No match
no_match: nothing in the reference was close enough.
Fuzzy matching is computed with the Levenshtein distance (total insertions, deletions, and substitutions). The rules for authorship fit plants, algae, and fungi, where the basionym author is given in parentheses and the year is usually omitted; animal names, which normally include the year, may match less well.
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
ts_match_names(
"Crepidomanes minutus",
c("Crepidomanes minutum", "Hymenophyllum polyanthos"),
simple = TRUE
)
#> query reference match_type
#> 1 Crepidomanes minutus Crepidomanes minutum auto_fuzzy_canon
# If names are too distant, they won't match
ts_match_names(
query = "Crepidblah foo",
reference = c("Crepidomanes minutum", "Hymenophyllum polyanthos"),
simple = TRUE
)
#> query reference match_type
#> 1 Crepidblah foo <NA> no_match
# But we can force a match manually
ts_match_names(
query = "Crepidblah foo",
reference = c("Crepidomanes minutum", "Hymenophyllum polyanthos"),
manual_match = data.frame(
query = c("Crepidblah foo"),
match = c("Crepidomanes minutum")
),
simple = TRUE
)
#> query reference match_type
#> 1 Crepidblah foo Crepidomanes minutum manual
# If you always want tibble output without specifying `tbl_out = TRUE`
# every time, set the option:
options(ts_tbl_out = TRUE)
ts_match_names(
"Crepidomanes minutus",
c("Crepidomanes minutum", "Hymenophyllum polyanthos")
)
#> # A tibble: 1 × 20
#> query reference match_type dist id_query id_ref genus_hybrid_sign_qu…¹
#> <chr> <chr> <chr> <int> <chr> <chr> <chr>
#> 1 Crepidomane… Crepidom… auto_fuzz… 1 c1ad73e… ref-1 NA
#> # ℹ abbreviated name: ¹genus_hybrid_sign_query
#> # ℹ 13 more variables: genus_name_query <chr>, species_hybrid_sign_query <chr>,
#> # specific_epithet_query <chr>, infraspecific_rank_query <chr>,
#> # infraspecific_epithet_query <chr>, author_query <chr>,
#> # genus_hybrid_sign_ref <chr>, genus_name_ref <chr>,
#> # species_hybrid_sign_ref <chr>, specific_epithet_ref <chr>,
#> # infraspecific_rank_ref <chr>, infraspecific_epithet_ref <chr>, …
# Example using the match_autonyms argument
ts_match_names(
c(
"Crepidomanes minutus", "Blechnum lunare var. lunare",
"Blechnum lunare", "Bar foo var. foo", "Bar foo"
),
c(
"Crepidomanes minutum", "Hymenophyllum polyanthos", "Blechnum lunare",
"Bar foo"
),
match_autonyms = TRUE,
match_autonyms_exclude = "Bar foo var. foo",
simple = TRUE
)
#> # A tibble: 5 × 3
#> query reference match_type
#> <chr> <chr> <chr>
#> 1 Crepidomanes minutus Crepidomanes minutum auto_fuzzy_canon
#> 2 Blechnum lunare var. lunare Blechnum lunare autonym
#> 3 Blechnum lunare Blechnum lunare exact
#> 4 Bar foo var. foo Bar foo auto_fuzzy_canon
#> 5 Bar foo Bar foo exact