% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rarefy.r
\name{biom_rescale}
\alias{biom_rescale}
\title{Rescale Counts to a Specific Range}
\usage{
biom_rescale(biom, range = c(0, 1), clone = TRUE)
}
\arguments{
\item{biom}{An \link[=rbiom_objects]{rbiom object}, or any value accepted by \code{\link[=as_rbiom]{as_rbiom()}}.}

\item{range}{Numeric vector of length 2. Target min and max.
Default: \code{c(0, 1)}.}

\item{clone}{Create a copy of \code{biom} before modifying. If \code{FALSE}, \code{biom}
is modified in place as a side-effect. See \link[=speed]{speed ups} for
use cases. Default: \code{TRUE}}
}
\value{
An \link[=rbiom_objects]{rbiom object}.
}
\description{
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.
}
\details{
Linearly rescale each sample's values to lie between a specified minimum
and maximum.
}
\note{
If \code{range} starts at a non-zero value (e.g., \code{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.
}
\section{Mathematical Transformation}{


The rescaling is performed in two steps:
\enumerate{
\item \strong{Normalize:} Divide values by the maximum value in that sample,
scaling them to a \verb{[0, 1]} range relative to the sample's peak.
\item \strong{Scale and Shift:} Apply the target range using the formula:
\deqn{x_{new} = x_{norm} \times (max - min) + min}
}
}

\examples{
    library(rbiom)
    
    biom <- hmp50[1:5]
    
    # Original range
    range(as.matrix(biom))
    
    # Rescaled to 0-1
    biom_01 <- biom_rescale(biom)
    range(as.matrix(biom_01))
    
    # Rescaled to 0-100 (Percentages)
    biom_100 <- biom_rescale(biom, range = c(0, 100))
    range(as.matrix(biom_100))
    
}
\seealso{
Other transformations: 
\code{\link{biom_inflate}()},
\code{\link{biom_relativize}()},
\code{\link{modify_metadata}},
\code{\link{rarefy}()},
\code{\link{slice_metadata}},
\code{\link{subset}()},
\code{\link{with}()}
}
\concept{transformations}
