Inflate Relative Abundances to Integer Counts

Scaling a matrix of proportions (or counts) to a new target depth, rounding to integers while preserving the original total abundance sum exactly.

Usage

biom_inflate(biom, depth = NULL, clone = TRUE)

Arguments

biom

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

depth

The target library size (sum) for each sample: a single integer, or one integer per sample. Must be greater than 0. If NULL (the default), each sample's original depth is recovered exactly when its values are whole multiples of its smallest value, and otherwise estimated with the "Singleton Peak Heuristic". See suggest_inflate_depths() for details and accuracy. Counts that are already integers are left unchanged when depth = NULL.

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

Value

An rbiom object.

Rounding (Largest Remainder Method)

To ensure the sum of the resulting counts equals the target depth exactly (avoiding drift caused by simple rounding), this function uses the Largest Remainder Method (also known as the Hare-Niemeyer method).

It assigns the integer part of the scaled value to each feature, and then distributes the remaining counts to the features with the largest fractional parts.

See also

suggest_inflate_depths() for details on how target depths are estimated when depth = NULL.

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

Examples

    library(rbiom)

    biom <- hmp50[1:5]
    sample_sums(biom)
#> HMP01 HMP02 HMP03 HMP04 HMP05 
#>  1660  1371  1353  1895  3939 

    biom <- biom_relativize(biom)
    sample_sums(biom)
#> HMP01 HMP02 HMP03 HMP04 HMP05 
#>     1     1     1     1     1 

    biom <- biom_inflate(biom)
    sample_sums(biom)
#> HMP01 HMP02 HMP03 HMP04 HMP05 
#>  1660  1371  1353  1895  3939