This vignette explains the three basic steps of the taxonomic name resolution workflow, which consist of:
We’ll start by loading taxastand. For more information
on installing taxastand, see here.
In R, scientific names are often just stored as character vectors (strings). For example,
example_name <- "Crepidomanes minutum (Bl.) K. Iwats."However, such a name actually consists of several distinct parts:
"Crepidomanes minutum (Bl.) K. Iwats."
------------- ------- ---------------
| | |
genus specific author
epithet
Furthermore, in the case of this name, it was originally named by
Blume ((Bl.)), then transferred to a different genus by
Iwatsuki (K. Iwats.).
When working with taxonomic names, it can be useful to
parse the name into its component parts. That is what
ts_parse_names() does. It takes a character vector as input
and returns a dataframe:
ts_parse_names(example_name)
#> name id genus_hybrid_sign
#> 1 Crepidomanes minutum (Bl.) K. Iwats. d6ec2820-1 <NA>
#> genus_name species_hybrid_sign specific_epithet infraspecific_rank
#> 1 Crepidomanes <NA> minutum <NA>
#> infraspecific_epithet author
#> 1 <NA> (Bl.) K. Iwats.The first column, name, is the original input name.
id is a unique identifier attached to the name. The rest of
the columns are the
parsed components of the name.
Note that the name parsing algorithm used by taxastand
is case-sensitive! It assumes that the standard
capitalization of scientific names is being used: genus is
capitalized, specific epithet is lower case, author is capitalized as a
proper noun, etc. Name parsing probably won’t work without this
type of capitalization.
Now that we’ve parsed a name, in the next section we will see why this is useful for matching names to each other.
One reason that name parsing is important is because some scientific names may differ only in certain components.
For example, the name Hymenophyllum wilsonii corresponds to two different scientific names with different authors, Hymenophyllum wilsonii Fée and Hymenophyllum wilsonii Hook.
We can see this by querying the name without an author:
ts_match_names(
"Hymenophyllum wilsonii",
c(
"Hymenophyllum wilsonii Fée",
"Hymenophyllum wilsonii Hook."
),
simple = TRUE
)
#> query reference match_type
#> 1 Hymenophyllum wilsonii Hymenophyllum wilsonii Fée auto_canon
#> 2 Hymenophyllum wilsonii Hymenophyllum wilsonii Hook. auto_canonts_match_names() matches both scientific names1, because
the algorithm it can’t distinguish between them without additional
information. So it is almost always better to include the
taxonomic author in the query, to distinguish between such
cases.
However, there can be quite a bit of variation in how authors are
recorded. Sometimes names are abbreviated to different lengths, or the
basionym author (an author name in parentheses) might get left out by
accident, etc. The algorithm used by taxastand can account
for this (to a point). Here is an example where the query lacks a
basionym author:
ts_match_names(
"Hymenophyllum taiwanense C. V. Morton",
c(
"Hymenophyllum taiwanense (Tagawa) C. V. Morton",
"Hymenophyllum taiwanense De Vol"
),
simple = TRUE
)
#> query
#> 1 Hymenophyllum taiwanense C. V. Morton
#> reference match_type
#> 1 Hymenophyllum taiwanense (Tagawa) C. V. Morton auto_basio-The name matching algorithm was able to narrow the match down to
Hymenophyllum taiwanense (Tagawa) C. V. Morton even though
the query lacked (Tagawa). Furthermore, the
match_type tells us how the matching was done:
auto_basio- means an automatic match based on excluding the
basionym author from the reference. It is recommended to always
check any results that weren’t identical (exact)
to verify that the matching algorithm worked correctly, especially for
fuzzy matches (auto_fuzzy).
Here is a summary of the values taken by match_type
(also documented in the “Match types” section of
?ts_match_names, ordered by how much each can be
trusted):
exact: Exact match to all parts of the name (genus
hybrid marker, genus name, species hybrid marker, species epithet,
infraspecific rank signifier, infraspecific rank, author string).autonym (only applies if match_autonyms is
TRUE): Exact match after an autonym (such as
Blechnum lunare var. lunare) is collapsed to the species
name (Blechnum lunare).auto_punct: Exact match to all parts of the name after
removing mis-matching spaces, periods, non-ASCII author name characters,
etc.auto_basio-: Match after excluding the basionym author
from the reference. For example,
Cardaminopsis umbrosa Czerep.
vs. Cardaminopsis umbrosa (Turcz.) Czerep.)); the basionym
author is (Turcz.).auto_basio+: Match after excluding the basionym author
from the query.auto_in-: Match after excluding all in
elements from reference. An in element refers to phrases such
as Tagawa in Morton. The version excluding in
elements is Tagawa.auto_in+: Match after excluding all in
elements from query.auto_exauth-: Match after excluding the first author of
an ex citation from the reference, keeping the author after
ex. For Hook. ex Smith, Smith validly published
the name and is its author under the botanical Code, so
Hook. ex Smith and Smith are the same name. A
basionym author in parentheses is kept.auto_exauth+: Same, excluding the first author of an
ex citation from the query.auto_irank: Match where all elements agree except for
infraspecific rank.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, so check these.auto_ex-: Match after excluding all in and
ex elements from reference. An ex element refers to
phrases such as Rändel ex D.F.Murray. The version excluding
ex elements is Rändel, the author who did
not validly publish the name, so these matches are usually, but
not always, the same name: check the reference name and author before
accepting one. They are tried after auto_exauth, so a
reference name with the author after ex is preferred.auto_ex+: Match after excluding all in and
ex elements from query.auto_basexin: Match after excluding all basionym
authors and all in and ex elements from query and
reference. Like auto_ex-, check these matches.auto_orthvar: Match after folding standard Latin
spelling variants in the epithets together
(ae/oe = e, y =
i, ph = f, rh =
r, th = t, final ii
= i), e.g., sylvestris
vs. silvestris. For queries without an author, canonical
names are compared. Occasionally this merges epithets that are genuinely
different.auto_fuzzy: Fuzzy match for a query that has an author;
match between whole scientific names (including the author) allowed up
to the threshold given by max_dist, the Levenshtein
distance including total insertions, deletions and substitutions
(with transpositions = TRUE, a swap of two adjacent letters
counts as one edit instead of two). The distance of each fuzzy hit is
given in the dist column of the full output.auto_canon: Match by “canonical form”, i.e., genus plus
specific epithet plus infraspecific epithet (if present), not including
the infraspecific specifier (“subsp.”, etc.). This is used automatically
for queries without an author; for queries with an author, it is only
used if match_canon is TRUE.auto_fuzzy_canon: Fuzzy match for a query that has
no author; match between “canonical forms” (see
auto_canon) allowed up to the threshold given by
max_dist. The author string is ignored, so it does not
count towards the distance. All reference names within the threshold are
returned.auto_fuzzy_genus: Fuzzy match for a query whose genus
is not in the reference (e.g., a misspelled genus): reference genera
within max_dist_genus of the query genus are tried, and the
rest of the name must still be within max_dist (the total
distance includes the genus edits).no_match: No match detected.The matching algorithm will prefer match codes higher in the list; so
if a name could be matched both by auto_punct and
auto_fuzzy, it will be matched based on
auto_punct2. For queries without an author, an
identical canonical name (auto_canon) is preferred over a
fuzzy canonical match (auto_fuzzy_canon).
Name resolution refers to the process of mapping a query name to its standard version. This could just be accounting for orthographic variations, or it could involve resolving synonyms: different names that actually refer to the same species.
In order to conduct name resolution, we require a taxonomic
standard in the form of a dataframe. taxastand
requires that the taxonomic standard conform to Darwin Core standards. There are many
sources of taxonomic data online, including GBIF,
Catalog of Life, and ITIS among others. The Setting up a reference vignette shows
how to get a standard database such as ITIS or PPG with
ts_load_ref(), and how to turn your own table into the
format taxastand needs. taxastand does not
check that the table is valid Darwin Core; the dwctaxon package can
validate it (dwctaxon::dct_validate()).
taxastand comes supplied with an example taxonomic
standard for filmy ferns (family Hymenophyllaceae):
# Load example reference taxonomy in Darwin Core format
data(filmy_taxonomy)
# Take a look at the columns used by taxastand
head(filmy_taxonomy[c(
"taxonID", "acceptedNameUsageID", "taxonomicStatus", "scientificName"
)])
#> taxonID acceptedNameUsageID taxonomicStatus
#> 1 54115096 NA accepted name
#> 2 54133783 54115097 synonym
#> 3 54115097 NA accepted name
#> 4 54133784 54115098 synonym
#> 5 54115098 NA accepted name
#> 6 54133785 54115099 synonym
#> scientificName
#> 1 Cephalomanes atrovirens Presl
#> 2 Trichomanes crassum Copel.
#> 3 Cephalomanes crassum (Copel.) M. G. Price
#> 4 Trichomanes densinervium Copel.
#> 5 Cephalomanes densinervium (Copel.) Copel.
#> 6 Trichomanes infundibulare Alderw.Here, taxonID is a unique identifier for each taxonomic
name. acceptedNameUsageID only applies in the case of
synonyms: it tells us the taxonID of the accepted name
corresponding to that synonym. taxonomicStatus describes
the status of the name, typically either as an accepted name, synonym,
or something else (“dubious”, etc.). Finally, the
scientificName is the full scientific name, preferably with
the author.
In its most simple usage, ts_resolve_names() can take as
input a character vector to query, and provide the resolved
name in the taxonomic standard (reference):
ts_resolve_names("Gonocormus minutum", filmy_taxonomy)
#> query resolved_name
#> 1 Gonocormus minutum Crepidomanes minutum (Bl.) K. Iwats.
#> matched_name resolved_status matched_status
#> 1 Gonocormus minutus (Bl.) Bosch accepted name synonym
#> match_type dist
#> 1 auto_fuzzy_canon 1In this case, the query, Gonocormus minutum was a
misspelled name that is actually a synonym for Crepidomanes
minutum (Bl.) K. Iwats. Under the hood,
ts_resolve_names() is calling both
ts_parse_names() and ts_match_names() to do
parsing and matching steps before name resolution3.
However, when used this way, ts_resolve_names() may not
be able to provide a resolved name if the input is not matched
unambiguously:
alatum_res <- ts_resolve_names("Didymoglossum alatum", filmy_taxonomy)
alatum_res
#> query resolved_name matched_name
#> 1 Didymoglossum alatum <NA> Didymoglossum alatum (Sw.) Desv.
#> 2 Didymoglossum alatum <NA> Didymoglossum alatum (Schkuhr) Presl
#> resolved_status matched_status match_type dist
#> 1 <NA> ambiguous synonym auto_canon NA
#> 2 <NA> ambiguous synonym auto_canon NAIn this case, name resolution using the default settings produced 2
possible answers, but no resolved_name. The trouble is that
our query lacked an author. A query without an author is matched on its
canonical name (genus, specific epithet, and infraspecific epithet),
ignoring the author (match type auto_canon, or
auto_fuzzy_canon if the name also needs fuzzy matching).
Here the reference contains two different names with the same canonical
name, Didymoglossum alatum (Sw.) Desv. and Didymoglossum
alatum (Schkuhr) Presl, and they resolve to different accepted
names, so there is no way to tell which one was meant. The remedy is to
include the author in the query:
ts_resolve_names("Didymoglossum alatum (Sw.) Desv.", filmy_taxonomy)
#> query resolved_name
#> 1 Didymoglossum alatum (Sw.) Desv. Vandenboschia radicans (Sw.) Copel.
#> matched_name resolved_status matched_status match_type
#> 1 Didymoglossum alatum (Sw.) Desv. accepted name ambiguous synonym exact
#> dist
#> 1 NAWith the author, the query matches a single name exactly
(exact), which resolves to its accepted name.
Name resolution workflows typically involve tweaking the matching
arguments (such as match_canon and max_dist)
to resolve as many names as possible automatically, followed by some
amount of manual editing of the names that remain unresolved.
A benefit of taxastand is that, if during the name
resolution workflow we discover mistakes in the reference database, the
reference database can be edited so that the query names resolve
correctly (this is not possible with packages that rely on querying a
remote taxonomic database that can’t be modified by the user). The dwctaxon package has
functions for editing Darwin Core taxonomic data, such as adding and
modifying rows while keeping synonyms mapped correctly.
If you will match several batches of queries against a large
reference, optimize it once with ts_optimize_ref(); see Large references in the
“Setting up a reference” vignette.
Note that ts_match_names() did the name
parsing by calling ts_parse_names() for us internally. This
is usually fine, but it can also take parsed names (dataframes) produced
by ts_parse_names() as input to either query
or reference.↩︎
The algorithm used by taxastand is
optimized for plants, algae, and fungi, which vary in their taxonomic rules somewhat from
animals. For example, plants include basionym authors in parentheses
followed by the combination author, and typically don’t include the
year, whereas animals normally include the year and may not provide the
combination author.↩︎
You can use the output of ts_match_names()
to the query input of ts_parse_names() if you
want to see the matching results first.↩︎