R: Get NatureServe taxonomic ID for a taxon name

get_natservid {taxize} | R Documentation

## Get NatureServe taxonomic ID for a taxon name

### Description

Get NatureServe taxonomic ID for a taxon name

### Usage

    get_natservid(query, searchtype = "scientific", ask = TRUE,
      verbose = TRUE, rows = NA, key = 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_(query, verbose = TRUE, rows = NA, key = NULL, ...)

### Arguments

`query` | character; A vector of common or scientific names.
`searchtype` | character; One of 'scientific' (default) or 'common'. This doesn't affect the query to NatureServe - but rather affects what column of data is targeted in name filtering post data request.
`ask` | logical; should get_natservid be run in interactive mode? If `TRUE` and more than one wormsid is found for the species, the user is asked for input. If `FALSE` NA is returned for multiple matches.
`verbose` | logical; should progress be printed?
`rows` | numeric; Any number from 1 to infinity. If the default NaN, all rows are considered. Note that this function still only gives back a natservid class object with one to many identifiers. See `get_natservid_` to get back all, or a subset, of the raw data that you are presented during the ask process.
`key` | (character) your NatureServe API key. Required. See Authentication below for more.
`...` | Ignored
`x` | Input to as.natservid
`check` | logical; Check if ID matches any existing on the DB, only used in `as.natservid`

### 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

### Authentication

Get an API key from NatureServe at https://services.natureserve.org/developer/index.jsp. You can pass your token in as an argument or store it one of two places:

- your .Rprofile file with an entry like `options(NatureServeKey = "your-natureserve-key")`

- your .Renviron file with an entry like `NATURE_SERVE_KEY=your-natureserve-key`

See `Startup` for information on how to create/find your .Rprofile and .Renviron files

### See Also

`classification`

Other taxonomic-ids: `get_boldid`, `get_colid`, `get_eolid`, `get_gbifid`, `get_ids`, `get_iucn`, `get_nbnid`, `get_tolid`, `get_tpsid`, `get_tsn`, `get_uid`, `get_wiki`, `get_wormsid`

### Examples

    ## Not run:
    (x <- get_natservid("Helianthus annuus"))
    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('Gadus morhua'))
    # same
    as.natservid(get_natservid(c('Gadus morhua', 'Pomatomus saltatrix')))
    # character
    as.natservid("ELEMENT_GLOBAL.2.101905")
    # character vector, length > 1
    as.natservid(c("ELEMENT_GLOBAL.2.101905", "ELEMENT_GLOBAL.2.101998"))
    # list, either numeric or character
    as.natservid(list("ELEMENT_GLOBAL.2.101905", "ELEMENT_GLOBAL.2.101998"))
    ## dont check, much faster
    as.natservid("ELEMENT_GLOBAL.2.101905", check = FALSE)
    as.natservid(c("ELEMENT_GLOBAL.2.101905", "ELEMENT_GLOBAL.2.101998"),
      check = FALSE)
    as.natservid(list("ELEMENT_GLOBAL.2.101905", "ELEMENT_GLOBAL.2.101998"),
      check = FALSE)

    (out <- as.natservid(
      c("ELEMENT_GLOBAL.2.101905", "ELEMENT_GLOBAL.2.101998")))
    data.frame(out)
    as.natservid( data.frame(out) )

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

    ## End(Not run)

[Package taxize version 0.9.0 Index]