Write, Analyze, and Visualize 'BIOM' Data

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Create an rbiom object

The fastest way to make an rbiom object is with as_rbiom(), which accepts:

A filepath or URL to a BIOM file.
An abundance matrix with OTUs in rows and samples in columns.
A phyloseq-class object, from the phyloseq Bioconductor R package.
A list with counts and optionally metadata, taxonomy, tree, etc (see as_rbiom()).

library(rbiom)

# create a simple matrix ------------------------
mtx <- matrix(
  data     = floor(runif(24) * 1000), 
  nrow     = 6, 
  dimnames = list(paste0("OTU", 1:6), paste0("Sample", 1:4)) )
mtx

# convert matrix to rbiom -----------------------
biom <- as_rbiom(biom = mtx)
biom


# convert from phyloseq to rbiom ----------------
file <- system.file("extdata", "rich_sparse_otu_table.biom", package="phyloseq")
phy  <- phyloseq::import_biom(file)
phy

biom <- as_rbiom(biom = phy)
biom

Now we have biom, an rbiom-class object that can be used with this package's functions. If you loaded your data from a BIOM file or phyloseq object, it might already include metadata, ranks, and a tree. These attributes are technically optional, however, more analyses are possible when extra information about samples and OTUs are present.

Attach metadata

$metadata lets you set arbitrary data for each sample.

A few quick rules:

.sample should be the first column.
Other column names cannot start with a dot (.).
Sample names need to match biom$samples.

# create example metadata -----------------------
md <- data.frame(
  .sample   = paste0("Sample", 1:4),
  state     = c("TX", "TX", "WA", "WA"),
  age       = c(32, 19, 36, 40),
  treatment = c(1, 2, 1, 2) )
md

# add metadata to rbiom object ------------------
biom <- as_rbiom(biom = mtx)
biom$metadata <- md
biom

# or in a single step ---------------------------
biom <- as_rbiom(biom = list(counts = mtx, metadata = md))
biom

Setting categorical variables

Any categorical metadata variable that looks numerical, such as "treatment" in the above example, will need to be manually changed to a categorical variable.

class(pull(biom, 'treatment'))

biom$metadata$treatment %<>% as.factor()

class(pull(biom, 'treatment'))
pull(biom, 'treatment')

Attach a tree

Use $tree to set the tree. You can specify a phylo object directly, or a newick file/string.

# define a random tree --------------------------
biom$tree <- "(((OTU6,(OTU5,OTU4)),OTU3),(OTU2,OTU1));"
biom

Attach taxonomy

Use $taxonomy to define taxonomic clades for each OTU.

# .otu must match otu_names(biom) ---------------
map <- data.frame(
  .otu   = paste0("OTU", 1:6),
  Phylum = c("Bacteroidetes", "Firmicutes", "Firmicutes"),
  Order  = c("Bacteroidia", "Clostridiales", "Bacillales") )
map

biom$taxonomy <- map
biom