rbiom (version 2.1.2)

rbiom_objects: 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)