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

upstream {taxize} | R Documentation

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

### Description

This function uses a while loop to continually collect taxa up to the taxonomic rank that you specify in the `upto` parameter. You can get data from ITIS (itis) or Catalogue of Life (col). There is no method exposed by itis or col for getting taxa at a specific taxonomic rank, so we do it ourselves inside the function.

### Usage

    upstream(...)

    ## Default S3 method:
    upstream(x, db = NULL, upto = NULL, rows = NA, ...)

    ## S3 method for class 'tsn'
    upstream(x, db = NULL, upto = NULL, ...)

    ## S3 method for class 'colid'
    upstream(x, db = NULL, upto = NULL, ...)

    ## S3 method for class 'ids'
    upstream(x, db = NULL, upto = NULL, ...)

### Arguments

`...` | Further args passed on to `itis_downstream` or `col_downstream`
`x` | Vector of taxa names (character) or IDs (character or numeric) to query.
`db` | character; database to query. One or both of `itis`, `col`. 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).
`upto` | 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','subspecies','variety','form','subvariety','race', 'stirp', 'morph','aberration','subform', or 'unspecified'
`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 upstream names of every supplied taxa. You get an NA if there was no match in the database.

### Examples

    ## Not run:
    ## col
    ### get all genera at one level up
    upstream("Pinus contorta", db = 'col', upto = 'genus')
    ### goes to same level, Abies is a genus
    upstream("Abies", db = 'col', upto = 'genus')
    upstream('Pinus contorta', db = 'col', upto = 'family')
    upstream('Poa annua', db = 'col', upto = 'family')
    upstream('Poa annua', db = 'col', upto = 'order')

    ## itis
    upstream(x='Pinus contorta', db = 'itis', upto = 'genus')

    ## both
    upstream(get_ids('Pinus contorta', db = c('col','itis')), upto = 'genus')

    # Use rows parameter to select certain
    upstream('Poa annua', db = 'col', upto = 'genus')
    upstream('Poa annua', db = 'col', upto = 'genus', rows=1)

    # use curl options
    res <- upstream('Poa annua', db = 'col', upto = 'genus', config=verbose())

    ## End(Not run)

[Package taxize version 0.9.0 Index]