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
)

Arguments

query

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

ref

Dataframe; reference taxonomic data adhering to the Darwin Core standard with the following columns:

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_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. See ts_match_names(). 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. See ts_match_names(). 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. For more information, see ts_match_names(). 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.

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 is a character vector. 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.

closest_only

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.

collapse_infra, collapse_infra_exclude

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

ref_taxonomy

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

Details

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.

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

# 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>