% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/standardize.R, R/unstandardize.R
\name{standardize}
\alias{standardize}
\alias{standardise}
\alias{standardize.numeric}
\alias{standardize.factor}
\alias{standardize.data.frame}
\alias{unstandardize}
\alias{unstandardise}
\alias{unstandardize.numeric}
\alias{unstandardize.data.frame}
\title{Standardization (Z-scoring)}
\usage{
standardize(x, ...)

standardise(x, ...)

\method{standardize}{numeric}(
  x,
  robust = FALSE,
  two_sd = FALSE,
  weights = NULL,
  verbose = TRUE,
  reference = NULL,
  center = NULL,
  scale = NULL,
  ...
)

\method{standardize}{factor}(
  x,
  robust = FALSE,
  two_sd = FALSE,
  weights = NULL,
  verbose = TRUE,
  force = FALSE,
  ...
)

\method{standardize}{data.frame}(
  x,
  robust = FALSE,
  two_sd = FALSE,
  weights = NULL,
  verbose = TRUE,
  reference = NULL,
  select = NULL,
  exclude = NULL,
  remove_na = c("none", "selected", "all"),
  force = FALSE,
  append = FALSE,
  center = NULL,
  scale = NULL,
  ...
)

unstandardize(x, ...)

unstandardise(x, ...)

\method{unstandardize}{numeric}(
  x,
  center = NULL,
  scale = NULL,
  reference = NULL,
  robust = FALSE,
  two_sd = FALSE,
  ...
)

\method{unstandardize}{data.frame}(
  x,
  center = NULL,
  scale = NULL,
  reference = NULL,
  robust = FALSE,
  two_sd = FALSE,
  select = NULL,
  exclude = NULL,
  ...
)
}
\arguments{
\item{x}{A data frame, a vector or a statistical model (for \code{unstandardize()}
cannot be a model).}

\item{...}{Arguments passed to or from other methods.}

\item{robust}{Logical, if \code{TRUE}, centering is done by subtracting the
median from the variables and dividing it by the median absolute deviation
(MAD). If \code{FALSE}, variables are standardized by subtracting the
mean and dividing it by the standard deviation (SD).}

\item{two_sd}{If \code{TRUE}, the variables are scaled by two times the deviation
(SD or MAD depending on \code{robust}). This method can be useful to obtain
model coefficients of continuous parameters comparable to coefficients
related to binary predictors, when applied to \strong{the predictors} (not the
outcome) (Gelman, 2008).}

\item{weights}{Can be \code{NULL} (for no weighting), or:
\itemize{
\item For model: if \code{TRUE} (default), a weighted-standardization is carried out.
\item For \code{data.frame}s: a numeric vector of weights, or a character of the
name of a column in the \code{data.frame} that contains the weights.
\item For numeric vectors: a numeric vector of weights.
}}

\item{verbose}{Toggle warnings and messages on or off.}

\item{reference}{A data frame or variable from which the centrality and
deviation will be computed instead of from the input variable. Useful for
standardizing a subset or new data according to another data frame.}

\item{center, scale}{\itemize{
\item For \code{standardize()}: \cr
Numeric values, which can be used as alternative to \code{reference} to define
a reference centrality and deviation. If \code{scale} and \code{center} are of
length 1, they will be recycled to match the length of selected variables
for standardization. Else, \code{center} and \code{scale} must be of same length as
the number of selected variables. Values in \code{center} and \code{scale} will be
matched to selected variables in the provided order, unless a named vector
is given. In this case, names are matched against the names of the selected
variables.
\item For \code{unstandardize()}: \cr
\code{center} and \code{scale} correspond to the center (the mean / median) and the scale (SD / MAD) of
the original non-standardized data (for data frames, should be named, or
have column order correspond to the numeric column). However, one can also
directly provide the original data through \code{reference}, from which the
center and the scale will be computed (according to \code{robust} and \code{two_sd}).
Alternatively, if the input contains the attributes \code{center} and \code{scale}
(as does the output of \code{standardize()}), it will take it from there if the
rest of the arguments are absent.
}}

\item{force}{Logical, if \code{TRUE}, forces standardization of factors and dates
as well. Factors are converted to numerical values, with the lowest level
being the value \code{1} (unless the factor has numeric levels, which are
converted to the corresponding numeric value).}

\item{select}{Character vector of column names. If \code{NULL} (the default), all
variables will be selected.}

\item{exclude}{Character vector of column names to be excluded from selection.}

\item{remove_na}{How should missing values (\code{NA}) be treated: if \code{"none"}
(default): each column's standardization is done separately, ignoring
\code{NA}s. Else, rows with \code{NA} in the columns selected with \code{select} /
\code{exclude} (\code{"selected"}) or in all columns (\code{"all"}) are dropped before
standardization, and the resulting data frame does not include these cases.}

\item{append}{Logical or string. If \code{TRUE}, standardized variables get new
column names (with the suffix \code{"_z"}) and are appended (column bind) to \code{x},
thus returning both the original and the standardized variables. If \code{FALSE},
original variables in \code{x} will be overwritten by their standardized versions.
If a character value, standardized variables are appended with new column
names (using the defined suffix) to the original data frame.}
}
\value{
The standardized object (either a standardize data frame or a
statistical model fitted on standardized data).
}
\description{
Performs a standardization of data (z-scoring), i.e., centering and scaling,
so that the data is expressed in terms of standard deviation (i.e., mean = 0,
SD = 1) or Median Absolute Deviance (median = 0, MAD = 1). When applied to a
statistical model, this function extracts the dataset, standardizes it, and
refits the model with this standardized version of the dataset. The
\code{\link[=normalize]{normalize()}} function can also be used to scale all numeric variables within
the 0 - 1 range.
\cr\cr
For model standardization, see \code{\link[effectsize:standardize.default]{effectsize::standardize.default()}}
}
\note{
When \code{x} is a vector or a data frame with \verb{remove_na = "none")},
missing values are preserved, so the return value has the same length /
number of rows as the original input.
}
\examples{
d <- iris[1:4, ]

# vectors
standardise(d$Petal.Length)

# Data frames
# overwrite
standardise(d, select = c("Sepal.Length", "Sepal.Width"))

# append
standardise(d, select = c("Sepal.Length", "Sepal.Width"), append = TRUE)

# append, suffix
standardise(d, select = c("Sepal.Length", "Sepal.Width"), append = "_std")

# standardizing with reference center and scale
d <- data.frame(
  a = c(-2, -1, 0, 1, 2),
  b = c(3, 4, 5, 6, 7)
)

# default standardization, based on mean and sd of each variable
standardize(d) # means are 0 and 5, sd ~ 1.581139

# standardization, based on mean and sd set to the same values
standardize(d, center = c(0, 5), scale = c(1.581, 1.581))

# standardization, mean and sd for each variable newly defined
standardize(d, center = c(3, 4), scale = c(2, 4))

# standardization, taking same mean and sd for each variable
standardize(d, center = 1, scale = 3)
}
\seealso{
See \code{\link[=center]{center()}} for grand-mean centering of variables.

Other transform utilities: 
\code{\link{data_rescale}()},
\code{\link{normalize}()},
\code{\link{ranktransform}()}
}
\concept{standardize}
\concept{transform utilities}
