Get subtaxa

Return data for the subtaxa of each taxon in an taxonomy() or taxmap() object.

obj$subtaxa(subset = NULL, recursive = TRUE,
  simplify = FALSE, include_input = FALSE, value = "taxon_indexes")
subtaxa(obj, subset = NULL, recursive = TRUE,
  simplify = FALSE, include_input = FALSE, value = "taxon_indexes")

Arguments

obj	The taxonomy() or taxmap() object containing taxon information to be queried.
subset	Taxon IDs, TRUE/FALSE vector, or taxon indexes to find subtaxa for. Default: All taxa in obj will be used. Any variable name that appears in all_names() can be used as if it was a vector on its own.
recursive	(logical or numeric) If FALSE, only return the subtaxa one rank below the target taxa. If TRUE, return all the subtaxa of every subtaxa, etc. Positive numbers indicate the number of ranks below the immediate subtaxa to return. 1 is equivalent to FALSE. Negative numbers are equivalent to TRUE. Since the algorithm is optimized for traversing all of large trees, numeric values greater than 0 for this option actually take slightly longer to compute than either TRUE or FALSE.
simplify	(logical) If TRUE, then combine all the results into a single vector of unique values.
include_input	(logical) If TRUE, the input taxa are included in the output
value	What data to return. This is usually the name of column in a table in obj$data. Any result of all_names() can be used, but it usually only makes sense to data that corresponds to taxa 1:1, such as taxon_ranks(). By default, taxon indexes are returned.

Value

If simplify = FALSE, then a list of vectors are returned corresponding to the target argument. If simplify = TRUE, then the unique values are returned in a single vector.

See also

Other taxonomy indexing functions: branches(), internodes(), leaves(), roots(), stems(), supertaxa()

Examples

# return the indexes for subtaxa for each taxon
subtaxa(ex_taxmap)
#> $b
#>  d  h  m  i  n  e  j  o  f  k  p 
#>  3  7 12  8 13  4  9 14  5 10 15 
#> 
#> $c
#>  g  l  q  r 
#>  6 11 16 17 
#> 
#> $d
#>  h  m  i  n 
#>  7 12  8 13 
#> 
#> $e
#>  j  o 
#>  9 14 
#> 
#> $f
#>  k  p 
#> 10 15 
#> 
#> $g
#>  l  q  r 
#> 11 16 17 
#> 
#> $h
#>  m 
#> 12 
#> 
#> $i
#>  n 
#> 13 
#> 
#> $j
#>  o 
#> 14 
#> 
#> $k
#>  p 
#> 15 
#> 
#> $l
#>  q  r 
#> 16 17 
#> 
#> $m
#> named integer(0)
#> 
#> $n
#> named integer(0)
#> 
#> $o
#> named integer(0)
#> 
#> $p
#> named integer(0)
#> 
#> $q
#> named integer(0)
#> 
#> $r
#> named integer(0)
#> 

# Only return data for some taxa using taxon indexes
subtaxa(ex_taxmap, subset = 1:3)
#> $b
#>  d  h  m  i  n  e  j  o  f  k  p 
#>  3  7 12  8 13  4  9 14  5 10 15 
#> 
#> $c
#>  g  l  q  r 
#>  6 11 16 17 
#> 
#> $d
#>  h  m  i  n 
#>  7 12  8 13 
#> 

# Only return data for some taxa using taxon ids
subtaxa(ex_taxmap, subset = c("d", "e"))
#> $d
#>  h  m  i  n 
#>  7 12  8 13 
#> 
#> $e
#>  j  o 
#>  9 14 
#> 

# Only return data for some taxa using logical tests
subtaxa(ex_taxmap, subset = taxon_ranks == "genus")
#> $h
#>  m 
#> 12 
#> 
#> $i
#>  n 
#> 13 
#> 
#> $j
#>  o 
#> 14 
#> 
#> $k
#>  p 
#> 15 
#> 
#> $l
#>  q  r 
#> 16 17 
#> 

# Only return subtaxa one level below
subtaxa(ex_taxmap, recursive = FALSE)
#> $b
#> d e f 
#> 3 4 5 
#> 
#> $c
#> g 
#> 6 
#> 
#> $d
#> h i 
#> 7 8 
#> 
#> $e
#> j 
#> 9 
#> 
#> $f
#>  k 
#> 10 
#> 
#> $g
#>  l 
#> 11 
#> 
#> $h
#>  m 
#> 12 
#> 
#> $i
#>  n 
#> 13 
#> 
#> $j
#>  o 
#> 14 
#> 
#> $k
#>  p 
#> 15 
#> 
#> $l
#>  q  r 
#> 16 17 
#> 
#> $m
#> named integer(0)
#> 
#> $n
#> named integer(0)
#> 
#> $o
#> named integer(0)
#> 
#> $p
#> named integer(0)
#> 
#> $q
#> named integer(0)
#> 
#> $r
#> named integer(0)
#> 

# Only return subtaxa some number of ranks below
subtaxa(ex_taxmap, recursive = 2)
#> $b
#>  d  h  i  e  j  f  k 
#>  3  7  8  4  9  5 10 
#> 
#> $c
#>  g  l 
#>  6 11 
#> 
#> $d
#>  h  m  i  n 
#>  7 12  8 13 
#> 
#> $e
#>  j  o 
#>  9 14 
#> 
#> $f
#>  k  p 
#> 10 15 
#> 
#> $g
#>  l  q  r 
#> 11 16 17 
#> 
#> $h
#>  m 
#> 12 
#> 
#> $i
#>  n 
#> 13 
#> 
#> $j
#>  o 
#> 14 
#> 
#> $k
#>  p 
#> 15 
#> 
#> $l
#>  q  r 
#> 16 17 
#> 
#> $m
#> named integer(0)
#> 
#> $n
#> named integer(0)
#> 
#> $o
#> named integer(0)
#> 
#> $p
#> named integer(0)
#> 
#> $q
#> named integer(0)
#> 
#> $r
#> named integer(0)
#> 

# Return something besides taxon indexes
subtaxa(ex_taxmap, value = "taxon_names")
#> $b
#>              d              h              m              i              n 
#>      "Felidae"     "Panthera"       "tigris"        "Felis"        "catus" 
#>              e              j              o              f              k 
#> "Notoryctidae"   "Notoryctes"     "typhlops"    "Hominidae"         "homo" 
#>              p 
#>      "sapiens" 
#> 
#> $c
#>              g              l              q              r 
#>   "Solanaceae"      "Solanum" "lycopersicum"    "tuberosum" 
#> 
#> $d
#>          h          m          i          n 
#> "Panthera"   "tigris"    "Felis"    "catus" 
#> 
#> $e
#>            j            o 
#> "Notoryctes"   "typhlops" 
#> 
#> $f
#>         k         p 
#>    "homo" "sapiens" 
#> 
#> $g
#>              l              q              r 
#>      "Solanum" "lycopersicum"    "tuberosum" 
#> 
#> $h
#>        m 
#> "tigris" 
#> 
#> $i
#>       n 
#> "catus" 
#> 
#> $j
#>          o 
#> "typhlops" 
#> 
#> $k
#>         p 
#> "sapiens" 
#> 
#> $l
#>              q              r 
#> "lycopersicum"    "tuberosum" 
#> 
#> $m
#> named character(0)
#> 
#> $n
#> named character(0)
#> 
#> $o
#> named character(0)
#> 
#> $p
#> named character(0)
#> 
#> $q
#> named character(0)
#> 
#> $r
#> named character(0)
#>