Rescale Counts to a Specific Range

This function performs a min-max scaling on each sample independently.

It is useful for normalization techniques that require data to be within a specific bounded range, or for visualization purposes where maintaining the relative distances between values is important but the absolute magnitude needs adjustment.

Usage

biom_rescale(biom, range = c(0, 1), clone = TRUE)

Arguments

biom

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

range

Numeric vector of length 2. Target min and max. Default: c(0, 1).

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.

Details

Linearly rescale each sample's values to lie between a specified minimum and maximum.

Note

If range starts at a non-zero value (e.g., c(1, 10)), the sparsity of the matrix will be destroyed because all zero counts will be shifted to the minimum value. This can significantly increase memory usage for large datasets.

Mathematical Transformation

The rescaling is performed in two steps:

1. Normalize: Divide values by the maximum value in that sample, scaling them to a [0, 1] range relative to the sample's peak.

2. Scale and Shift: Apply the target range using the formula: $$x_{new} = x_{norm} \times (max - min) + min$$

See also

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

Examples

    library(rbiom)
    
    biom <- hmp50[1:5]
    
    # Original range
    range(as.matrix(biom))
#> [1]    0 2672
    
    # Rescaled to 0-1
    biom_01 <- biom_rescale(biom)
    range(as.matrix(biom_01))
#> [1] 0 1
    
    # Rescaled to 0-100 (Percentages)
    biom_100 <- biom_rescale(biom, range = c(0, 100))
    range(as.matrix(biom_100))
#> [1]   0 100