Span taxa

Select a range of taxa, either by two names, or relational operators

span(.data, ...)

Arguments

.data	Input, object of class Hierarchy, or hierarchies
...	quoted rank names (e.g., family) via ranks(), taxon names (e.g., Poa annua) via nms(), or taxonomic IDs (e.g., 93036) via ids(). You can't pass in arbitrary strings or numbers.

Value

an object of the same class as passed in

Details

supports Hierarchy and hierarchies objects

See also

See filtering-helpers, including for more explanation of how this function works.

Examples

# Hierarchy class
ex_hierarchy1
#> <Hierarchy>
#>   no. taxon's:  3 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 
#>   Poa annua / species / 93036 

## ranks
### keep all taxa between family and genus
span(ex_hierarchy1, ranks("family", "genus"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 
span(ex_hierarchy1, nms("Poaceae", "Poa"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 
span(ex_hierarchy1, ids(4479, 4544))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 

### keep all taxa between genus and species
span(ex_hierarchy1, ranks("genus", "species"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poa / genus / 4544 
#>   Poa annua / species / 93036 

### keep all taxa greater than genus
span(ex_hierarchy1, ranks("> genus"))
#> <Hierarchy>
#>   no. taxon's:  1 
#>   Poaceae / family / 4479 

### keep all taxa greater than or equal to genus
span(ex_hierarchy1, ranks(">= genus"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 

### keep all taxa less than genus
span(ex_hierarchy1, ranks("< genus"))
#> <Hierarchy>
#>   no. taxon's:  1 
#>   Poa annua / species / 93036 

### keep all taxa less than or equal to genus
span(ex_hierarchy1, ranks("<= genus"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poa / genus / 4544 
#>   Poa annua / species / 93036 

### same as above, with different dataset
span(ex_hierarchy2, ranks("> genus"))
#> <Hierarchy>
#>   no. taxon's:  1 
#>   Felidae / family / 9681 
span(ex_hierarchy2, ranks(">= genus"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Felidae / family / 9681 
#>   Puma / genus / 146712 
span(ex_hierarchy2, ranks("< genus"))
#> <Hierarchy>
#>   no. taxon's:  1 
#>   Puma concolor / species / 9696 
span(ex_hierarchy2, ranks("<= genus"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Puma / genus / 146712 
#>   Puma concolor / species / 9696 

# using taxonomic names
span(ex_hierarchy2, nms("< Felidae"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Puma / genus / 146712 
#>   Puma concolor / species / 9696 

# using taxonomic ids
span(ex_hierarchy2, ids("< 9681"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Puma / genus / 146712 
#>   Puma concolor / species / 9696 

## Multiple operator statements - useful with larger classifications
ex_hierarchy3
#> <Hierarchy>
#>   no. taxon's:  6 
#>   Chordata / phylum / 158852 
#>   Vertebrata / subphylum / 331030 
#>   Teleostei / class / 161105 
#>   Salmonidae / family / 161931 
#>   Salmo / genus / 161994 
#>   Salmo salar / species / 161996 
span(ex_hierarchy3, ranks("> genus"), ranks("< phylum"))
#> <Hierarchy>
#>   no. taxon's:  3 
#>   Vertebrata / subphylum / 331030 
#>   Teleostei / class / 161105 
#>   Salmonidae / family / 161931 
span(ex_hierarchy3, ids("> 161994"), ids("< 158852"))
#> <Hierarchy>
#>   no. taxon's:  3 
#>   Vertebrata / subphylum / 331030 
#>   Teleostei / class / 161105 
#>   Salmonidae / family / 161931 


## taxon names
### keep all taxa between Poaceae and Poa
### - matches to ranks first
ex_hierarchy1 %>% span(nms("Poaceae", "Poa"))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 

## taxon ids
### keep all taxa between 4479 and 4544 taxonomic IDs
### - matches to ranks first
ex_hierarchy1 %>% span(ids(4479, 4544))
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 


# hierarchies class
invisible(lapply(ex_hierarchies, print))
#> <Hierarchy>
#>   no. taxon's:  3 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 
#>   Poa annua / species / 93036 
#> <Hierarchy>
#>   no. taxon's:  3 
#>   Felidae / family / 9681 
#>   Puma / genus / 146712 
#>   Puma concolor / species / 9696 
#> <Hierarchy>
#>   no. taxon's:  6 
#>   Chordata / phylum / 158852 
#>   Vertebrata / subphylum / 331030 
#>   Teleostei / class / 161105 
#>   Salmonidae / family / 161931 
#>   Salmo / genus / 161994 
#>   Salmo salar / species / 161996 
ex_hierarchies %>% span(ranks("family", "genus")) %>% lapply(., print) %>%
invisible
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Poaceae / family / 4479 
#>   Poa / genus / 4544 
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Felidae / family / 9681 
#>   Puma / genus / 146712 
#> <Hierarchy>
#>   no. taxon's:  2 
#>   Salmonidae / family / 161931 
#>   Salmo / genus / 161994