Sample n observations from taxmap()

Randomly sample some number of observations from a taxmap() object. Weights can be specified for observations or the taxa they are classified by. Any variable name that appears in all_names() can be used as if it was a vector on its own. See dplyr::sample_n() for the inspiration for this function. Calling the function using the obj$sample_n_obs(...) style edits "obj" in place, unlike most R functions. However, calling the function using the sample_n_obs(obj, ...) imitates R's traditional copy-on-modify semantics, so "obj" would not be changed; instead a changed version would be returned, like most R functions.

obj$sample_n_obs(data, size, replace = FALSE,
  taxon_weight = NULL, obs_weight = NULL,
  use_supertaxa = TRUE, collapse_func = mean, ...)
sample_n_obs(obj, data, size, replace = FALSE,
  taxon_weight = NULL, obs_weight = NULL,
  use_supertaxa = TRUE, collapse_func = mean, ...)

Arguments

obj	(taxmap()) The object to sample from.
data	Dataset names, indexes, or a logical vector that indicates which datasets in obj$data to sample. If multiple datasets are sampled at once, then they must be the same length.
size	(numeric of length 1) The number of observations to sample.
replace	(logical of length 1) If TRUE, sample with replacement.
taxon_weight	(numeric) Non-negative sampling weights of each taxon. If use_supertaxa is TRUE, the weights for each taxon in an observation's classification are supplied to collapse_func to get the observation weight. If obs_weight is also specified, the two weights are multiplied (after taxon_weight for each observation is calculated).
obs_weight	(numeric) Sampling weights of each observation. If taxon_weight is also specified, the two weights are multiplied (after taxon_weight for each observation is calculated).
use_supertaxa	(logical or numeric of length 1) Affects how the taxon_weight is used. If TRUE, the weights for each taxon in an observation's classification are multiplied to get the observation weight. Otherwise, just the taxonomic level the observation is assign to it considered. If TRUE, use all supertaxa. Positive numbers indicate the number of ranks above each taxon to use. 0 is equivalent to FALSE. Negative numbers are equivalent to TRUE.
collapse_func	(function of length 1) If taxon_weight option 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_obs().
target	DEPRECIATED. use "data" instead.

Value

An object of type 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_taxa(), select_obs(), transmute_obs()

Examples

# Sample 2 rows without replacement
sample_n_obs(ex_taxmap, "info", 2)
#> <Taxmap>
#>   17 taxa: b. Mammalia, c. Plantae ... q. lycopersicum, r. tuberosum
#>   17 edges: NA->b, NA->c, b->d, b->e ... j->o, k->p, l->q, l->r
#>   4 data sets:
#>     info:
#>       # A tibble: 2 x 4
#>         taxon_id name  n_legs dangerous
#>         <chr>    <chr>  <dbl> <lgl>    
#>       1 p        human      2 TRUE     
#>       2 n        cat        4 FALSE    
#>     phylopic_ids: a named vector of 'character' with 6 items
#>        m. e148eabb-f138-43[truncated] ... r. 63604565-0406-46[truncated]
#>     foods: a list of 6 items named by taxa:
#>        m, n, o, p, q, r
#>     abund:
#>       # A tibble: 8 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 m        T     A             1           1
#>       2 n        C     A             2           2
#>       3 o        M     B             5           3
#>       # … with 5 more rows
#>   1 functions:
#>     reaction
sample_n_obs(ex_taxmap, "foods", 2)
#> <Taxmap>
#>   17 taxa: b. Mammalia, c. Plantae ... q. lycopersicum, r. tuberosum
#>   17 edges: NA->b, NA->c, b->d, b->e ... j->o, k->p, l->q, l->r
#>   4 data sets:
#>     info:
#>       # A tibble: 6 x 4
#>         taxon_id name  n_legs dangerous
#>         <chr>    <chr>  <dbl> <lgl>    
#>       1 m        tiger      4 TRUE     
#>       2 n        cat        4 FALSE    
#>       3 o        mole       4 FALSE    
#>       # … with 3 more rows
#>     phylopic_ids: a named vector of 'character' with 6 items
#>        m. e148eabb-f138-43[truncated] ... r. 63604565-0406-46[truncated]
#>     foods: a list of 2 items named by taxa:
#>        p, n
#>     abund:
#>       # A tibble: 8 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 m        T     A             1           1
#>       2 n        C     A             2           2
#>       3 o        M     B             5           3
#>       # … with 5 more rows
#>   1 functions:
#>     reaction

