Apply a function to each subset of an rbiom object.

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)

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

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

Details

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

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

Examples

    library(rbiom)
    
    # bdply ----------------------------------------------------
    
    bdply(hmp50, "Sex", `$`, 'n_samples')
#> # A tibble: 2 × 2
#>   Sex       V1
#>   <fct>  <int>
#> 1 Male      20
#> 2 Female    30
    
    blply(hmp50, "Sex", `$`, 'n_samples') %>% unlist()
#>   Male Female 
#>     20     30 
    
    bdply(hmp50, c("Body Site", "Sex"), function (b) {
      adm <- adiv_matrix(b)[,c("Shannon", "Simpson")]
      apply(adm, 2L, mean)
    })
#> # A tibble: 9 × 4
#>   `Body Site`    Sex    Shannon Simpson
#>   <fct>          <fct>    <dbl>   <dbl>
#> 1 Anterior nares Male     1.51    0.665
#> 2 Anterior nares Female   1.43    0.681
#> 3 Buccal mucosa  Male     1.71    0.602
#> 4 Buccal mucosa  Female   1.17    0.408
#> 5 Mid vagina     Female   0.407   0.167
#> 6 Saliva         Male     3.17    0.913
#> 7 Saliva         Female   2.93    0.893
#> 8 Stool          Male     2.51    0.835
#> 9 Stool          Female   2.43    0.850
    
    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]]))
    })
#> # A tibble: 8 × 5
#>   Sex    w     d        min   max
#>   <fct>  <lgl> <chr>  <dbl> <dbl>
#> 1 Male   TRUE  bray       0     1
#> 2 Male   FALSE bray       0     1
#> 3 Male   TRUE  euclid   292 11855
#> 4 Male   FALSE euclid     5    14
#> 5 Female TRUE  bray       0     1
#> 6 Female FALSE bray       0     1
#> 7 Female TRUE  euclid   123 17185
#> 8 Female FALSE euclid     3    12