Combine several rbiom objects into one.

WARNING: It is generally ill-advised to merge BIOM datasets, as OTUs mappings are dependent on upstream clustering and are not equivalent between BIOM files.

Usage

biom_merge(
  ...,
  metadata = NA,
  taxonomy = NA,
  tree = NA,
  sequences = NA,
  id = NA,
  comment = NA
)

Arguments

...

Any number of rbiom objects, or anything accepted by the biom parameter of as_rbiom() (matrices, file names, lists with a counts element, phyloseq objects, ...). Lists of such inputs are flattened.

metadata, taxonomy, tree, sequences, id, comment

Replace the corresponding data in the merged rbiom object with these values. The default, NA, derives the component from the inputs (see details). Set to NULL to omit the component.

Value

An rbiom object.

Details

Samples present in more than one input must have identical counts; otherwise an error is raised. OTUs are matched by name.

With the default NA arguments:

• metadata and taxonomy are the union of the inputs' tables. A field whose type differs between inputs (for example numeric in one and categorical in another) is converted to categorical, with a single warning listing the affected fields. An OTU with different lineages in different inputs keeps the most detailed one (one summarizing warning).

• sequences are the union of the inputs' sequences. If only some inputs have sequences, OTUs without one get NA and a warning is issued once.

• tree is taken from the first input whose tree contains every OTU of the merged object (pruned to those OTUs). This is the case when the inputs are subsets of one dataset. If no input tree covers all of the OTUs, the merged object has no tree and a message says so; a merged tree can't be inferred, so supply tree= in that case.

• id and comment are kept when all inputs agree, and are otherwise "Merged BIOM" and "".

The merged object's $history nests the histories of its inputs, so its $code reproduces the entire pipeline.

See also

Other biom: bdply()

Examples

    library(rbiom)

    b1 <- as_rbiom(hmp50$counts[,1:4])
    b2 <- as_rbiom(hmp50$counts[,5:8])

    biom <- biom_merge(b1, b2)
    print(biom)
#> 
#> ══ Untitled Dataset ════════════════════════════════════════
#> 
#>       8 Samples: HMP01, HMP02, HMP03, ..., and HMP08 
#>     168 OTUs:    Unc53100, PpbAcne6, UncO2012, ... 
#>       1 Ranks:   .otu 
#>       1 Fields:  .sample 
#>         Tree:    <absent>
#> 
#> ── 1.4k - 4.2k reads/sample ────────────────── 2026-11-13 ──
#> 

    biom$tree     <- hmp50$tree
    biom$metadata <- subset(hmp50$metadata, .sample %in% biom$samples)
    print(biom)
#> 
#> ══ Untitled Dataset ════════════════════════════════════════
#> 
#>       8 Samples: HMP01, HMP02, HMP03, ..., and HMP08 
#>     168 OTUs:    Unc53100, PpbAcne6, UncO2012, ... 
#>       1 Ranks:   .otu 
#>       5 Fields:  .sample, Age, BMI, Body Site, and Sex 
#>         Tree:    <present>
#> 
#> ── 1.4k - 4.2k reads/sample ────────────────── 2026-11-13 ──
#> 

    # Subsets of one dataset keep its tree, and record their history.
    biom <- biom_merge(hmp50[1:10], hmp50[11:20])
    biom$code
#> # Generated by rbiom 4.0.0
#> library(rbiom)
#> 
#> biom1 <- hmp50
#> biom1 <- biom1[1:10]
#> 
#> biom2 <- hmp50
#> biom2 <- biom2[11:20]
#> 
#> biom <- biom_merge(biom1, biom2)