Sample n taxa from taxonomy() or taxmap()

Randomly sample some number of taxa from a taxonomy() or taxmap() object. Weights can be specified for taxa or the observations assigned to them. See dplyr::sample_n() for the inspiration for this function.

obj$sample_n_taxa(size, taxon_weight = NULL,
  obs_weight = NULL, obs_target = NULL,
  use_subtaxa = TRUE, collapse_func = mean, ...)
sample_n_taxa(obj, size, taxon_weight = NULL,
  obs_weight = NULL, obs_target = NULL,
  use_subtaxa = TRUE, collapse_func = mean, ...)

Arguments

obj	(taxonomy() or taxmap()) The object to sample from.
size	(numeric of length 1) The number of taxa to sample.
taxon_weight	(numeric) Non-negative sampling weights of each taxon. If obs_weight is also specified, the two weights are multiplied (after obs_weight for each taxon is calculated).
obs_weight	(numeric) This option only applies to taxmap() objects. Sampling weights of each observation. The weights for each observation assigned to a given taxon are supplied to collapse_func to get the taxon weight. If use_subtaxa is TRUE then the observations assigned to every subtaxa are also used. Any variable name that appears in all_names() can be used as if it was a vector on its own. If taxon_weight is also specified, the two weights are multiplied (after obs_weight for each observation is calculated). obs_target must be used with this option.
obs_target	(character of length 1) This option only applies to taxmap() objects. The name of the data set in obj$data that values in obs_weight corresponds to. Must be used when obs_weight is used.
use_subtaxa	(logical or numeric of length 1) Affects how the obs_weight option is used. If TRUE, the weights for each taxon in an observation's classification are multiplied to get the observation weight. If FALSE just the taxonomic level the observation is assign to it considered. Positive numbers indicate the number of ranks below the each taxon to use. 0 is equivalent to FALSE. Negative numbers are equivalent to TRUE.
collapse_func	(function of length 1) If taxon_weight is used and supertaxa is TRUE, the weights for each taxon in an observation's classification are supplied to collapse_func to get the observation weight. This function should take numeric vector and return a single number.
...	Additional options are passed to filter_taxa().

Value

An object of type taxonomy() or taxmap()

See also

Other taxmap manipulation functions: arrange_obs(), arrange_taxa(), filter_obs(), filter_taxa(), mutate_obs(), sample_frac_obs(), sample_frac_taxa(), sample_n_obs(), select_obs(), transmute_obs()

Examples

# Randomly sample three taxa
sample_n_taxa(ex_taxmap, 3)
#> <Taxmap>
#>   3 taxa: i. Felis, k. homo, o. typhlops
#>   3 edges: NA->i, NA->k, NA->o
#>   4 data sets:
#>     info:
#>       # A tibble: 3 x 4
#>         taxon_id name  n_legs dangerous
#>         <chr>    <chr>  <dbl> <lgl>    
#>       1 i        cat        4 FALSE    
#>       2 o        mole       4 FALSE    
#>       3 k        human      2 TRUE     
#>     phylopic_ids: a named vector of 'character' with 3 items
#>        i. 12899ba0-9923-4f[truncated] ... k. 9fae30cd-fb59-4a[truncated]
#>     foods: a list of 3 items named by taxa:
#>        i, o, k
#>     abund:
#>       # A tibble: 6 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 i        C     A             2           2
#>       2 o        M     B             5           3
#>       3 k        H     B             2           4
#>       # … with 3 more rows
#>   1 functions:
#>     reaction

# Include supertaxa
sample_n_taxa(ex_taxmap, 3, supertaxa = TRUE)
#> <Taxmap>
#>   4 taxa: b. Mammalia, c. Plantae ... g. Solanaceae
#>   4 edges: NA->b, NA->c, b->e, c->g
#>   4 data sets:
#>     info:
#>       # A tibble: 6 x 4
#>         taxon_id name  n_legs dangerous
#>         <chr>    <chr>  <dbl> <lgl>    
#>       1 b        tiger      4 TRUE     
#>       2 b        cat        4 FALSE    
#>       3 e        mole       4 FALSE    
#>       # … with 3 more rows
#>     phylopic_ids: a named vector of 'character' with 6 items
#>        b. e148eabb-f138-43[truncated] ... g. 63604565-0406-46[truncated]
#>     foods: a list of 6 items named by taxa:
#>        b, b, e, b, g, g
#>     abund:
#>       # A tibble: 8 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 b        T     A             1           1
#>       2 b        C     A             2           2
#>       3 e        M     B             5           3
#>       # … with 5 more rows
#>   1 functions:
#>     reaction

# Include subtaxa
sample_n_taxa(ex_taxmap, 1, subtaxa = TRUE)
#> <Taxmap>
#>   1 taxa: n. catus
#>   1 edges: NA->n
#>   4 data sets:
#>     info:
#>       # A tibble: 1 x 4
#>         taxon_id name  n_legs dangerous
#>         <chr>    <chr>  <dbl> <lgl>    
#>       1 n        cat        4 FALSE    
#>     phylopic_ids: a named vector of 'character' with 1 item
#>        n. 12899ba0-9923-4feb-a7f9-758c3c7d5e13
#>     foods: a list of 1 item named by taxa:
#>        n
#>     abund:
#>       # A tibble: 2 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 n        C     A             2           2
#>       2 n        C     A             2           2
#>   1 functions:
#>     reaction

# Sample some taxa more often then others
sample_n_taxa(ex_taxmap, 3, supertaxa = TRUE,
              obs_weight = n_legs, obs_target = "info")
#> <Taxmap>
#>   4 taxa: b. Mammalia, e. Notoryctidae ... o. typhlops
#>   4 edges: NA->b, b->e, e->j, j->o
#>   4 data sets:
#>     info:
#>       # A tibble: 4 x 4
#>         taxon_id name  n_legs dangerous
#>         <chr>    <chr>  <dbl> <lgl>    
#>       1 b        tiger      4 TRUE     
#>       2 b        cat        4 FALSE    
#>       3 o        mole       4 FALSE    
#>       # … with 1 more row
#>     phylopic_ids: a named vector of 'character' with 4 items
#>        b. e148eabb-f138-43[truncated] ... b. 9fae30cd-fb59-4a[truncated]
#>     foods: a list of 4 items named by taxa:
#>        b, b, o, b
#>     abund:
#>       # A tibble: 8 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 b        T     A             1           1
#>       2 b        C     A             2           2
#>       3 o        M     B             5           3
#>       # … with 5 more rows
#>   1 functions:
#>     reaction