Given a taxmap() object, return data associated with each taxon in a given table included in that taxmap() object.

obj$obs(data, value = NULL, subset = NULL,
  recursive = TRUE, simplify = FALSE)
obs(obj, data, value = NULL, subset = NULL,
  recursive = TRUE, simplify = FALSE)

Arguments

obj

(taxmap()) The taxmap() object containing taxon information to be queried.

data

Either the name of something in obj$data that has taxon information or a an external object with taxon information. For tables, there must be a column named "taxon_id" and lists/vectors must be named by taxon ID.

value

What data to return. This is usually the name of column in a table in obj$data. Any result of all_names(obj) can be used. If the value used has names, it is assumed that the names are taxon ids and the taxon ids are used to look up the correct values.

subset

Taxon IDs, TRUE/FALSE vector, or taxon indexes to find observations 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 observation assigned to the specified input taxa, not subtaxa. If TRUE, return all the observations of every subtaxa, etc. Positive numbers indicate the number of ranks below the each taxon to get observations for 0 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 observation indexes.

Value

If simplify = FALSE, then a list of vectors of observation indexes are returned corresponding to the data argument. If simplify = TRUE, then the observation indexes for all data taxa are returned in a single vector.

Examples

# Get indexes of rows corresponding to each taxon obs(ex_taxmap, "info")
#> $b #> [1] 1 2 3 4 #> #> $c #> [1] 5 6 #> #> $d #> [1] 1 2 #> #> $e #> [1] 3 #> #> $f #> [1] 4 #> #> $g #> [1] 5 6 #> #> $h #> [1] 1 #> #> $i #> [1] 2 #> #> $j #> [1] 3 #> #> $k #> [1] 4 #> #> $l #> [1] 5 6 #> #> $m #> [1] 1 #> #> $n #> [1] 2 #> #> $o #> [1] 3 #> #> $p #> [1] 4 #> #> $q #> [1] 5 #> #> $r #> [1] 6 #>
# Get only a subset of taxon indexes obs(ex_taxmap, "info", subset = 1:2)
#> $b #> [1] 1 2 3 4 #> #> $c #> [1] 5 6 #>
# Get only a subset of taxon IDs obs(ex_taxmap, "info", subset = c("b", "c"))
#> $b #> [1] 1 2 3 4 #> #> $c #> [1] 5 6 #>
# Get only a subset of taxa using logical tests obs(ex_taxmap, "info", subset = taxon_ranks == "genus")
#> $h #> [1] 1 #> #> $i #> [1] 2 #> #> $j #> [1] 3 #> #> $k #> [1] 4 #> #> $l #> [1] 5 6 #>
# Only return indexes of rows assinged to each taxon explicitly obs(ex_taxmap, "info", recursive = FALSE)
#> $b #> numeric(0) #> #> $c #> numeric(0) #> #> $d #> numeric(0) #> #> $e #> numeric(0) #> #> $f #> numeric(0) #> #> $g #> numeric(0) #> #> $h #> numeric(0) #> #> $i #> numeric(0) #> #> $j #> numeric(0) #> #> $k #> numeric(0) #> #> $l #> numeric(0) #> #> $m #> [1] 1 #> #> $n #> [1] 2 #> #> $o #> [1] 3 #> #> $p #> [1] 4 #> #> $q #> [1] 5 #> #> $r #> [1] 6 #>
# Lump all row indexes in a single vector obs(ex_taxmap, "info", simplify = TRUE)
#> [1] 1 2 3 4 5 6
# Return values from a dataset instead of indexes obs(ex_taxmap, "info", value = "name")
#> $b #> m n o p #> "tiger" "cat" "mole" "human" #> #> $c #> q r #> "tomato" "potato" #> #> $d #> m n #> "tiger" "cat" #> #> $e #> o #> "mole" #> #> $f #> p #> "human" #> #> $g #> q r #> "tomato" "potato" #> #> $h #> m #> "tiger" #> #> $i #> n #> "cat" #> #> $j #> o #> "mole" #> #> $k #> p #> "human" #> #> $l #> q r #> "tomato" "potato" #> #> $m #> m #> "tiger" #> #> $n #> n #> "cat" #> #> $o #> o #> "mole" #> #> $p #> p #> "human" #> #> $q #> q #> "tomato" #> #> $r #> r #> "potato" #>