bdply: Apply a function to each subset of an rbiom object.

Description

blply() and bdply() let you divide your biom dataset into smaller pieces, run a function on those smaller rbiom objects, and return the results as a data.frame or list.

Usage

bdply(biom, vars, FUN, ..., iters = list(), prefix = FALSE)
blply(biom, vars, FUN, ..., iters = list(), prefix = FALSE)

Value

For bdply(), a tibble data.frame comprising the accumulated outputs of FUN, along with the columns specified by vars and iters. For blply(), a named list that has details about vars and iters in attr(,'split_labels').

Arguments

biom: An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.
vars: A character vector of metadata fields. Each unique combination of values in these columns will be used to create a subsetted rbiom object to pass to FUN. If NULL, biom will be passed to FUN unaltered. Unambiguous abbreviations of metadata fields are also accepted.
FUN: The function to execute on each subset of biom. For bdply(), the returned value will be coerced to a data.frame. For blply(), any returned value is unmodified.
...: Additional arguments to pass on to FUN.
iters: A named list of values to pass to FUN. Unlike ..., these will be iterated over in all combinations. Default: list()
prefix: When TRUE, prefixes the names in in iters with a '.' in the final data.frame or 'split_labels' attribute. Default: FALSE

Details

You can also specify additional variables for your function to iterate over in unique combinations.

Calls plyr::ddply() or plyr::dlply() internally.

Examples

Run this code

    library(rbiom)
    
    bdply(hmp50, "Sex", `$`, 'n_samples')
    
    blply(hmp50, "Sex", `$`, 'n_samples') %>% unlist()
    
    bdply(hmp50, c("Body Site", "Sex"), function (b) {
      adm <- adiv_matrix(b)[,c("Shannon", "Simpson")]
      apply(adm, 2L, mean)
    })
    
    iters <- list(w = c(TRUE, FALSE), d = c("bray", "euclid"))
    bdply(hmp50, "Sex", iters = iters, function (b, w, d) {
      r <- range(bdiv_distmat(biom = b, bdiv = d, weighted = w))
      round(data.frame(min = r[[1]], max = r[[2]]))
    })