ts_resolve_names: Resolve synonyms in taxonomic names

In joelnitta/taxastand: Taxonomic Name Standardization

Resolve synonyms in taxonomic names

Description

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

Usage

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.

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.

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.

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

joelnitta/taxastand documentation built on Sept. 21, 2022, 12:49 p.m.