Skip to contents

Lookup names in the GBIF backbone taxonomy in a checklist.

Source: R/name_backbone_checklist.R
name_backbone_checklist.Rd

Lookup names in the GBIF backbone taxonomy in a checklist.

Usage

name_backbone_checklist(
  name_data = NULL,
  rank = NULL,
  kingdom = NULL,
  phylum = NULL,
  class = NULL,
  order = NULL,
  family = NULL,
  genus = NULL,
  strict = FALSE,
  verbose = FALSE,
  curlopts = list()
)

Arguments

name_data

(data.frame or vector) see details.

rank

(character) default value (optional).

kingdom

(character) default value (optional).

phylum

(character) default value (optional).

class

(character) default value (optional).

order

(character) default value (optional).

family

(character) default value (optional).

genus

(character) default value (optional).

strict

(logical) strict=TRUE will not attempt to fuzzy match or return higherrankmatches.

verbose

(logical) If true it shows alternative matches which were considered but then rejected.

curlopts

list of named curl options passed on to HttpClient. see curl::curl_options for curl options

Value

A data.frame of matched names.

Details

This function is an alternative for name_backbone(), which will work with a list of names (a vector or a data.frame). The data.frame should have the following column names, but only the 'name' column is required. If only one column is present, then that column is assumed to be the 'name' column.

  • name : (required)

  • rank : (optional)

  • kingdom : (optional)

  • phylum : (optional)

  • class : (optional)

  • order : (optional)

  • family : (optional)

  • genus : (optional)

The input columns will be returned as "verbatim_name","verbatim_rank", "verbatim_phylum" ect. A column of "verbatim_index" will also be returned giving the index of the input.

The following aliases for the 'name' column will work (any case or with '_' will work) :

  • "scientificName", "ScientificName", "scientific_name" ...

  • "sci_name", "sciname", "SCI_NAME" ...

  • "names", "NAMES" ...

  • "species", "SPECIES" ...

  • "species_name", "speciesname" ...

  • "sp_name", "SP_NAME", "spname" ...

  • "taxon_name", "taxonname", "TAXON NAME" ...

If more than one aliases is present and no column is named 'name', then the left-most column with an acceptable aliased name above is used.

If verbose=TRUE, a column called is_alternative will be returned, which species if a name was originally a first choice or not. is_alternative=TRUE means the name was not is not considered to be the best match by GBIF.

Default values for rank, kingdom, phylum, class, order, family, and genus can can be supplied. If a default value is supplied, the values for these fields are ignored in name_data, and the default value is used instead. This is most useful if you have a list of names and you know they are all plants, insects, birds, ect. You can also input multiple values, if they are the same length as list of names you are trying to match.

This function can also be used with a character vector of names. In that case no column names are needed of course.

This function is very similar to the GBIF species-lookup tool. https://www.gbif.org/tools/species-lookup.

If you have 1000s of names to match, it can take some minutes to get back all of the matches. I have tested it with 60K names. Scientific names with author details usually get better matches.

See also article Working With Taxonomic Names.

Examples

if (FALSE) {

library(rgbif)

name_data <- data.frame(
 scientificName = c(
   "Cirsium arvense (L.) Scop.", # a plant
   "Calopteryx splendens (Harris, 1780)", # an insect
   "Puma concolor (Linnaeus, 1771)", # a big cat
   "Ceylonosticta alwisi (Priyadarshana & Wijewardhane, 2016)", # newly discovered insect 
   "Puma concuolor (Linnaeus, 1771)", # a mis-spelled big cat
   "Fake species (John Waller 2021)", # a fake species
   "Calopteryx" # Just a Genus   
 ), description = c(
   "a plant",
   "an insect",
   "a big cat",
   "newly discovered insect",
   "a mis-spelled big cat",
   "a fake species",
   "just a GENUS"
 ), 
 kingdom = c(
   "Plantae",
   "Animalia",
   "Animalia",
   "Animalia",
   "Animalia",
   "Johnlia",
   "Animalia"
 ))

name_backbone_checklist(name_data)

# return more than 1 result per name
name_backbone_checklist(name_data,verbose=TRUE) 

# works with just vectors too 
name_list <- c(
"Cirsium arvense (L.) Scop.", 
"Calopteryx splendens (Harris, 1780)", 
"Puma concolor (Linnaeus, 1771)", 
"Ceylonosticta alwisi (Priyadarshana & Wijewardhane, 2016)", 
"Puma concuolor", 
"Fake species (John Waller 2021)", 
"Calopteryx")

name_backbone_checklist(name_list)
name_backbone_checklist(name_list,verbose=TRUE)
name_backbone_checklist(name_list,strict=TRUE) 

# default values
name_backbone_checklist(c("Aloe arborecens Mill.",
"Cirsium arvense (L.) Scop."),kingdom="Plantae")
name_backbone_checklist(c("Aloe arborecens Mill.",
"Calopteryx splendens (Harris, 1780)"),kingdom=c("Plantae","Animalia"))

}