Add species information provided by the GBIF taxonomic backbone API

Development on gbif_species_name_match() is complete, and for new code we strongly recommend switching to rgbif::name_backbone_checklist(), which is easier to use, has more features, and still under active development. This functions extends an existing dataframe with additional columns provided by the GBIF taxonomic backbone and matched on the species (scientific) name, which need to be an available column in the dataframe.

This function is essentially a wrapper around the existing rgbif name_backbone and extends the application to a data.frame. Such extension has been added to rgbif via the function rgbif::name_backbone_checklist. # nolint For more information on the name matching API of GBIF on which rgbif relies, see https://www.gbif.org/developer/species/#searching.

gbif_species_name_match(
  df,
  name = "name",
  gbif_terms = c("usageKey", "scientificName", "rank", "order", "matchType", "phylum",
    "kingdom", "genus", "class", "confidence", "synonym", "status", "family"),
  ...
)

Arguments

df

data.frame with species information

name

char column name of the column containing the names used for the name matching with the GBIF taxonomic backbone. Default: "name".

gbif_terms

list of valid GBIF terms to add as additional columns to the data.frame. Default: usageKey, scientificName, rank, order, matchType, phylum, kingdom, genus, class, confidence, synonym, status, family.

...

any parameter to pass to rgbif function name_bakbone. One of: rank, kingdom, phylum, class, order, family, genus, strict, verbose, start, limit, curlopts. See ?name_backbone for more details.

Value

a tibble data.frame with GBIF information as additional columns. If none of the taxa in df is matched, only the columns confidence, matchType and synonym are added. This behaviour is inherited by rgbif::name_backbone.

Examples

if (FALSE) {
library(readr)
library(dplyr)
species_list <- read_csv(paste0(
  "https://raw.githubusercontent.com/inbo",
  "/inbo-pyutils/master/gbif/gbif_name_match",
  "/sample.csv"
),
trim_ws = TRUE, col_types = cols()
)
# basic usage
species_list %>%
  gbif_species_name_match()
# pass optional parameters to name_backbone
species_list %>%
  gbif_species_name_match(name = "name", kingdom = "kingdom", strict = TRUE)
# select GBIF terms
species_list %>%
  gbif_species_name_match(gbif_terms = c("scientificName", "rank"))
}