% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/S3_normalize.R
\name{scale}
\alias{scale}
\alias{scale.HDF5Matrix}
\title{Scale / normalize an HDF5Matrix}
\usage{
\method{scale}{HDF5Matrix}(
  x,
  center = TRUE,
  scale = TRUE,
  byrows = FALSE,
  wsize = NULL,
  result_path = NULL,
  compression = NULL,
  paral = NULL,
  threads = NULL,
  ...
)
}
\arguments{
\item{x}{An \code{HDF5Matrix} object.}

\item{center}{Logical (or numeric vector, see Details).  If \code{TRUE}
(default) subtract column means before scaling.}

\item{scale}{Logical (or numeric vector, see Details).  If \code{TRUE}
(default) divide by column standard deviations.}

\item{byrows}{Logical.  If \code{TRUE} normalize row-wise instead of
column-wise. Default \code{FALSE}.}

\item{wsize}{Integer or NULL.  Block size for HDF5 reads (NULL = auto).}

\item{result_path}{Output location.  \code{NULL} (default) writes to
\code{"NORMALIZED/<group>/<dataset>"} in the same file.
A character string writes to that path in the same file.
A named list \code{list(file=, path=)} writes to a
different file.}

\item{compression}{Integer (0-9) or NULL. gzip compression level for the
result datasets.  NULL uses the global option set by
\code{\link{hdf5matrix_options}} (default 6).  Use \code{0} to disable
compression (faster for benchmarks).}

\item{paral}{Logical or NULL. Enable OpenMP parallelism. \code{TRUE}
forces block-wise streaming (PATH 2) regardless of matrix size, so the
thread count is respected. \code{NULL} or \code{FALSE} uses the preload
path (PATH 1) when the matrix fits in RAM. Overrides the global option
set by \code{\link{hdf5matrix_options}}. Default \code{NULL}.}

\item{threads}{Integer or NULL. Number of OpenMP threads when
\code{paral = TRUE}. Always capped by \code{OMP_THREAD_LIMIT}
(CRAN compliance). \code{NULL} uses the system default. Overrides
the global option set by \code{\link{hdf5matrix_options}}.}

\item{...}{Ignored (for S3 compatibility).}
}
\value{
An \code{HDF5Matrix} pointing to the normalized dataset on disk.
}
\description{
Block-wise centering and scaling equivalent to base R \code{\link{scale}()}.
The computation runs entirely on disk — the full matrix is never loaded into
RAM.
}
\details{
Passing a pre-computed numeric vector as \code{center} or \code{scale} is
not currently supported.  If a vector is supplied it is coerced to a logical
(\code{TRUE} if \code{length(x) > 0}) and a warning is issued.

The returned \code{HDF5Matrix} carries \code{scaled:center} and
\code{scaled:scale} attributes (numeric vectors), mirroring the behavior of
\code{base::scale()}.

\strong{Performance settings:}

Parallelization and thread count can be set globally via
\code{\link{hdf5matrix_options}} or passed explicitly via \code{paral}
and \code{threads}. Explicit parameters take priority over global options.
\preformatted{
# Global configuration
hdf5matrix_options(paral = TRUE, threads = 4)
Xs <- scale(X)           # uses 4 threads

# Explicit per-call override
Xs <- scale(X, paral = TRUE, threads = 8)
}
}
\examples{
\donttest{
tmp <- tempfile(fileext = ".h5")
X   <- hdf5_create_matrix(tmp, "data/M",
                           data = matrix(rnorm(500), 50, 10))
Xs  <- scale(X)                         # center=TRUE, scale=TRUE by cols
cat("scaled:center[1]:", attr(Xs, "scaled:center")[1], "\n")
X$close(); Xs$close(); unlink(tmp)
}

}
\seealso{
\code{\link{hdf5matrix_options}} for global performance settings.
}
