Package 'taxize'

Description

This package interacts with a suite of web 'APIs' for taxonomic tasks, such as verifying species names, getting taxonomic hierarchies, and verifying name spelling.

About

Allows users to search over many websites for species names (scientific and common) and download up- and downstream taxonomic hierarchical information - and many other things.

The functions in the package that hit a specific API have a prefix and suffix separated by an underscore. They follow the format of service_whatitdoes. For example, gnr_resolve uses the Global Names Resolver API to resolve species names.

General functions in the package that don't hit a specific API don't have two words separated by an underscore, e.g., classification

You need API keys for some data sources. See taxize-authentication for more information.

Currently supported APIs

If the source above has a TRUE in the ⁠SOAP?⁠ column, it is not available in this package. They are available from a different package called taxizesoap. See the GitHub repo for how to install https://github.com/ropensci/taxizesoap

Catalogue of Life (COL)

COL introduced rate limiting recently in 2019 - which has made the API essentially unusable - CoL+ is coming soon and we'll incorporate it here when it's stable. See https://github.com/ropensci/colpluz for the R implementation for CoL+

Author(s)

Scott Chamberlain

Eduard Szoecs [email protected]

Zachary Foster [email protected]

Carl Boettiger [email protected]

Karthik Ram [email protected]

Ignasi Bartomeus [email protected]

John Baumgartner [email protected]

James O'Donnell [email protected]

Description

Generic names and their replacements from the Angiosperm Phylogeny Group III system of flowering plant classification.

Usage

apgOrders(...)

apgFamilies(...)

Arguments

References

http://www.mobot.org/MOBOT/research/APweb/

Examples

## Not run: 
head(apgOrders())
head(apgFamilies())

## End(Not run)

Description

Family names and their replacements from the Angiosperm Phylogeny Website system of flowering plant classification.

Format

A data frame with 1705 rows and 6 variables:

• family: family name

• synonym: if accepted=FALSE, this is the accepted name; if accepted=TRUE, this is NA, and the name in family is accepted

• order: order name for the family

• accepted: logical, if name in family column is accepted or not

• original: original data record from APG website, mapping name in family column to a new name, if there is one

• accepted_name: accepted name. accepted names, combining those that are accepted from family column, with the new name from synonym if applicable

Details

This dataset is from Version 14, incorporated on 2020-06-03, generated using apgFamilies()

(update script in inst/ignore/apg_script.R)

Source

http://www.mobot.org/MOBOT/research/APweb/

Description

Lookup in the APGIII taxonomy and replace family names

Usage

apg_lookup(taxa, rank = "family")

Arguments

Details

Internally in this function, we use the datasets apg_families and apg_orders - see their descriptions for the data in them. The functions apgOrders() apgFamilies() are for scraping current content from the http://www.mobot.org/MOBOT/research/APweb/ website

