This vignette explains the three basic steps of the taxonomic name resolution workflow, which consist of:

  1. Name parsing
  2. Name matching
  3. Name resolution

Setup

We’ll start by loading taxastand. For more information on installing taxastand, see here.

Name parsing

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.

Name matching

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_canon

ts_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

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    1

In 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   NA

In 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   NA

With 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.

Large references

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.


  1. 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.↩︎

  2. 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.↩︎

  3. 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.↩︎