Resolve synonyms in taxonomic names

After matching taxonomic names to a reference, some may match synonyms. This function resolves synonyms to their accepted names.

ts_resolve_names(
  query,
  ref_taxonomy,
  max_dist = 10,
  match_no_auth = FALSE,
  match_canon = FALSE,
  collapse_infra = FALSE,
  collapse_infra_exclude = NULL,
  docker = getOption("ts_docker", default = FALSE),
  tbl_out = getOption("ts_tbl_out", default = FALSE)
)

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_taxonomy

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

• taxonID: Unique identifier for each taxon.

• acceptedNameUsageID: If the taxon is a synonym, the unique identifier for the accepted name

• taxonomicStatus: The status of the use of the scientificName as a label for the taxon.

• scientificName: The full scientific name of the taxon, with authorship and date information if known.

max_dist

Max Levenshtein distance to allow during fuzzy matching (total insertions, deletions and substitutions). Default: 10.

match_no_auth

Logical; If no author is given in the query and the name (without author) occurs only once in the reference, accept the name in the reference as a match. Default: to not allow such a match (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).

collapse_infra

Logical; if the specific epithet and infraspecific epithet are the same, drop the infraspecific rank and epithet from the query. For more information, see ts_match_names().

collapse_infra_exclude

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

docker

Logical; if TRUE, docker will be used to run taxon-tools (so that taxon-tools need not be installed).

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.

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

• matched_status: Taxonomic status of the matched name (same as taxonomicStatus in ref_taxonomy)

• match_type: Type of match (for a summary of match types, see taxon-tools manual)

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_taxonomy, then resolve synonyms. If the latter, the scientific names in ref_taxonomy should be the same used as reference with ts_match_names() (this is not checked).

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

Examples

if (ts_tt_installed()) {
  # Load reference taxonomy in Darwin Core format
  data(filmy_taxonomy)

  ts_resolve_names("Gonocormus minutum", filmy_taxonomy)
  # 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 × 6
#>   query              resolved_name               match…¹ resol…² match…³ match…⁴
#>   <chr>              <chr>                       <chr>   <chr>   <chr>   <chr>  
#> 1 Gonocormus minutum Crepidomanes minutum (Bl.)… Gonoco… accept… synonym auto_f…
#> # … with abbreviated variable names ¹​matched_name, ²​resolved_status,
#> #   ³​matched_status, ⁴​match_type