The datasets used in this function are from the most recent version of APGIII, Version 14 (http://www.mobot.org/MOBOT/research/APweb/)

Value

A APGIII family or order name, the original name if the name is the same as APG has, or NA if no match found

Examples

# New name found
apg_lookup(taxa = "Hyacinthaceae", rank = "family")
# Name is the same
apg_lookup(taxa = "Poaceae", rank = "family")
apg_lookup(taxa = "Asteraceae", rank = "family")
# Name not found
apg_lookup(taxa = "Foobar", rank = "family")

# New name found
apg_lookup(taxa = "Acerales", rank = "order")
# Name is the same
apg_lookup(taxa = "Acorales", rank = "order")
# Name not found
apg_lookup(taxa = "Foobar", rank = "order")

Description

Order names and their replacements from the Angiosperm Phylogeny Website system of flowering plant classification.

Format

A data frame with 576 rows and 5 variables:

• order: order name

• synonym: if accepted=FALSE, this is the accepted name; if accepted=TRUE, this is NA, and the name in order is accepted

• accepted: logical, if name in order column is accepted or not

• original: original data record from APG website, mapping name in order column to a new name, if there is one

• accepted_name: accepted name. accepted names, combining those that are accepted from order column, with the new name from synonym if applicable

Details

This dataset is from Version 14, incorporated on 2020-06-03, generated using apgOrders()

(update script in inst/ignore/apg_script.R)

Source

http://www.mobot.org/MOBOT/research/APweb/

Description

Retrieve all taxa names downstream in hierarchy for BOLD

Usage

bold_downstream(id, downto, intermediate = FALSE, ...)

Arguments

Details

BEWARE: This function scrapes the BOLD website, so may be unstable. That is, one day it may work, and the next it may fail. Open an issue if you encounter an error: https://github.com/ropensci/taxize/issues

Value

data.frame of taxonomic information downstream to family from e.g., Order, Class, etc., or if intermediated=TRUE, list of length two, with target taxon rank names, and intermediate names.

Examples

## Not run: 
## the genus Gadus
bold_downstream(id = 3451, downto="species")

bold_downstream(id = 443, downto="genus")
bold_downstream(id = 443, downto="genus", intermediate=TRUE)

## End(Not run)

Description

Search Barcode of Life for taxonomic IDs

Usage

bold_search(
  sci = NULL,
  id = NULL,
  fuzzy = FALSE,
  dataTypes = "basic",
  includeTree = FALSE,
  response = FALSE,
  name = NULL,
  ...
)

Arguments

Details

You must provide one of sci or id to this function. The other parameters are optional. Note that when passing in sci, fuzzy can be used as well, while if id is passed, then fuzzy is ignored, and dataTypes includeTree can be used.

Options for dataTypes parameter:

• all returns all data

• basic returns basic taxon information

• images returns specimen image. Includes copyright information, image URL, image metadata.

• stats Returns specimen and sequence statistics. Includes public species count, public BIN count, public marker counts, public record count, specimen count, sequenced specimen count, barcode specimen count, species count, barcode species count.

• geo Returns collection site information. Includes country, collection site map.

• sequencinglabs Returns sequencing labs. Includes lab name, record count.

• depository Returns specimen depositories. Includes depository name, record count.

• thirdparty Returns information from third parties. Includes wikipedia summary, wikipedia URL, GBIF map.

Value

A list of data.frame's.

References

http://www.boldsystems.org/index.php/resources/api

Examples

## Not run: 
# A basic example
bold_search(sci="Apis")
bold_search(sci="Agapostemon")
bold_search(sci="Poa")

# Fuzzy search
head(bold_search(sci="Po", fuzzy=TRUE))
head(bold_search(sci="Aga", fuzzy=TRUE))

# Many names
bold_search(sci=c("Apis","Puma concolor"))
nms <- names_list('species')
bold_search(sci=nms)

# Searching by ID - dataTypes can be used, and includeTree can be used
bold_search(id=88899)
bold_search(id=88899, dataTypes="stats")
bold_search(id=88899, dataTypes="geo")
bold_search(id=88899, dataTypes="basic")
bold_search(id=88899, includeTree=TRUE)

## End(Not run)

Description

This function is different from downstream() in that it only collects immediate taxonomic children, while downstream() collects taxonomic names down to a specified taxonomic rank, e.g., getting all species in a family.

Usage

children(...)

## Default S3 method:
children(sci_id, db = NULL, rows = NA, x = NULL, ...)

## S3 method for class 'tsn'
children(sci_id, db = NULL, ...)

## S3 method for class 'wormsid'
children(sci_id, db = NULL, ...)

## S3 method for class 'ids'
children(sci_id, db = NULL, ...)

## S3 method for class 'uid'
children(sci_id, db = NULL, ...)

## S3 method for class 'boldid'
children(sci_id, db = NULL, ...)

Arguments

Value

A named list of data.frames with the children names of every supplied taxa. You get an NA if there was no match in the database.

ncbi

note that with db = "ncbi", we set ambiguous = TRUE; that is, children taxa with words like "unclassified", "unknown", "uncultured", "sp." are NOT removed

bold

BEWARE: db="bold" scrapes the BOLD website, so may be unstable. That is, one day it may work, and the next it may fail. Open an issue if you encounter an error: https://github.com/ropensci/taxize/issues

Examples

## Not run: 
# Plug in taxonomic IDs
children(161994, db = "itis")
children(8028, db = "ncbi")
## works with numeric if as character as well
children(161994, db = "itis")
children(88899, db = "bold")
children(as.boldid(88899))

# Plug in taxon names
children("Salmo", db = 'itis')
children("Salmo", db = 'ncbi')
children("Salmo", db = 'worms')
children("Salmo", db = 'bold')

# Plug in IDs
(id <- get_wormsid("Gadus"))
children(id)

# Many taxa
sp <- c("Tragia", "Schistocarpha", "Encalypta")
children(sp, db = 'itis')

# Two data sources
(ids <- get_ids("Apis", db = c('ncbi','itis')))
children(ids)
## same result
children(get_ids("Apis", db = c('ncbi','itis')))

# Use the rows parameter
children("Poa", db = 'itis')
children("Poa", db = 'itis', rows=1)

# use curl options
res <- children("Poa", db = 'itis', rows=1, verbose = TRUE)

## End(Not run)

Description

This function converts a list of hierarchies for individual species into a single species by taxonomic level matrix, then calculates a distance matrix based on taxonomy alone, and outputs either a phylo or dist object. See details for more information.

Usage

class2tree(input, varstep = TRUE, check = TRUE, remove_shared = FALSE, ...)

## S3 method for class 'classtree'
plot(x, ...)

## S3 method for class 'classtree'
print(x, ...)

Arguments

Details

See vegan::taxa2dist(). Thanks to Jari Oksanen for making the taxa2dist function and pointing it out, and Clarke & Warwick (1998, 2001), which taxa2dist was based on. The taxonomy tree created is not only based on the clustering of the taxonomy ranks (e.g. strain, species, genus, ...), but it also utilizes the actual taxon clades (e.g. mammals, plants or reptiles, etc.). The process of this function is as following: First, all possible taxonomy ranks and their corresponding IDs for each given taxon will be collected from the input. Then, the rank vectors of all taxa will be aligned, so that they together will become a matrix where columns are ordered taxonomy ranks of all taxa and rows are the rank vectors of those taxa. After that, the rank matrix will be converted into taxonomy ID matrix, any missing rank will have a pseudo ID from the previous rank. Finally, this taxonomy ID matrix will be used to cluster taxa that have similar taxonomy hierarchy together.

Value

An object of class "classtree" with slots:

• phylo - The resulting object, a phylo object

• classification - The classification data.frame, with taxa as rows, and different classification levels as columns

• distmat - Distance matrix

• names - The names of the tips of the phylogeny

Note that when you execute the resulting object, you only get the phylo object. You can get to the other 3 slots by calling them directly, like output$names, etc.

Examples

## Not run: 
spnames <- c('Quercus robur', 'Iris oratoria', 'Arachis paraguariensis',
 'Helianthus annuus','Madia elegans','Lupinus albicaulis',
 'Pinus lambertiana')
out <- classification(spnames, db='itis')
tr <- class2tree(out)
plot(tr)

spnames <- c('Klattia flava', 'Trollius sibiricus',
 'Arachis paraguariensis',
 'Tanacetum boreale', 'Gentiana yakushimensis','Sesamum schinzianum',
 'Pilea verrucosa','Tibouchina striphnocalyx','Lycium dasystemum',
 'Berkheya echinacea','Androcymbium villosum',
 'Helianthus annuus','Madia elegans','Lupinus albicaulis',
 'Pinus lambertiana')
out <- classification(spnames, db='ncbi')
tr <- class2tree(out)
plot(tr)

## End(Not run)

Description

Retrieve the taxonomic hierarchy for a given taxon ID.

Usage

classification(...)

## Default S3 method:
classification(
  sci_id,
  db = NULL,
  callopts = list(),
  return_id = TRUE,
  rows = NA,
  x = NULL,
  ...
)

## S3 method for class 'tsn'
classification(id, return_id = TRUE, ...)

## S3 method for class 'uid'
classification(
  id,
  callopts = list(),
  return_id = TRUE,
  batch_size = 50,
  max_tries = 3,
  ...
)

## S3 method for class 'eolid'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'tpsid'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'gbifid'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'nbnid'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'tolid'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'wormsid'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'natservid'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'boldid'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'wiki'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'pow'
classification(id, callopts = list(), return_id = TRUE, ...)

## S3 method for class 'ids'
classification(id, ...)

## S3 method for class 'classification'
cbind(...)

## S3 method for class 'classification'
rbind(...)

## S3 method for class 'classification_ids'
cbind(...)

## S3 method for class 'classification_ids'
rbind(...)

Arguments

Details

If IDs are supplied directly (not from the ⁠get_*⁠ functions) you must specify the type of ID. There is a timeout of 1/3 seconds between queries to NCBI.

BEWARE: Right now, NBN doesn't return the queried taxon in the classification. But you can attach it yourself quite easily of course. This behavior is different from the other data sources.

Value

A named list of data.frames with the taxonomic classification of every supplied taxa.

Lots of results

It may happen sometimes that you get more results back from your query than will show in the data.frame on screen. Our advice is to refine your query in those cases. On a data source basis we can attempt to help make it easier to refine queries, whether it be with the data provider (unlikely to happen), or in the code in this package (more likely) - let us know if you run into too many results problem and we'll see what we can do.

Authentication

See taxize-authentication

EOL

EOL does not have very good failure behavior. For example, if you submit an ID that does not exist they'll return a 500 HTTP error, which is not an appropriate error; it's probably that that ID does not exist in their database, but we can't know for sure. Isn't that fun?

NCBI Rate limits

In case you run into NCBI errors due to your rate limit being exceeded, see taxize_options(), where you can set ncbi_sleep.

HTTP version for NCBI requests

We hard code http_version = 2L to use HTTP/1.1 in HTTP requests to the Entrez API. See curl::curl_symbols('CURL_HTTP_VERSION')

See Also

get_tsn(), get_uid(), get_eolid(), get_tpsid(), get_gbifid(), get_wormsid(), get_natservid(), get_boldid(), get_wiki(), get_pow()

Examples

## Not run: 
# Plug in taxon IDs
classification(9606, db = 'ncbi')
classification(c(9606, 55062), db = 'ncbi')
classification(129313, db = 'itis')
classification(6985636, db = 'eol')
classification(126436, db = 'worms')
classification('Helianthus annuus', db = 'pow')
classification('Helianthus', db = 'pow')
classification('Asteraceae', db = 'pow')
classification("134717", db = 'natserv')
classification(c(2704179, 6162875, 8286319, 2441175, 731), db = 'gbif')
classification(25509881, db = 'tropicos')
classification("NBNSYS0000004786", db = 'nbn')
classification(as.nbnid("NBNSYS0000004786"), db = 'nbn')
classification(3930798, db = 'tol')

## works the same if IDs are in class character
classification(c("2704179", "2441176"), db = 'gbif')
classification("Agapostemon", db = "bold")

# wikispecies
classification("Malus domestica", db = "wiki")
classification("Pinus contorta", db = "wiki")
classification("Pinus contorta", db = "wiki", wiki_site = "commons")
classification("Pinus contorta", db = "wiki", wiki_site = "pedia")
classification("Pinus contorta", db = "wiki", wiki_site = "pedia",
  wiki = "fr")

classification(get_wiki("Malus domestica", "commons"))
classification(get_wiki("Malus domestica", "species"))
classification(c("Pinus contorta", "Malus domestica"), db = "wiki")

# Plug in taxon names
## in this case, we use get_*() fxns internally to first get taxon IDs
classification("Oncorhynchus mykiss", db = "eol")
classification(c("Chironomus riparius", "aaa vva"), db = 'ncbi')
classification(c("Chironomus riparius", "aaa vva"), db = 'ncbi',
  messages=FALSE)
classification(c("Chironomus riparius", "aaa vva"), db = 'itis')
classification(c("Chironomus riparius", "aaa vva"), db = 'itis',
  messages=FALSE)
classification(c("Chironomus riparius", "aaa vva"), db = 'eol')
classification("Alopias vulpinus", db = 'nbn')
classification('Gadus morhua', db = 'worms')
classification('Aquila chrysaetos', db = 'natserv')
classification('Gadus morhua', db = 'natserv')
classification('Pomatomus saltatrix', db = 'natserv')
classification('Aquila chrysaetos', db = 'natserv')
classification(c("Chironomus riparius", "asdfasdfsfdfsd"), db = 'gbif')
classification("Chironomus", db = 'tol')
classification("Poa annua", db = 'tropicos')

# Use methods for get_uid, get_tsn, get_eolid, get_tpsid
classification(get_uid(c("Chironomus riparius", "Puma concolor")))

classification(get_uid(c("Chironomus riparius", "aaa vva")))
classification(get_tsn(c("Chironomus riparius", "aaa vva")))
classification(get_tsn(c("Chironomus riparius", "aaa vva"),
  messages = FALSE))
classification(get_eolid(c("Chironomus riparius", "aaa vva")))
classification(get_tpsid(c("Poa annua", "aaa vva")))
classification(get_gbifid(c("Poa annua", "Bison bison")))

# Pass many ids from class "ids"
(out <- get_ids("Puma concolor", db = c('ncbi','gbif')))
(cl <- classification(out))

# Bind width-wise from class classification_ids
cbind(cl)

# Bind length-wise
rbind(cl)

# Many names to get_ids
(out <- get_ids(c("Puma concolor","Accipiter striatus"),
  db = c('ncbi','itis')))
(cl <- classification(out))
rbind(cl)
## cbind with so many names results in some messy data
cbind(cl)
## so you can turn off return_id
cbind( classification(out, return_id=FALSE) )

(cl_uid <- classification(get_uid(c("Puma concolor",
  "Accipiter striatus")), return_id=FALSE))
rbind(cl_uid)
cbind(cl_uid)
## cbind works a bit odd when there are lots of ranks without names
(cl_uid <- classification(get_uid(c("Puma concolor","Accipiter striatus")),
  return_id=TRUE))
cbind(cl_uid)

(cl_tsn <- classification(get_tsn(c("Puma concolor","Accipiter striatus"))))
rbind(cl_tsn)
cbind(cl_tsn)

(tsns <- get_tsn(c("Puma concolor","Accipiter striatus")))
(cl_tsns <- classification(tsns))
cbind(cl_tsns)

# NBN data
(res <- classification(c("Alopias vulpinus","Pinus sylvestris"),
  db = 'nbn'))
rbind(res)
cbind(res)

# Return taxonomic IDs
## the return_id parameter is logical, and you can turn it on or off.
## It's TRUE by default
classification(c("Alopias vulpinus","Pinus sylvestris"), db = 'ncbi',
  return_id = TRUE)
classification(c("Alopias vulpinus","Pinus sylvestris"), db = 'ncbi',
  return_id = FALSE)

# Use rows parameter to select certain
classification('Poa annua', db = 'tropicos')
classification('Poa annua', db = 'tropicos', rows=1:4)
classification('Poa annua', db = 'tropicos', rows=1)
classification('Poa annua', db = 'tropicos', rows=6)

# Queries of many IDs are processed in batches for NCBI
ids <- c("13083", "2650392", "1547764", "230054", "353934", "656984", 
"271789", "126272", "184644", "73213", "662816", "1161803", "1239353", 
"59420", "665675", "866969", "1091219", "1431218", "1471898", 
"864321", "251768", "2486276", "2068772", "1825808", "2006532", 
"128287", "1195738", "1084683", "1886461", "508296", "377247", 
"1489665", "329325", "219243", "1176946", "339893", "197933", 
"174510", "1704048", "212897", "154842", "1239280", "260135", 
"405735", "1566412", "2083462", "651348", "983204", "165380", 
"2338856", "2068760", "167262", "34229", "1213340", "478939", 
"1933585", "49951", "1277794", "1671089", "1502538", "362355", 
"746473", "242879", "158219", "313664", "2093188", "1541232", 
"584742", "1331091", "147639", "284492", "75642", "1412882", 
"391782", "1406855", "434506", "2053357", "217315", "1444328", 
"329249", "2294004", "84942", "324458", "538247", "69452", "49170", 
"1993845", "261646", "127633", "228146", "1420004", "1629772", 
"577055", "697062", "231660", "648380", "554953", "746496", "2602969")
result <- classification(ids, db = 'ncbi')

## End(Not run)

## Not run: 
# Fails without db param set
# classification(315576)

## End(Not run)

Description

Get scientific names from common names.

Usage

comm2sci(...)

## Default S3 method:
comm2sci(
  com,
  db = "ncbi",
  itisby = "search",
  simplify = TRUE,
  commnames = NULL,
  ...
)

## S3 method for class 'tsn'
comm2sci(id, db = "ncbi", itisby = "search", simplify = TRUE, ...)

## S3 method for class 'uid'
comm2sci(id, db = "ncbi", itisby = "search", simplify = TRUE, ...)

Arguments

Details

For data sources ITIS and NCBI you can pass in common names directly, and use get_uid() or get_tsn() to get ids first, then pass in to this fxn.

For the other data sources, you can only pass in common names directly.

Value

If simplify=TRUE, a list of scientific names, with list labeled by your input names. If simplify=FALSE, a data.frame with columns that vary by data source. character(0) on no match

Authentication

See taxize-authentication for help on authentication

HTTP version for NCBI requests

We hard code http_version = 2L to use HTTP/1.1 in HTTP requests to the Entrez API. See curl::curl_symbols('CURL_HTTP_VERSION')

Rate limits

In case you run into errors due to your rate limit being exceeded, see taxize_options(), where you can set ncbi_sleep.

Author(s)

Scott Chamberlain

See Also

sci2comm()

Examples

## Not run: 
comm2sci(com='american black bear')
comm2sci(com='american black bear', simplify = FALSE)
comm2sci(com='black bear', db='itis')
comm2sci(com='american black bear', db='itis')
comm2sci(com='annual blue grass', db='tropicos')
comm2sci(com=c('annual blue grass','tree of heaven'), db='tropicos')
comm2sci('blue whale', db = "worms")
comm2sci(c('blue whale', 'dwarf surfclam'), db = "worms")

# ncbi: pass in uid's from get_uid() directly
x <- get_uid("western capercaillie", modifier = "Common Name")
comm2sci(x)
# itis: pass in tsn's from get_tsn() directly
x <- get_tsn(c("Louisiana black bear", "american crow"),
  searchtype = "common")
comm2sci(x)

## End(Not run)

Description

This function uses a while loop to continually collect children taxa down to the taxonomic rank that you specify in the downto parameter. You can get data from ITIS (itis), GBIF (gbif), NCBI (ncbi), WORMS (worms), or BOLD (bold). There is no method exposed by these four services for getting taxa at a specific taxonomic rank, so we do it ourselves here.

Usage

downstream(...)

## Default S3 method:
downstream(
  sci_id,
  db = NULL,
  downto = NULL,
  intermediate = FALSE,
  rows = NA,
  x = NULL,
  ...
)

## S3 method for class 'tsn'
downstream(sci_id, db = NULL, downto = NULL, intermediate = FALSE, ...)

## S3 method for class 'gbifid'
downstream(
  sci_id,
  db = NULL,
  downto = NULL,
  intermediate = FALSE,
  limit = 100,
  start = NULL,
  ...
)

## S3 method for class 'uid'
downstream(sci_id, db = NULL, downto = NULL, intermediate = FALSE, ...)

## S3 method for class 'wormsid'
downstream(sci_id, db = NULL, downto = NULL, intermediate = FALSE, ...)

## S3 method for class 'boldid'
downstream(sci_id, db = NULL, downto = NULL, intermediate = FALSE, ...)

## S3 method for class 'ids'
downstream(sci_id, db = NULL, downto = NULL, intermediate = FALSE, ...)

Arguments

Value

A named list of data.frames with the downstream names of every supplied taxa. You get an NA if there was no match in the database.

Authentication

See taxize-authentication for help on authentication

bold

BEWARE: db="bold" scrapes the BOLD website, so may be unstable. That is, one day it may work, and the next it may fail. Open an issue if you encounter an error: https://github.com/ropensci/taxize/issues

Examples

## Not run: 
# Plug in taxon IDs
downstream(125732, db = 'worms', downto = 'species')
downstream(3451, db = 'bold', downto = 'species')

if (interactive()) {

# Plug in taxon names
downstream("Apis", db = 'ncbi', downto = 'species')
downstream("Apis", db = 'itis', downto = 'species')
downstream("Apis", db = 'bold', downto = 'species')
downstream("Gadus", db = 'worms', downto = 'species')
downstream(c("Apis","Epeoloides"), db = 'itis', downto = 'species')
downstream("Ursus", db = 'gbif', downto = 'species')
downstream(get_gbifid("Ursus"), db = 'gbif', downto = 'species')

# Many taxa
sp <- names_list("genus", 3)
downstream(sp, db = 'itis', downto = 'species')
downstream(sp, db = 'gbif', downto = 'species')

# Both data sources
ids <- get_ids("Apis", db = c('gbif','itis'))
downstream(ids, downto = 'species')
## same result
downstream(get_ids("Apis", db = c('gbif','itis')), downto = 'species')

# Collect intermediate names
## itis
downstream('Bangiophyceae', db="itis", downto="genus")
downstream('Bangiophyceae', db="itis", downto="genus", intermediate=TRUE)
downstream(get_tsn('Bangiophyceae'), downto="genus")
downstream(get_tsn('Bangiophyceae'), downto="genus", intermediate=TRUE)

# Use the rows parameter
## note how in the second function call you don't get the prompt
downstream("Poa", db = 'gbif', downto="species")
downstream("Poa", db = 'gbif', downto="species", rows=1)

# use curl options
res <- downstream("Apis", db = 'gbif', downto = 'species', verbose = TRUE)

# Pagination
# GBIF limits queries to a maximum of 1000 records per request, so if
# there's more than 1000, use the start parameter
# Piper, taxonKey = 3075433
z1 <- downstream(3075433, db = 'gbif', downto = "species", limit=1000)
z2 <- downstream(3075433, db = 'gbif', downto = "species", limit=1000,
  start=1000)
z3 <- downstream(3075433, db = 'gbif', downto = "species", limit=1000,
  start=2000)
z4 <- downstream(3075433, db = 'gbif', downto = "species", limit=1000,
  start=3000)
NROW(rbind(z1[[1]], z2[[1]], z3[[1]], z4[[1]]))
}
## End(Not run)

Description

Given the identifier for a data object, return all metadata about the object

Usage

eol_dataobjects(id, taxonomy = TRUE, language = NULL, ...)

Arguments

Details

It's possible to return JSON or XML with the EOL API. However, this function only returns JSON for now.

Value

A list, optionally with a data.frame if taxonomy=TRUE

Examples

## Not run: 
eol_dataobjects(id = 7561533)

# curl options
eol_dataobjects(id = 7561533, verbose = TRUE)

## End(Not run)

Description

Search for pages in EOL database using a taxonconceptID.

Usage

eol_pages(
  taxonconceptID,
  images_per_page = NULL,
  images_page = NULL,
  videos_per_page = NULL,
  videos_page = NULL,
  sounds_per_page = NULL,
  sounds_page = NULL,
  maps_per_page = NULL,
  maps_page = NULL,
  texts_per_page = NULL,
  texts_page = NULL,
  subjects = "overview",
  licenses = "all",
  details = FALSE,
  common_names = FALSE,
  synonyms = FALSE,
  references = FALSE,
  taxonomy = TRUE,
  vetted = 0,
  cache_ttl = NULL,
  ...
)

Arguments

Details

It's possible to return JSON or XML with the EOL API. However, this function only returns JSON for now.

Value

JSON list object, or data.frame.

Examples

## Not run: 
(pageid <- eol_search('Pomatomus')$pageid[1])
x <- eol_pages(taxonconceptID = pageid)
x
x$scinames

z <- eol_pages(taxonconceptID = pageid, synonyms = TRUE)
z$synonyms

z <- eol_pages(taxonconceptID = pageid, common_names = TRUE)
z$vernacular

## End(Not run)

Description

Search for terms in EOL database.

Usage

eol_search(
  sci,
  page = 1,
  exact = NULL,
  filter_tid = NULL,
  filter_heid = NULL,
  filter_by_string = NULL,
  cache_ttl = NULL,
  terms = NULL,
  ...
)

Arguments

Details

It's possible to return JSON or XML with the EOL API. However, this function only returns JSON for now.

Value

A data frame with four columns:

• pageid: pageid, this is the same as the eolid you can get from get_eolid()

• name: taxonomic name, may or may not contain the taxonomic authority

• link: URL for the taxon in question

• content: a string of semi-colon separated names. it's not clear to us what these represent exactly, but figured why not give it to users in case some may find it useful

Examples

## Not run: 
eol_search(sci='Homo')
eol_search(sci='Salix', verbose = TRUE)
eol_search(sci='Ursus americanus')
eol_search('Pinus contorta')

## End(Not run)

Description

EUBON capabilities

Usage

eubon_capabilities(...)

Arguments

References

https://cybertaxonomy.eu/eu-bon/utis/1.3/doc.html

See Also

Other eubon-methods: eubon_children(), eubon_hierarchy(), eubon_search()

Examples

## Not run: 
eubon_capabilities()

## End(Not run)

Description

EUBON children

Usage

eubon_children(id, providers = NULL, timeout = 0, ...)

Arguments

Value

a data.frame or an empty list if no results found

Note

There is no pagination in this method, so you may or may not be getting all the results for a search. Sorry, out of our control

References

https://cybertaxonomy.eu/eu-bon/utis/1.3/doc.html

See Also

Other eubon-methods: eubon_capabilities(), eubon_hierarchy(), eubon_search()

Examples

## Not run: 
x <- eubon_children(id = "urn:lsid:marinespecies.org:taxname:126141",
  providers = 'worms')
head(x)

## End(Not run)

Description

EUBON hierarchy

Usage

eubon_hierarchy(id, providers = "pesi", timeout = 0, ...)

Arguments

Note

There is no pagination in this method, so you may or may not be getting all the results for a search. Sorry, out of our control

References

https://cybertaxonomy.eu/eu-bon/utis/1.3/doc.html

See Also

Other eubon-methods: eubon_capabilities(), eubon_children(), eubon_search()

Examples

## Not run: 
eubon_hierarchy(id = "urn:lsid:marinespecies.org:taxname:126141", 'worms')
eubon_hierarchy(id = "urn:lsid:marinespecies.org:taxname:274350", 'worms')

## End(Not run)

Description

EUBON taxonomy search

Usage

eubon_search(
  query,
  providers = "pesi",
  searchMode = "scientificNameExact",
  addSynonymy = FALSE,
  addParentTaxon = FALSE,
  timeout = 0,
  dedup = NULL,
  limit = 20,
  page = 1,
  ...
)

Arguments

References

https://cybertaxonomy.eu/eu-bon/utis/1.3/doc.html

See Also

Other eubon-methods: eubon_capabilities(), eubon_children(), eubon_hierarchy()

Examples

## Not run: 
eubon_search("Prionus")
eubon_search("Salmo", "pesi")
eubon_search("Salmo", c("pesi", "worms"))
eubon_search("Salmo", "worms", "scientificNameLike")
eubon_search("Salmo", "worms", "scientificNameLike", limit = 3)
eubon_search("Salmo", "worms", "scientificNameLike", limit = 20, page = 2)
eubon_search("Salmo", "worms", addSynonymy = TRUE)
eubon_search("Salmo", "worms", addParentTaxon = TRUE)

## End(Not run)

Description

Search for taxonomic names in Index Fungorum

Usage

fg_name_search(q, anywhere = TRUE, limit = 10, ...)

fg_author_search(q, anywhere = TRUE, limit = 10, ...)

fg_epithet_search(q, anywhere = TRUE, limit = 10, ...)

fg_name_by_key(key, ...)

fg_name_full_by_lsid(lsid, ...)

fg_all_updated_names(date, ...)

fg_deprecated_names(date, ...)

Arguments

Value

A data.frame, or NULL if no results

References

http://www.indexfungorum.org/, API docs: http://www.indexfungorum.org/ixfwebservice/fungus.asmx

Examples

## Not run: 
# NameSearch
fg_name_search(q = "Gymnopus", limit = 2, verbose = TRUE)
fg_name_search(q = "Gymnopus")

# EpithetSearch
fg_epithet_search(q = "phalloides")

# NameByKey
fg_name_by_key(17703)

# NameFullByKey
fg_name_full_by_lsid("urn:lsid:indexfungorum.org:names:81085")

# AllUpdatedNames
fg_all_updated_names(date = gsub("-", "", Sys.Date() - 2))

# DeprecatedNames
fg_deprecated_names(date=20151001)

# AuthorSearch
fg_author_search(q = "Fayod", limit = 2)

## End(Not run)

Description

Retrieve all taxonomic names downstream in hierarchy for GBIF

Usage

gbif_downstream(
  id,
  downto,
  intermediate = FALSE,
  limit = 100,
  start = NULL,
  key = NULL,
  ...
)

Arguments

Details

Sometimes records don't have a canonicalName entry which is what we look for. In that case we grab the scientificName entry. You can see the type of name colleceted in the column name_type

Value

data.frame of taxonomic information downstream to family from e.g., Order, Class, etc., or if intermediated=TRUE, list of length two, with target taxon rank names, and intermediate names.

Author(s)

Scott Chamberlain

Examples

## Not run: 
## the plant class Bangiophyceae
gbif_downstream(id = 198, downto="genus")
gbif_downstream(id = 198, downto="genus", intermediate=TRUE)

# families downstream from the family Strepsiptera (twisted wing parasites)
gbif_downstream(id = 1227, "family")
## here, intermediate leads to the same result as the target
gbif_downstream(id = 1227, "family", intermediate=TRUE)

if (interactive()) {
# Lepidoptera
gbif_downstream(id = 797, "family")

# get species downstream from the genus Ursus
gbif_downstream(id = 2433406, "species")

# get tribes down from the family Apidae
gbif_downstream(id = 7799978, downto="species")
gbif_downstream(id = 7799978, downto="species", intermediate=TRUE)

# names that don't have canonicalname entries for some results
# Myosotis: key 2925668
key <- 2925668
res <- gbif_downstream(key, downto = "species")
res2 <- downstream(key, db = "gbif", downto = "species")

# Pagination
# GBIF limits queries to a maximum of 1000 records per request, so if
# there's more than 1000, use the start parameter
# Piper, taxonKey = 3075433
x1 <- gbif_downstream(id = 3075433, downto = "species", limit=1000)
x2 <- gbif_downstream(id = 3075433, downto = "species", limit=1000,
  start=1000)
x3 <- gbif_downstream(id = 3075433, downto = "species", limit=1000,
  start=2000)
x4 <- gbif_downstream(id = 3075433, downto = "species", limit=1000,
  start=3000)
rbind(x1, x2, x3, x4)
}

## End(Not run)

Description

This is a taxize version of the same function in the rgbif package so as to not have to import rgbif and thus require GDAL binary installation.

Usage

gbif_name_usage(
  key = NULL,
  name = NULL,
  data = "all",
  language = NULL,
  datasetKey = NULL,
  uuid = NULL,
  sourceId = NULL,
  rank = NULL,
  shortname = NULL,
  start = NULL,
  limit = 20,
  ...
)

Arguments

Value

A list of length two. The first element is metadata. The second is either a data.frame (verbose=FALSE, default) or a list (verbose=TRUE)

References

https://www.gbif.org/developer/summary

Description

Parse taxon names using the GBIF name parser.

Usage

gbif_parse(scientificname, ...)

Arguments

Value

A data.frame containing fields extracted from parsed taxon names. Fields returned are the union of fields extracted from all species names in scientificname.

Author(s)

John Baumgartner [email protected]

References

https://www.gbif.org/tools/name-parser/about

See Also

gni_parse(), gna_parse()

Examples

## Not run: 
gbif_parse(scientificname='x Agropogon littoralis')
gbif_parse(c('Arrhenatherum elatius var. elatius',
             'Secale cereale subsp. cereale', 'Secale cereale ssp. cereale',
             'Vanessa atalanta (Linnaeus, 1758)'))

## End(Not run)

Description

Get NCBI taxonomy UID from GenBankID

Usage

genbank2uid(id, batch_size = 100, key = NULL, ...)

Arguments

Details

See https://www.ncbi.nlm.nih.gov/Sitemap/sequenceIDs.html for help on why there are two identifiers, and the difference between them.

Value

one or more NCBI taxonomic IDs

Authentication

See taxize-authentication for help on authentication. We recommend getting an API key.

HTTP version

We hard code http_version = 2L to use HTTP/1.1 in HTTP requests to the Entrez API. See curl::curl_symbols('CURL_HTTP_VERSION')

Rate limits

In case you run into errors due to your rate limit being exceeded, see taxize_options(), where you can set ncbi_sleep.

Examples

## Not run: 
# with accession numbers
genbank2uid(id = 'AJ748748')
genbank2uid(id = 'Y13155')
genbank2uid(id = 'X78312')
genbank2uid(id = 'KM495596')

# with gi numbers
genbank2uid(id = 62689767)
genbank2uid(id = 22775511)
genbank2uid(id = 156446673)

# pass in many accession or gi numbers
genbank2uid(c(62689767,156446673))
genbank2uid(c('X78312','KM495596'))
genbank2uid(list('X78312',156446673))

# curl options
res <- genbank2uid(id = 156446673, verbose = TRUE)

## End(Not run)

Description

Get the BOLD (Barcode of Life) code for a search term.

Usage

get_boldid(
  sci,
  fuzzy = FALSE,
  dataTypes = "basic",
  includeTree = FALSE,
  ask = TRUE,
  messages = TRUE,
  rows = NA,
  rank = NULL,
  division = NULL,
  parent = NULL,
  searchterm = NULL,
  ...
)

as.boldid(x, check = TRUE)

## S3 method for class 'boldid'
as.boldid(x, check = TRUE)

## S3 method for class 'character'
as.boldid(x, check = TRUE)

## S3 method for class 'list'
as.boldid(x, check = TRUE)

## S3 method for class 'numeric'
as.boldid(x, check = TRUE)

## S3 method for class 'data.frame'
as.boldid(x, check = TRUE)

## S3 method for class 'boldid'
as.data.frame(x, ...)

get_boldid_(
  sci,
  messages = TRUE,
  fuzzy = FALSE,
  dataTypes = "basic",
  includeTree = FALSE,
  rows = NA,
  searchterm = NULL,
  ...
)

Arguments

Value

A vector of taxonomic identifiers as an S3 class. If a taxon is not found an NA is given. If more than one identifier is found the function asks for user input if ask = TRUE, otherwise returns NA. If ask=FALSE and rows does not equal NA, then a data.frame is given back, but not of the uid class, which you can't pass on to other functions as you normally can.

See get_id_details for further details including attributes and exceptions

Filtering

The parameters division, parent, and rank are not used in the search to the data provider, but are used in filtering the data down to a subset that is closer to the target you want. For all these parameters, you can use regex strings since we use grep() internally to match. Filtering narrows down to the set that matches your query, and removes the rest.

See Also

classification()

Other taxonomic-ids: get_eolid(), get_gbifid(), get_ids(), get_iucn(), get_natservid(), get_nbnid(), get_pow(), get_tolid(), get_tpsid(), get_tsn(), get_uid(), get_wiki(), get_wormsid()

Examples

## Not run: 
get_boldid(sci = "Agapostemon")
get_boldid(sci = "Chironomus riparius")
get_boldid(c("Chironomus riparius","Quercus douglasii"))
splist <- names_list('species')
get_boldid(splist, messages=FALSE)

# Fuzzy searching
get_boldid(sci="Osmi", fuzzy=TRUE)

# Get back a subset
get_boldid(sci="Osmi", fuzzy=TRUE, rows = 1)
get_boldid(sci="Osmi", fuzzy=TRUE, rows = 1:10)
get_boldid(sci=c("Osmi","Aga"), fuzzy=TRUE, rows = 1)
get_boldid(sci=c("Osmi","Aga"), fuzzy=TRUE, rows = 1:3)

# found
get_boldid('Epicordulia princeps')
get_boldid('Arigomphus furcifer')

# When not found
get_boldid("howdy")
get_boldid(c("Chironomus riparius", "howdy"))
get_boldid("Cordulegaster erronea")
get_boldid("Nasiaeshna pentacantha")

# Narrow down results to a division or rank, or both
## Satyrium example
### Results w/o narrowing
get_boldid("Satyrium")
### w/ phylum
get_boldid("Satyrium", division = "Plantae")
get_boldid("Satyrium", division = "Animalia")

## Rank example
get_boldid("Osmia", fuzzy = TRUE)
get_boldid("Osmia", fuzzy = TRUE, rank = "genus")

# Fuzzy filter on any filtering fields
## uses grep on the inside
get_boldid("Satyrium", division = "anim")
get_boldid("Aga", fuzzy = TRUE, parent = "*idae")

# Convert a boldid without class information to a boldid class
as.boldid(get_boldid("Agapostemon")) # already a boldid, returns the same
as.boldid(get_boldid(c("Agapostemon","Quercus douglasii"))) # same
as.boldid(1973) # numeric
as.boldid(c(1973,101009,98597)) # numeric vector, length > 1
as.boldid("1973") # character
as.boldid(c("1973","101009","98597")) # character vector, length > 1
as.boldid(list("1973","101009","98597")) # list, either numeric or character
## dont check, much faster
as.boldid("1973", check=FALSE)
as.boldid(1973, check=FALSE)
as.boldid(c("1973","101009","98597"), check=FALSE)
as.boldid(list("1973","101009","98597"), check=FALSE)

(out <- as.boldid(c(1973,101009,98597)))
data.frame(out)
as.boldid( data.frame(out) )

# Get all data back
get_boldid_("Osmia", fuzzy=TRUE, rows=1:5)
get_boldid_("Osmia", fuzzy=TRUE, rows=1)
get_boldid_(c("Osmi","Aga"), fuzzy=TRUE, rows = 1:3)

## End(Not run)

Description

Note that EOL doesn't expose an API endpoint for directly querying for EOL taxon ID's, so we first use the function eol_search() to find pages that deal with the species of interest, then use eol_pages() to find the actual taxon IDs.

Usage

get_eolid(
  sci_com,
  ask = TRUE,
  messages = TRUE,
  rows = NA,
  rank = NULL,
  data_source = NULL,
  sciname = NULL,
  ...
)

as.eolid(x, check = TRUE)

## S3 method for class 'eolid'
as.eolid(x, check = TRUE)

## S3 method for class 'character'
as.eolid(x, check = TRUE)

## S3 method for class 'list'
as.eolid(x, check = TRUE)

## S3 method for class 'numeric'
as.eolid(x, check = TRUE)

## S3 method for class 'data.frame'
as.eolid(x, check = TRUE)

## S3 method for class 'eolid'
as.data.frame(x, ...)

get_eolid_(sci_com, messages = TRUE, rows = NA, sciname = NULL, ...)

Arguments

Details

EOL is a bit odd in that they have page IDs for each taxon, but then within that, they have taxon ids for various taxa within that page (e.g., GBIF and NCBI each have a taxon they refer to within the page [i.e., taxon]). And we need the taxon ids from a particular data provider (e.g, NCBI) to do other things, like get a higher classification tree. However, humans want the page id, not the taxon id. So, the id returned from this function is the taxon id, not the page id. You can get the page id for a taxon by using eol_search() and 'eol_pages(), and the URI returned in the attributes for a taxon will lead you to the taxon page, and the ID in the URL is the page id.

Value

A vector of taxonomic identifiers as an S3 class. If a taxon is not found an NA is given. If more than one identifier is found the function asks for user input if ask = TRUE, otherwise returns NA. If ask=FALSE and rows does not equal NA, then a data.frame is given back, but not of the uid class, which you can't pass on to other functions as you normally can.

See get_id_details for further details including attributes and exceptions

Filtering

The parameters rank and data_source are not used in the search to the data provider, but are used in filtering the data down to a subset that is closer to the target you want. For all these parameters, you can use regex strings since we use grep() internally to match. Filtering narrows down to the set that matches your query, and removes the rest.

Author(s)

Scott Chamberlain

See Also

classification()

Other taxonomic-ids: get_boldid(), get_gbifid(), get_ids(), get_iucn(), get_natservid(), get_nbnid(), get_pow(), get_tolid(), get_tpsid(), get_tsn(), get_uid(), get_wiki(), get_wormsid()

Examples

## Not run: 
get_eolid(sci_com='Pinus contorta')
get_eolid(sci_com='Puma concolor')

get_eolid(c("Puma concolor", "Pinus contorta"))

# specify rows to limit choices available
get_eolid('Poa annua')
get_eolid('Poa annua', rows=1)
get_eolid('Poa annua', rows=2)
get_eolid('Poa annua', rows=1:2)

# When not found
get_eolid(sci_com="uaudnadndj")
get_eolid(c("Chironomus riparius", "uaudnadndj"))

# filter results to a rank or data source, or both
get_eolid("Satyrium")
get_eolid("Satyrium", rank = "genus")
get_eolid("Satyrium", data_source = "INAT")
get_eolid("Satyrium", rank = "genus",
  data_source = "North Pacific Species List")

# Convert a eolid without class information to a eolid class
# already a eolid, returns the same
as.eolid(get_eolid("Chironomus riparius"))
# same
as.eolid(get_eolid(c("Chironomus riparius","Pinus contorta")))
# numeric
as.eolid(10247706)
# numeric vector, length > 1
as.eolid(c(6985636,12188704,10247706))
# character
as.eolid("6985636")
# character vector, length > 1
as.eolid(c("6985636","12188704","10247706"))
# list, either numeric or character
as.eolid(list("6985636","12188704","10247706"))
## dont check, much faster
as.eolid("6985636", check=FALSE)
as.eolid(6985636, check=FALSE)
as.eolid(c("6985636","12188704","10247706"), check=FALSE)
as.eolid(list("6985636","12188704","10247706"), check=FALSE)

(out <- as.eolid(c(6985636,12188704,10247706)))
data.frame(out)
as.eolid( data.frame(out) )

# Get all data back
get_eolid_("Poa annua")
get_eolid_("Poa annua", rows=2)
get_eolid_("Poa annua", rows=1:2)
get_eolid_(c("asdfadfasd", "Pinus contorta"))

## End(Not run)

Description

Get the GBIF backbone taxon ID from taxonomic names.

Usage

get_gbifid(
  sci,
  ask = TRUE,
  messages = TRUE,
  rows = NA,
  phylum = NULL,
  class = NULL,
  order = NULL,
  family = NULL,
  rank = NULL,
  method = "backbone",
  sciname = NULL,
  ...
)

as.gbifid(x, check = FALSE)

## S3 method for class 'gbifid'
as.gbifid(x, check = FALSE)

## S3 method for class 'character'
as.gbifid(x, check = TRUE)

## S3 method for class 'list'
as.gbifid(x, check = TRUE)

## S3 method for class 'numeric'
as.gbifid(x, check = TRUE)

## S3 method for class 'data.frame'
as.gbifid(x, check = TRUE)

## S3 method for class 'gbifid'
as.data.frame(x, ...)

get_gbifid_(
  sci,
  messages = TRUE,
  rows = NA,
  method = "backbone",
  sciname = NULL
)

Arguments

Details

Internally in this function we use a function to search GBIF's taxonomy, and if we find an exact match we return the ID for that match. If there isn't an exact match we return the options to you to pick from.

Value

A vector of taxonomic identifiers as an S3 class. If a taxon is not found an NA is given. If more than one identifier is found the function asks for user input if ask = TRUE, otherwise returns NA. If ask=FALSE and rows does not equal NA, then a data.frame is given back, but not of the uid class, which you can't pass on to other functions as you normally can.

See get_id_details for further details including attributes and exceptions

method parameter

"backbone" uses the ⁠/species/match⁠ GBIF API route, matching against their backbone taxonomy. We turn on fuzzy matching by default, as the search without fuzzy against backbone is quite narrow. "lookup" uses the ⁠/species/search⁠ GBIF API route, doing a full text search of name usages covering scientific and vernacular named, species descriptions, distributions and the entire classification.

Filtering

The parameters phylum, class, order, family, and rank are not used in the search to the data provider, but are used in filtering the data down to a subset that is closer to the target you want. For all these parameters, you can use regex strings since we use grep() internally to match. Filtering narrows down to the set that matches your query, and removes the rest.

Author(s)

Scott Chamberlain,

See Also

classification()

Other taxonomic-ids: get_boldid(), get_eolid(), get_ids(), get_iucn(), get_natservid(), get_nbnid(), get_pow(), get_tolid(), get_tpsid(), get_tsn(), get_uid(), get_wiki(), get_wormsid()

Examples

## Not run: 
get_gbifid(sci='Poa annua')
get_gbifid(sci='Pinus contorta')
get_gbifid(sci='Puma concolor')

#lots of queries
spp <- names_list("species", 10)
res <- get_gbifid(spp)
res
xx <- taxon_last()
xx

# multiple names
get_gbifid(c("Poa annua", "Pinus contorta"))

# specify rows to limit choices available
get_gbifid(sci='Pinus')
get_gbifid(sci='Pinus', rows=10)
get_gbifid(sci='Pinus', rows=1:3)

# When not found, NA given
get_gbifid(sci="uaudnadndj")
get_gbifid(c("Chironomus riparius", "uaudnadndj"))

# Narrow down results to a division or rank, or both
## Satyrium example
### Results w/o narrowing
get_gbifid("Satyrium")
### w/ phylum
get_gbifid("Satyrium", phylum = "Tracheophyta")
get_gbifid("Satyrium", phylum = "Arthropoda")
### w/ phylum & rank
get_gbifid("Satyrium", phylum = "Arthropoda", rank = "genus")

## Rank example
get_gbifid("Poa", method = "lookup")
get_gbifid("Poa", method = "lookup", rank = "genus")
get_gbifid("Poa", method = "lookup", family = "Thripidae")

# Fuzzy filter on any filtering fields
## uses grep on the inside
get_gbifid("Satyrium", phylum = "arthropoda")
get_gbifid("A*", method = "lookup", order = "*tera")
get_gbifid("A*", method = "lookup", order = "*ales")

# Convert a uid without class information to a uid class
as.gbifid(get_gbifid("Poa annua")) # already a uid, returns the same
as.gbifid(get_gbifid(c("Poa annua","Puma concolor"))) # same
as.gbifid(2704179) # numeric
as.gbifid(c(2704179,2435099,3171445)) # numeric vector, length > 1
as.gbifid("2704179") # character
as.gbifid(c("2704179","2435099","3171445")) # character vector, length > 1
as.gbifid(list("2704179","2435099","3171445")) # list, either numeric or character
## dont check, much faster
as.gbifid("2704179", check=FALSE)
as.gbifid(2704179, check=FALSE)
as.gbifid(2704179, check=FALSE)
as.gbifid(c("2704179","2435099","3171445"), check=FALSE)
as.gbifid(list("2704179","2435099","3171445"), check=FALSE)

(out <- as.gbifid(c(2704179,2435099,3171445)))
data.frame(out)
as.uid( data.frame(out) )

# Get all data back
get_gbifid_("Puma concolor")
get_gbifid_(c("Pinus", "uaudnadndj"))
get_gbifid_(c("Pinus", "Puma"), rows=5)
get_gbifid_(c("Pinus", "Puma"), rows=1:5)

# use curl options
invisible(get_gbifid("Quercus douglasii", verbose = TRUE))

## End(Not run)

Description

Including outputs from ⁠get_*()⁠ functions, as well as their attributes, and all exception behaviors.

Details

This document applies to the following functions:

• get_boldid()

• get_eolid()

• get_gbifid()

• get_ids()

• get_iucn()

• get_natservid()

• get_nbnid()

• get_tolid()

• get_tpsid()

• get_tsn()

• get_ubioid()

• get_uid()

• get_wiki()

• get_wormsid()

attributes

Each output from ⁠get_*()⁠ functions have the following attributes:

• match (character) - the reason for NA, either 'not found', 'found' or if ask = FALSE then 'NA due to ask=FALSE')