# Sample with replacement
sample_n_obs(ex_taxmap, "info", 10, replace = TRUE)
#> <Taxmap>
#>   17 taxa: b. Mammalia, c. Plantae ... q. lycopersicum, r. tuberosum
#>   17 edges: NA->b, NA->c, b->d, b->e ... j->o, k->p, l->q, l->r
#>   4 data sets:
#>     info:
#>       # A tibble: 10 x 4
#>         taxon_id name  n_legs dangerous
#>         <chr>    <chr>  <dbl> <lgl>    
#>       1 p        human      2 TRUE     
#>       2 m        tiger      4 TRUE     
#>       3 o        mole       4 FALSE    
#>       # … with 7 more rows
#>     phylopic_ids: a named vector of 'character' with 6 items
#>        m. e148eabb-f138-43[truncated] ... r. 63604565-0406-46[truncated]
#>     foods: a list of 6 items named by taxa:
#>        m, n, o, p, q, r
#>     abund:
#>       # A tibble: 8 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 m        T     A             1           1
#>       2 n        C     A             2           2
#>       3 o        M     B             5           3
#>       # … with 5 more rows
#>   1 functions:
#>     reaction

# Sample some rows for often then others
sample_n_obs(ex_taxmap, "info", 3, obs_weight = n_legs)
#> <Taxmap>
#>   17 taxa: b. Mammalia, c. Plantae ... q. lycopersicum, r. tuberosum
#>   17 edges: NA->b, NA->c, b->d, b->e ... j->o, k->p, l->q, l->r
#>   4 data sets:
#>     info:
#>       # A tibble: 3 x 4
#>         taxon_id name  n_legs dangerous
#>         <chr>    <chr>  <dbl> <lgl>    
#>       1 m        tiger      4 TRUE     
#>       2 o        mole       4 FALSE    
#>       3 n        cat        4 FALSE    
#>     phylopic_ids: a named vector of 'character' with 6 items
#>        m. e148eabb-f138-43[truncated] ... r. 63604565-0406-46[truncated]
#>     foods: a list of 6 items named by taxa:
#>        m, n, o, p, q, r
#>     abund:
#>       # A tibble: 8 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 m        T     A             1           1
#>       2 n        C     A             2           2
#>       3 o        M     B             5           3
#>       # … with 5 more rows
#>   1 functions:
#>     reaction

# Sample multiple datasets at once
sample_n_obs(ex_taxmap, c("info", "phylopic_ids", "foods"), 3)
#> <Taxmap>
#>   17 taxa: b. Mammalia, c. Plantae ... q. lycopersicum, r. tuberosum
#>   17 edges: NA->b, NA->c, b->d, b->e ... j->o, k->p, l->q, l->r
#>   4 data sets:
#>     info:
#>       # A tibble: 3 x 4
#>         taxon_id name   n_legs dangerous
#>         <chr>    <chr>   <dbl> <lgl>    
#>       1 o        mole        4 FALSE    
#>       2 p        human       2 TRUE     
#>       3 r        potato      0 FALSE    
#>     phylopic_ids: a named vector of 'character' with 3 items
#>        o. 11b783d5-af1c-4f[truncated] ... r. 63604565-0406-46[truncated]
#>     foods: a list of 3 items named by taxa:
#>        o, p, r
#>     abund:
#>       # A tibble: 8 x 5
#>         taxon_id code  sample_id count taxon_index
#>         <chr>    <fct> <fct>     <dbl>       <int>
#>       1 m        T     A             1           1
#>       2 n        C     A             2           2
#>       3 o        M     B             5           3
#>       # … with 5 more rows
#>   1 functions:
#>     reaction