metacoder (version 0.3.7)

sample_n_taxa: Sample n taxa from [taxonomy()] or [taxmap()]

Description

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, ...)

Value

An object of type [taxonomy()] or [taxmap()]

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()].

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)

# Include supertaxa
sample_n_taxa(ex_taxmap, 3, supertaxa = TRUE)

# Include subtaxa
sample_n_taxa(ex_taxmap, 1, subtaxa = TRUE)

# Sample some taxa more often then others
sample_n_taxa(ex_taxmap, 3, supertaxa = TRUE,
              obs_weight = n_legs, obs_target = "info")