• multiple_matches (logical) - Whether multiple matches were returned by the data source. This can be TRUE, even if you get 1 name back because we try to pattern match the name to see if there's any direct matches. So sometimes this attribute is TRUE, as well as pattern_match, which then returns 1 resulting name without user prompt.

• pattern_match (logical) - Whether a pattern match was made. If TRUE thenmultiple_matches must be TRUE, and we found a perfect match to your name, ignoring case. If FALSE, there wasn't a direct match, and likely you need to pick from many choices or further parameters can be used to limit results

• uri (character) - The URI where more information can be read on the taxon

• includes the taxonomic identifier in the URL somewhere. This may be missing if the value returned is NA

exceptions

The following are the various ways in which ⁠get_*()⁠ functions behave:

• success - the value returned is a character string or numeric

• no matches found - you'll get an NA, refine your search or possible the taxon searched for does not exist in the database you're using

• more than on match and ask = FALSE - if there's more than one matching result, and you have set ask = FALSE, then we can't determine the single match to return, so we give back NA. However, in this case we do set the match attribute to say ⁠NA due to ask=FALSE & > 1 result⁠ so it's very clear what happened - and you can even programatically check this as well

• NA due to some other reason - some ⁠get_*()⁠ functions have additional parameters for filtering taxa. It's possible that even though there's results (that is, found will say TRUE), you can get back an NA. This is most likely if the parameter filters taxa after they are returned from the data provider and the value passed to the parameter leads to no matches.

