rbiom (version 3.1.0)

rarefy: Rarefy Counts to a Constant Depth

Description

This function reduces the number of observations (reads) in each sample to a fixed integer value (depth). Samples with fewer observations than the specified depth are discarded.

Rarefaction is a common technique in microbiome analysis used to account for uneven sequencing effort across samples. By standardizing the library size, it allows for fair comparisons of alpha and beta diversity metrics.

Usage

rarefy(
  biom,
  depth = NULL,
  seed = 0L,
  inflate = FALSE,
  clone = TRUE,
  cpus = n_cpus()
)

Value

An rbiom object.

Arguments

biom

An rbiom object, or any value accepted by as_rbiom().

depth

The number of observations to keep per sample. Must be an integer greater than 0.

• If NULL (the default), a depth is automatically selected that retains at least 10% of the dataset's total abundance while maximizing the number of samples kept. See suggest_rarefy_depth() for the specific heuristic used.

• Samples with total counts less than depth will be dropped from the result.

seed

Random seed for permutations. Must be a non-negative integer. Default: 0

inflate

Logical. Handling for non-integer data (e.g. relative abundances).

• FALSE (Default): The function will error if non-integers are detected. Rarefaction requires discrete counts (integers).

• TRUE: The function will automatically rescale (inflate) non-integers to integers using biom_inflate() before rarefying. This is useful for 'shoehorning' metagenomic relative abundance data into diversity functions that strictly require integers.

clone

Create a copy of biom before modifying. If FALSE, biom is modified in place as a side-effect. See speed ups for use cases. Default: TRUE

cpus

The number of CPUs to use. Set to NULL to use all available, or to 1 to disable parallel processing. Default: NULL

Details

Normalizes the library sizes of a dataset by randomly sub-sampling observations from each sample to a specific depth.

See Also

suggest_rarefy_depth() for details on the default depth selection.

Other transformations: biom_inflate(), biom_relativize(), biom_rescale(), modify_metadata, slice_metadata, subset(), with()

Examples

    library(rbiom)
    
    biom <- hmp50[1:5]
    sample_sums(biom)
    
    # Rarefy to the lowest sample depth 
    # (All samples are kept, but counts are reduced)
    biom_rare <- rarefy(biom, depth = min(sample_sums(biom)))
    sample_sums(biom_rare)
    
    # Auto-select depth (may drop samples with low coverage)
    biom_auto <- rarefy(biom)
    sample_sums(biom_auto)