Skip to contents

Resolve common (vernacular) names to scientific names

Source: R/comm2sci.R
comm2sci.Rd

The reverse of add_common_names(): given a common name, return the accepted scientific name(s) it refers to. Reads the bundled common_names enrichment (GBIF, NCBI, and Open Tree vernaculars) offline; the first call may trigger the one-time download. A common name is frequently ambiguous (several species share "bluebell", "robin"), so the result can carry more than one row per query.

Usage

comm2sci(
  x,
  lang = NULL,
  output = c("lookup", "result"),
  backbone = NULL,
  ...,
  verbose = TRUE
)

Arguments

x

Character vector of common names.

lang

Character. Restrict to one language: an ISO 639-1 code ("en", "de", ...) as used by the GBIF source, or NA for the untagged NCBI/Open Tree names. NULL (default) searches every language. List the languages present with enrichment_groups("common_names").

output

What to return. "lookup" (default): the lookup table (common name -> scientific name). "result": the matched scientific names run through taxify(), as a taxify_result (with a leading query_common column), so the result pipes straight into the add_*() enrichments.

backbone

Passed to taxify() when output = "result"; NULL (default) uses every installed backbone. Ignored for "lookup".

...

Matching arguments passed to taxify() when output = "result" (e.g. fuzzy, fuzzy_threshold, kingdom, region). Must be named.

verbose

Logical. Default TRUE.

Value

For output = "lookup", a data.frame with one row per (query, scientific match, language):

input_name

The common name as supplied.

common_name

The vernacular name as stored in the source (its casing, which may differ from input_name).

accepted_name

The accepted scientific name.

lang

Language tag of the vernacular name (NA for NCBI/Open Tree).

A query with no match contributes no rows. For output = "result", a taxify_result with one row per (query, distinct scientific match), with query_common prepended.

See also

add_common_names() for the forward direction (scientific -> common), taxify().

Examples

# Runs offline against the bundled example database.
old <- options(taxify.data_dir = taxify_example_data())

# The bundled example database maps "example_common_name" to Quercus robur;
# against the full download this is where "pedunculate oak" would resolve.
comm2sci("example_common_name")

# Resolve straight to a taxify_result you can enrich
comm2sci("example_common_name", output = "result", backbone = "wfo")

options(old)