Description

This is a convenience function to get identifiers across all data sources. You can use other ⁠get_*⁠ functions to get identifiers from specific sources if you like.

Usage

get_ids(
  sci_com,
  db = c("itis", "ncbi", "eol", "tropicos", "gbif", "nbn", "pow"),
  suppress = FALSE,
  names = NULL,
  ...
)

get_ids_(
  sci_com,
  db = get_ids_dbs,
  rows = NA,
  suppress = FALSE,
  names = NULL,
  ...
)

Arguments

Value

A vector of taxonomic identifiers, each retaining their respective S3 classes so that each element can be passed on to another function (see e.g.'s).

Authentication

See taxize-authentication for help on authentication

Note

There is a timeout of 1/3 seconds between queries to NCBI.

See Also

classification()

Other taxonomic-ids: get_boldid(), get_eolid(), get_gbifid(), get_iucn(), get_natservid(), get_nbnid(), get_pow(), get_tolid(), get_tpsid(), get_tsn(), get_uid(), get_wiki(), get_wormsid()

Examples

## Not run: 
# Plug in taxon names directly
# specify rows to limit choices available
get_ids("Poa annua", db="eol", rows=1)
get_ids("Poa annua", db="eol", rows=1:2)

## Or you can specify which source you want via the db parameter
get_ids("Chironomus riparius", db = 'ncbi')
get_ids("Salvelinus fontinalis", db = 'nbn')

get_ids(c("Chironomus riparius", "Pinus contorta"), db = 'ncbi')
get_ids("Pinus contorta", db = c('ncbi','eol','tropicos'))
get_ids("ava avvva", db = c('ncbi','eol','tropicos'))

# Pass on to other functions
out <- get_ids("Pinus contorta", db = c('ncbi','eol','tropicos'))
classification(out$ncbi)

# Get all data back
get_ids_(c("Chironomus riparius", "Pinus contorta"), db = 'nbn',
  rows=1:10)
get_ids_(c("Chironomus riparius", "Pinus contorta"), db = c('nbn','gbif'),
  rows=1:10)

# use curl options
get_ids("Agapostemon", db = "ncbi", verbose = TRUE)

## End(Not run)

Description

Get a IUCN Redlist taxon

Usage

get_iucn(sci, messages = TRUE, key = NULL, x = NULL, ...)

as.iucn(x, check = TRUE, key = NULL)

## S3 method for class 'iucn'
as.iucn(x, check = TRUE, key = NULL)

## S3 method for class 'character'
as.iucn(x, check = TRUE, key = NULL)

## S3 method for class 'list'
as.iucn(x, check = TRUE, key = NULL)

## S3 method for class 'numeric'
as.iucn(x, check = TRUE, key = NULL)

## S3 method for class 'data.frame'
as.iucn(x, check = TRUE, key = NULL)

## S3 method for class 'iucn'
as.data.frame(x, ...)

Arguments

Details

There is no underscore method, because there's no real search for IUCN, that is, where you search for a string, and get back a bunch of results due to fuzzy matching. If that exists in the future we'll add an underscore method here.

IUCN ids only work with synonyms() and sci2comm() methods.

Value

A vector of taxonomic identifiers as an S3 class.

Comes with the following attributes:

• match (character) - the reason for NA, either 'not found', 'found' or if ask = FALSE then 'NA due to ask=FALSE')

