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
)

Arguments

query

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().

ref

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.

manual_match

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_dist

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_dist_genus

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.

transpositions

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.

match_canon

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

match_autonyms

Logical; match autonyms (names whose specific epithet and infraspecific epithet are the same) with the species name. Default: FALSE.

match_autonyms_exclude

Character vector; taxonomic names to exclude from match_autonyms. Any names used must match those in query exactly, or they won't be excluded.

simple

Logical; return the output in a simplified format with only the query name, matched reference name, and match type. Default: FALSE.

tbl_out

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.

strip_qualifiers

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.

exclude_placeholders

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.

collapse_infra, collapse_infra_exclude

Aliases of match_autonyms and match_autonyms_exclude, kept so that existing code keeps working.

reference

Alias of ref, the name used before taxastand 3.0.0; it will be deprecated in a future version.

match_no_auth

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.

Value

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.

Details

Names are matched in two steps:

  1. Scientific names are parsed into their component parts (genus, species, variety, author, etc).

  2. 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).

Match types

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.

References

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

Examples

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