R: Get a summary from the IUCN Red List

iucn_summary {taxize} | R Documentation

## Get a summary from the IUCN Red List

### Description

Get a summary from the IUCN Red List (http://www.iucnredlist.org/).

### Usage

    iucn_summary(x, parallel = FALSE, distr_detail = FALSE, key = NULL, ...)

    iucn_summary_id(species_id, silent = TRUE, parallel = FALSE,
      distr_detail = FALSE, ...)

### Arguments

`x` | character; Scientific name. Should be cleaned and in the format <Genus> <Species>.
`parallel` | logical; Search in parallel to speed up search. You have to register a parallel backend if `TRUE`. See e.g., doMC, doSNOW, etc.
`distr_detail` | logical; If `TRUE`, the geographic distribution is returned as a list of vectors corresponding to the different range types: native, introduced, etc.
`key` | a Redlist API key, get one from http://apiv3.iucnredlist.org/api/v3/token Required for `iucn_summary` but not needed for `iucn_summary_id`. Defaults to `NULL` in case you have your key stored (see `Redlist Authentication` below).
`...` | Currently not used.
`species_id` | an IUCN ID
`silent` | logical; Make errors silent or not (when species not found).

### Details

Beware: IUCN functions can give back incorrect data. This isn't our fault. We do our best to get you the correct data quickly, but sometimes IUCN gives back the wrong data, and sometimes Global Names gives back the wrong data. We will fix these as soon as possible. In the meantime, just make sure that the data you get back is correct.

`iucn_summary` has a default method that errors when anything's passed in that's not `character` or `iucn` class - a `iucn_summary.character` method for when you pass in taxon names - and a `iucn_summary.iucn` method so you can pass in iucn class objects as output from `get_iucn` or `as.iucn`. If you already have IUCN IDs, coerce them to `iucn` class via `as.iucn(..., check = FALSE)`

### Value

A list (for every species one entry) of lists with the following items:

`status` | Red List Category.
`history` | History of status, if available.
`distr` | Geographic distribution, if available.
`trend` | Trend of population size, if available.

### Redlist Authentication

`iucn_summary` uses the new Redlist API for searching for a IUCN ID, so we use the `rl_search` function internally. This function requires an API key. Get the key at http://apiv3.iucnredlist.org/api/v3/token, and pass it to the `key` parameter, or store in your `.Renviron` file like `IUCN_REDLIST_KEY=yourkey` or in your `.Rprofile` file like `options(iucn_redlist_key="yourkey"`. We strongly encourage you to not pass the key in the function call but rather store it in one of those two files. This key will also set you up to use the rredlist package.

### Note

Not all entries (history, distr, trend) are available for every species and NA is returned. `iucn_status` is an extractor function to easily extract status into a vector.

### Author(s)

Eduard Szoecs, eduardszoecs@gmail.com

Philippe Marchand, marchand.philippe@gmail.com

Scott Chamberlain, myrmecocystus@gmail.com

### See Also

`iucn_status`

### Examples

    ## Not run:
    # if you send a taxon name, an IUCN API key is required
    ## here, the key is being detected from a .Rprofile file
    ## or .Renviron file, See "Redlist Authentication" above
    iucn_summary("Lutra lutra")

    ia <- iucn_summary(c("Panthera uncia", "Lynx lynx"))
    ia <- iucn_summary(c("Panthera uncia", "Lynx lynx", "aaa"))

    ## get detailed distribution
    iac <- iucn_summary(x="Ara chloropterus", distr_detail = TRUE)
    iac[[1]]$distr

    # If you pass in an IUCN ID, you don't need to pass in a Redlist API Key
    ia <- iucn_summary_id(c(22732, 12519))
    # extract status
    iucn_status(ia)
    # extract other available information
    ia[['Lynx lynx']]$history
    ia[['Panthera uncia']]$distr
    ia[[2]]$trend
    ## the outputs aren't quite identical, but we're working on it
    identical(
      iucn_summary_id(c(22732, 12519)),
      iucn_summary(as.iucn(c(22732, 12519)))
    )

    # using parallel, e.g., with doMC package, register cores first
    # library(doMC)
    # registerDoMC(cores = 2)
    # nms <- c("Panthera uncia", "Lynx lynx", "Ara chloropterus", "Lutra lutra")
    # (res <- iucn_summary(nms, parallel = TRUE))

    ## End(Not run)

[Package taxize version 0.9.0 Index]