• name (character) - the taxonomic name, which is needed in synonyms() and sci2comm() methods since they internally use rredlist functions which require the taxonomic name, and not the taxonomic identifier

• ri (character) - The URI where more information can be read on the taxon - includes the taxonomic identifier in the URL somewhere

multiple_matches and pattern_match do not apply here as in other ⁠get_*⁠ methods since there is no IUCN Redlist search, so you either get a match or you do not get a match.

See Also

Other taxonomic-ids: get_boldid(), get_eolid(), get_gbifid(), get_ids(), get_natservid(), get_nbnid(), get_pow(), get_tolid(), get_tpsid(), get_tsn(), get_uid(), get_wiki(), get_wormsid()

Examples

## Not run: 
get_iucn("Branta canadensis")
get_iucn("Branta bernicla")
get_iucn("Panthera uncia")

# as coercion
as.iucn(22732)
as.iucn("22732")
(res <- as.iucn(c(22679946, 22732, 22679935)))
data.frame(res)
as.iucn(data.frame(res))

## End(Not run)

Description

Get NatureServe taxonomic ID for a taxon name

Usage

get_natservid(
  sci_com,
  searchtype = "scientific",
  ask = TRUE,
  messages = TRUE,
  rows = NA,
  query = NULL,
  ...
)

