metacoder (version 0.3.7)

supertaxa: Get all supertaxa of a taxon

Description

Return data for supertaxa (i.e. all taxa the target taxa are a part of) of each taxon in a [taxonomy()] or [taxmap()] object.

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

Value

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

Arguments

obj

The [taxonomy()] or [taxmap()] object containing taxon information to be queried.

subset

Taxon IDs, TRUE/FALSE vector, or taxon indexes to find supertaxa 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 supertaxa one rank above the target taxa. If `TRUE`, return all the supertaxa of every supertaxa, etc. Positive numbers indicate the number of recursions (i.e. number of ranks above the target taxon to return). `1` is equivalent to `FALSE`. Negative numbers are equivalent to `TRUE`.

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. Any result of [all_names()] can be used, but it usually only makes sense to use data that has an associated taxon id.

na

(`logical`) If `TRUE`, return `NA` where information is not available.

See Also

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

Examples

# return the indexes for supertaxa for each taxon
supertaxa(ex_taxmap)

# Only return data for some taxa using taxon indexes
supertaxa(ex_taxmap, subset = 1:3)

# Only return data for some taxa using taxon ids
supertaxa(ex_taxmap, subset = c("d", "e"))

# Only return data for some taxa using logical tests
supertaxa(ex_taxmap, subset = taxon_ranks == "species")

# Only return supertaxa one level above
supertaxa(ex_taxmap, recursive = FALSE)

# Only return supertaxa some number of ranks above
supertaxa(ex_taxmap, recursive = 2)

# Return something besides taxon indexes
supertaxa(ex_taxmap, value = "taxon_names")