rbiom_objects: Working with rbiom Objects.
In rbiom: Read/Write, Analyze, and Visualize 'BIOM' Data

rbiom_objects

R Documentation

Working with rbiom Objects.

Description

Rbiom objects make it easy to access and manipulate your BIOM data, ensuring all the disparate components remain in sync. These objects behave largely like lists, in that you can access and assign to them using the $ operator. The sections below list all the fields which can be read and/or written, and the helper functions for common tasks like rarefying and subsetting. To create an rbiom object, see as_rbiom().

Use ⁠$clone()⁠ to create a copy of an rbiom object. This is necessary because rbiom objects are passed by reference. The usual ⁠<-⁠ assignment operator will simply create a second reference to the same object - it will not create a second object. See speed ups for more details.

Readable Fields

Reading from fields will not change the rbiom object.

Accessor	Content
`⁠$counts⁠`	Abundance of each OTU in each sample.
`⁠$metadata⁠`	Sample mappings to metadata (treatment, patient, etc).
`⁠$taxonomy⁠`	OTU mappings to taxonomic ranks (genus, phylum, etc).
`⁠$otus⁠`, `⁠$n_otus⁠`	OTU names.
`⁠$samples⁠`, `⁠$n_samples⁠`	Sample names.
`⁠$fields⁠`, `⁠$n_fields⁠`	Metadata field names.
`⁠$ranks⁠`, `⁠$n_ranks⁠`	Taxonomic rank names.
`⁠$tree⁠`, `⁠$sequences⁠`	Phylogenetic tree / sequences for the OTUs, or `NULL`.
`⁠$id⁠`, `⁠$comment⁠`	Arbitrary strings for describing the dataset.
`⁠$depth⁠`	Rarefaction depth, or `NULL` if unrarefied.
`⁠$date⁠`	Date from BIOM file.

Writable Fields

Assigning new values to these components will trigger validation checks and inter-component synchronization.

Component	What can be assigned.
`⁠$counts⁠`	Matrix of abundances; OTUs (rows) by samples (columns).
`⁠$metadata⁠`	Data.frame with `'.sample'` column, or a file name.
`⁠$taxonomy⁠`	Data.frame with `'.otu'` as the first column.
`⁠$otus⁠`	Character vector with new names for the OTUs.
`⁠$samples⁠`	Character vector with new names for the samples.
`⁠$tree⁠`	Phylo object with the phylogenetic tree for the OTUs.
`⁠$sequences⁠`	Named character vector of OTU reference sequences.
`⁠$id⁠`, `⁠$comment⁠`	String with dataset's title or comment.
`⁠$date⁠`	Date-like object, or `"%Y-%m-%dT%H:%M:%SZ"` string.

Transformations

All functions return an rbiom object.

Function	Transformation
`<rbiom>$clone()`	Safely duplicate an rbiom object.
`<rbiom>[`	Subset to a specific set of sample names.
`subset()`	Subset samples according to metadata properties.
`slice()`	Subset to a specific number of samples.
`mutate()`	Create, modify, and delete metadata fields.
`rarefy()`	Sub-sample OTU counts to an even sampling depth.

Examples

    library(rbiom)
    
    # Duplicate the HMP50 example dataset.
    biom <- hmp50$clone()
    
    
    # Display an overall summary of the rbiom object.
    biom
    
    
    # Markdown syntax for comments is recommended.
    biom$comment %>% cli::cli_text()
    
    
    # Demonstrate a few accessors.
    biom$n_samples
    biom$fields
    biom$metadata
    
    
    # Edit the metadata table.
    biom$metadata$rand <- sample(1:50)
    biom %<>% mutate(Obese = BMI >= 30, Sex = NULL)
    biom %<>% rename('Years Old' = "Age")
    biom$metadata
    
    
    # Subset the rbiom object
    biom %<>% subset(`Body Site` == "Saliva" & !Obese)
    biom$metadata
    
    
    # Rarefy to an even sampling depth
    sample_sums(biom)
    
    biom %<>% rarefy()
    sample_sums(biom)

rbiom documentation built on April 3, 2025, 6:39 p.m.