as.natservid(x, check = TRUE)

## S3 method for class 'natservid'
as.natservid(x, check = TRUE)

## S3 method for class 'character'
as.natservid(x, check = TRUE)

## S3 method for class 'list'
as.natservid(x, check = TRUE)

## S3 method for class 'numeric'
as.natservid(x, check = TRUE)

## S3 method for class 'data.frame'
as.natservid(x, check = TRUE)

## S3 method for class 'natservid'
as.data.frame(x, ...)

get_natservid_(
  sci_com,
  searchtype = "scientific",
  messages = TRUE,
  rows = NA,
  query = NULL,
  ...
)

Arguments

Value

A vector of taxonomic identifiers as an S3 class. If a taxon is not found an NA is given. If more than one identifier is found the function asks for user input if ask = TRUE, otherwise returns NA. If ask=FALSE and rows does not equal NA, then a data.frame is given back, but not of the uid class, which you can't pass on to other functions as you normally can.

See get_id_details for further details including attributes and exceptions

Note

Authentication no longer required

See Also

classification()

Other taxonomic-ids: get_boldid(), get_eolid(), get_gbifid(), get_ids(), get_iucn(), get_nbnid(), get_pow(), get_tolid(), get_tpsid(), get_tsn(), get_uid(), get_wiki(), get_wormsid()

