R: Retrieve the downstream taxa for a given taxon name or ID.

downstream {taxize} | R Documentation

## Retrieve the downstream taxa for a given taxon name or ID.

### 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), Catalogue of Life (col), GBIF (gbif), or NCBI (ncbi). 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(x, db = NULL, downto = NULL,
      intermediate = FALSE, rows = NA, ...)

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

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

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

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

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

### Arguments

`...` | Further args passed on to `itis_downstream`, `col_downstream`, `gbif_downstream`, or `ncbi_downstream`
`x` | Vector of taxa names (character) or IDs (character or numeric) to query.
`db` | character; database to query. One or more of `itis`, `col`, `gbif`, or `ncbi`. Note that each taxonomic data source has their own identifiers, so that if you provide the wrong `db` value for the identifier you could get a result, but it will likely be wrong (not what you were expecting).
`downto` | What taxonomic rank to go down to. One of: 'superkingdom', 'kingdom', 'subkingdom','infrakingdom','phylum','division','subphylum', 'subdivision','infradivision', 'superclass','class','subclass','infraclass', 'superorder','order','suborder','infraorder','superfamily','family', 'subfamily','tribe','subtribe','genus','subgenus','section','subsection', 'species group','species','subspecies','variety','form','subvariety','race', 'stirp', 'morph','aberration','subform', 'unspecified', 'no rank'
`intermediate` | (logical) If `TRUE`, return a list of length two with target taxon rank names, with additional list of data.frame's of intermediate taxonomic groups. Default: `FALSE`
`rows` | (numeric) Any number from 1 to infinity. If the default NA, all rows are considered. Note that this parameter is ignored if you pass in a taxonomic id of any of the acceptable classes: tsn, colid.

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

### Examples

    ## Not run:
    # Plug in taxon IDs
    ## col Ids have to be character, as they are alphanumeric IDs
    downstream("015be25f6b061ba517f495394b80f108", db = "col",
      downto = "species")
    ## ITIS tsn ids can be numeric or character
    downstream("154395", db = "itis", downto = "species")
    downstream(154395, db = "itis", downto = "species")

    # Plug in taxon names
    downstream("Insecta", db = 'col', downto = 'order')
    downstream("Apis", db = 'col', downto = 'species')
    downstream("Apis", db = 'ncbi', downto = 'species')
    downstream("Apis", db = 'itis', downto = 'species')
    downstream(c("Apis","Epeoloides"), db = 'itis', downto = 'species')
    downstream(c("Apis","Epeoloides"), db = 'col', downto = 'species')
    downstream("Ursus", db = 'gbif', downto = 'species')
    downstream(get_gbifid("Ursus"), db = 'gbif', downto = 'species')

    # Plug in IDs
    id <- get_colid("Apis")
    downstream(id, downto = 'species')

    ## Equivalently, plug in the call to get the id via e.g., get_colid
    ## into downstream
    identical(downstream(id, downto = 'species'),
             downstream(get_colid("Apis"), downto = 'species'))

    id <- get_colid("Apis")
    downstream(id, downto = 'species')
    downstream(get_colid("Apis"), downto = 'species')

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

    # Both data sources
    ids <- get_ids("Apis", db = c('col','itis'))
    downstream(ids, downto = 'species')
    ## same result
    downstream(get_ids("Apis", db = c('col','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)
    ## col
    downstream(get_colid("Animalia"), downto="class")
    downstream(get_colid("Animalia"), downto="class", intermediate=TRUE)

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

    downstream("Poa", db = 'ncbi', downto="species")

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

    ## End(Not run)

[Package taxize version 0.9.0 Index]