Working with rbiom Objects. — rbiom

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, or `NULL`.
`$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`	character vector of OTU reference sequences
`$id`, `$comment`	string with a title or comment for the dataset
`$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
#> 
#> ══ Human Microbiome Project - 50 Sample Demo ═══════════════
#> 
#>      50 Samples:  HMP01, HMP02, HMP03, ..., and HMP50
#>     490 OTUs:     Unc01yki, Unc53100, LtbAci52, ...
#>       7 Ranks:    .otu, Kingdom, Phylum, ..., and Genus
#>       5 Metadata: .sample, Age, BMI, Body Site, and Sex
#>         Tree:     
#> <present>
#> 
#> ── 182 - 22K reads/sample ──────────────────── 2023-12-05 ──
#> 
    
    
    # Demonstrate a few accessors.
    biom$n_samples
#> [1] 50
    biom$fields
#> [1] ".sample"   "Age"       "BMI"       "Body Site" "Sex"      
    biom$metadata
#> # A tibble: 50 × 5
#>    .sample   Age   BMI `Body Site`    Sex   
#>    <chr>   <dbl> <dbl> <fct>          <fct> 
#>  1 HMP01      22    20 Buccal mucosa  Female
#>  2 HMP02      24    23 Buccal mucosa  Male  
#>  3 HMP03      28    26 Saliva         Male  
#>  4 HMP04      25    23 Saliva         Male  
#>  5 HMP05      27    24 Buccal mucosa  Female
#>  6 HMP06      32    25 Saliva         Male  
#>  7 HMP07      26    22 Buccal mucosa  Male  
#>  8 HMP08      27    26 Saliva         Female
#>  9 HMP09      33    32 Saliva         Male  
#> 10 HMP10      22    20 Anterior nares Female
#> # ℹ 40 more rows
    
    
    # Edit the metadata table.
    biom$metadata$rand <- sample(1:50)
    biom %<>% mutate(Obese = BMI >= 30, Sex = NULL)
    biom %<>% rename('Years Old' = "Age")
    biom$metadata
#> # A tibble: 50 × 6
#>    .sample `Years Old`   BMI `Body Site`     rand Obese
#>    <chr>         <dbl> <dbl> <fct>          <int> <lgl>
#>  1 HMP01            22    20 Buccal mucosa      5 FALSE
#>  2 HMP02            24    23 Buccal mucosa     25 FALSE
#>  3 HMP03            28    26 Saliva            22 FALSE
#>  4 HMP04            25    23 Saliva            49 FALSE
#>  5 HMP05            27    24 Buccal mucosa     32 FALSE
#>  6 HMP06            32    25 Saliva            47 FALSE
#>  7 HMP07            26    22 Buccal mucosa     23 FALSE
#>  8 HMP08            27    26 Saliva            35 FALSE
#>  9 HMP09            33    32 Saliva            40 TRUE 
#> 10 HMP10            22    20 Anterior nares    30 FALSE
#> # ℹ 40 more rows
    
    
    # Subset the rbiom object
    biom %<>% subset(`Body Site` == "Saliva" & !Obese)
    biom$metadata
#> # A tibble: 8 × 6
#>   .sample `Years Old`   BMI `Body Site`  rand Obese
#>   <chr>         <dbl> <dbl> <fct>       <int> <lgl>
#> 1 HMP03            28    26 Saliva         22 FALSE
#> 2 HMP04            25    23 Saliva         49 FALSE
#> 3 HMP06            32    25 Saliva         47 FALSE
#> 4 HMP08            27    26 Saliva         35 FALSE
#> 5 HMP18            28    24 Saliva          7 FALSE
#> 6 HMP28            23    19 Saliva         10 FALSE
#> 7 HMP29            36    25 Saliva         18 FALSE
#> 8 HMP30            24    21 Saliva         39 FALSE
    
    
    # Rarefy to an even sampling depth
    sample_sums(biom)
#> HMP03 HMP04 HMP06 HMP08 HMP18 HMP28 HMP29 HMP30 
#>  1353  1895  4150  1695  2202  1695  2423  3938 
    
    biom %<>% rarefy()
    sample_sums(biom)
#> HMP03 HMP04 HMP06 HMP08 HMP18 HMP28 HMP29 HMP30 
#>  1353  1353  1353  1353  1353  1353  1353  1353