Examples

## Not run: 
(x <- get_natservid("Helianthus annuus", verbose = TRUE))
attributes(x)
attr(x, "match")
attr(x, "multiple_matches")
attr(x, "pattern_match")
attr(x, "uri")

get_natservid('Gadus morhua')
get_natservid(c("Helianthus annuus", 'Gadus morhua'))

# specify rows to limit choices available
get_natservid('Ruby Quaker Moth', 'common')
get_natservid('Ruby*', 'common')
get_natservid('Ruby*', 'common', rows=1)
get_natservid('Ruby*', 'common', rows=1:2)

# When not found
get_natservid("howdy")
get_natservid(c('Gadus morhua', "howdy"))

# Convert a natservid without class information to a natservid class
# already a natservid, returns the same
as.natservid(get_natservid('Pomatomus saltatrix'))
# same
as.natservid(get_natservid(c('Gadus morhua', 'Pomatomus saltatrix')))
# character
as.natservid(101905)
# character vector, length > 1
as.natservid(c(101905, 101998))
# list, either numeric or character
as.natservid(list(101905, 101998))
## dont check, much faster
as.natservid(101905, check = FALSE)
as.natservid(c(101905, 101998), check = FALSE)
as.natservid(list(101905, 101998), check = FALSE)

(out <- as.natservid(c(101905, 101998), check = FALSE))
data.frame(out)
as.natservid( data.frame(out) )

# Get all data back
get_natservid_("Helianthus")
get_natservid_("Ruby*", searchtype = "common")
get_natservid_("Ruby*", searchtype = "common", rows=1:3)

## End(Not run)

Description

Get the UK National Biodiversity Network ID from taxonomic names.

Usage

get_nbnid(
  sci_com,
  ask = TRUE,
  messages = TRUE,
  rec_only = FALSE,
  rank = NULL,
  rows = NA,
  name = NULL,
  ...
)

as.nbnid(x, check = TRUE)

## S3 method for class 'nbnid'
as.nbnid(x, check = TRUE)

## S3 method for class 'character'
as.nbnid(x, check = TRUE)

## S3 method for class 'list'
as.nbnid(x, check = TRUE)

## S3 method for class 'data.frame'
as.nbnid(x, check = TRUE)

## S3 method for class 'nbnid'
as.data.frame(x, ...)

get_nbnid_(
  sci_com,
  messages = TRUE,
  rec_only = FALSE,
  rank = NULL,
  rows = NA,
  name = NULL,
  ...
)

Arguments

Value

A vector of taxonomic identifiers as an S3 class. If a taxon is not found an NA is given. If more than one identifier is found the function asks for user input if ask = TRUE, otherwise returns NA. If ask=FALSE and rows does not equal NA, then a data.frame is given back, but not of the uid class, which you can't pass on to other functions as you normally can.

See get_id_details for further details including attributes and exceptions

an object of class nbnid, a light wrapper around a character string that is the taxonomic ID - includes attributes with relavant metadata

Author(s)

Scott Chamberlain,

References

https://api.nbnatlas.org/

See Also

classification()

Other taxonomic-ids: get_boldid(), get_eolid(), get_gbifid(), get_ids(), get_iucn(), get_natservid(), get_pow(), get_tolid(), get_tpsid(), get_tsn(), get_uid(), get_wiki(), get_wormsid()

Other nbn: nbn_classification(), nbn_search(), nbn_synonyms()

Examples

## Not run: 
get_nbnid(sci_com='Poa annua')
get_nbnid(sci_com='Poa annua', rec_only=TRUE)
get_nbnid(sci_com='Poa annua', rank='Species')
get_nbnid(sci_com='Poa annua', rec_only=TRUE, rank='Species')
get_nbnid(sci_com='Pinus contorta')

# The NBN service handles common names too
get_nbnid(sci_com='red-winged blackbird')

# specify rows to limit choices available
get_nbnid('Poa ann')
get_nbnid('Poa ann', rows=1)
get_nbnid('Poa ann', rows=25)
get_nbnid('Poa ann', rows=1:2)

# When not found
get_nbnid(sci_com="uaudnadndj")
get_nbnid(c("Zootoca vivipara", "uaudnadndj"))
get_nbnid(c("Zootoca vivipara","Chironomus riparius", "uaudnadndj"))

# Convert an nbnid without class information to a nbnid class
as.nbnid(get_nbnid("Zootoca vivipara")) # already a nbnid, returns the same
as.nbnid(get_nbnid(c("Zootoca vivipara","Pinus contorta"))) # same
as.nbnid('NHMSYS0001706186') # character
# character vector, length > 1
as.nbnid(c("NHMSYS0001706186","NHMSYS0000494848","NBNSYS0000010867"))
# list
as.nbnid(list("NHMSYS0001706186","NHMSYS0000494848","NBNSYS0000010867"))
## dont check, much faster
as.nbnid('NHMSYS0001706186', check=FALSE)
as.nbnid(list("NHMSYS0001706186","NHMSYS0000494848","NBNSYS0000010867"),
  check=FALSE)

(out <- as.nbnid(c("NHMSYS0001706186","NHMSYS0000494848",
  "NBNSYS0000010867")))
data.frame(out)
as.nbnid( data.frame(out) )

# Get all data back
get_nbnid_("Zootoca vivipara")
get_nbnid_("Poa annua", rows=2)
get_nbnid_("Poa annua", rows=1:2)
get_nbnid_(c("asdfadfasd","Pinus contorta"), rows=1:5)

# use curl options
invisible(get_nbnid("Quercus douglasii", verbose = TRUE))

## End(Not run)

Description

Get Kew's Plants of the World code for a taxon

Usage

get_pow(
  sci_com,
  accepted = FALSE,
  ask = TRUE,
  messages = TRUE,
  rows = NA,
  family_filter = NULL,
  rank_filter = NULL,
  x = NULL,
  ...
)

as.pow(x, check = TRUE)

## S3 method for class 'pow'
as.pow(x, check = TRUE)

## S3 method for class 'character'
as.pow(x, check = TRUE)

## S3 method for class 'list'
as.pow(x, check = TRUE)

## S3 method for class 'data.frame'
as.pow(x, check = TRUE)

## S3 method for class 'pow'
as.data.frame(x, ...)

get_pow_(sci_com, messages = TRUE, rows = NA, x = NULL, ...)

Arguments

Value

A vector of taxonomic identifiers as an S3 class. If a taxon is not found an NA is given. If more than one identifier is found the function asks for user input if ask = TRUE, otherwise returns NA. If ask=FALSE and rows does not equal NA, then a data.frame is given back, but not of the uid class, which you can't pass on to other functions as you normally can.

See get_id_details for further details including attributes and exceptions

Filtering

The parameters family_filter anrank_filterer are not used in the search to the data provider, but are used in filtering the data down to a subset that is closer to the target you want. For these two parameters, you can use regex strings since we use grep() internally to match. Filtering narrows down to the set that matches your query, and removes the rest.

Rate-limits

As of February 2019, KEW was limiting to 5 requests per second. Note that they may change that number in the future.

If you get errors that contain 429 you are hitting the rate limit, and you can get around it by doing requests with Sys.sleep in between requests.

See Also

classification()

Other pow: pow_lookup(), pow_search(), pow_synonyms()

Other taxonomic-ids: get_boldid(), get_eolid(), get_gbifid(), get_ids(), get_iucn(), get_natservid(), get_nbnid(), get_tolid(), get_tpsid(), get_tsn(), get_uid(), get_wiki(), get_wormsid()

Examples

## Not run: 
get_pow(sci_com="Helianthus")
get_pow(c("Helianthus","Quercus douglasii"))

# Get back a subset
get_pow(sci_com="Helianthus", rows = 1)
get_pow(sci_com="Helianthus", rows = 1:10)

# When not found
get_pow("howdy")
get_pow(c("Helianthus annuus", "howdy"))

# Narrow down results 
# to accepted names
get_pow("Helianthus", accepted = TRUE)
# to a kingom 
get_pow("Helianthus", rank_filter = "genus")
# to accepted names and rank
get_pow("Helianthus annuus", accepted = TRUE, rank_filter = "species")
# to a family
get_pow("flower", family_filter = "Acanthaceae")

# Convert a pow without class information to a pow class
z <- get_pow("Helianthus annuus", accepted = TRUE, rank_filter = "species")
# already a pow, returns the same
as.pow(z)
as.pow("urn:lsid:ipni.org:names:119003-2")
# character vector, length > 1
ids <- c("urn:lsid:ipni.org:names:119003-2","urn:lsid:ipni.org:names:328247-2")
as.pow(ids)
# list, with character strings
as.pow(as.list(ids)) 
## dont check, much faster
as.pow("urn:lsid:ipni.org:names:119003-2", check=FALSE)
as.pow(ids, check=FALSE)
as.pow(as.list(ids), check=FALSE)

(out <- as.pow(ids))
data.frame(out)
as.pow( data.frame(out) )

# Get all data back
get_pow_("Quercus", rows=1:5)
get_pow_("Quercus", rows=1)
get_pow_(c("Pinus", "Abies"), rows = 1:3)

## End(Not run)