\HeaderA{sweep}{Sweep out Array Summaries}{sweep}
\keyword{array}{sweep}
\keyword{iteration}{sweep}
\begin{Description}\relax
Return an array obtained from an input array by sweeping out a summary
statistic.
\end{Description}
\begin{Usage}
\begin{verbatim}
sweep(x, MARGIN, STATS, FUN="-", check.margin=TRUE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an array.
\item[\code{MARGIN}] a vector of indices giving the extents of \code{x}
which correspond to \code{STATS}.
\item[\code{STATS}] the summary statistic which is to be swept out.
\item[\code{FUN}] the function to be used to carry out the sweep.  In the
case of binary operators such as \code{"/"} etc., the function name
must backquoted or quoted. (\code{FUN} is found by a call to
\code{\LinkA{match.fun}{match.fun}}.)
\item[\code{check.margin}] logical.  If \code{TRUE} (the default), warn if the
length or dimensions of \code{STATS} do not match the specified
dimensions of \code{x}.  Set to \code{FALSE} for a small speed gain
when you \emph{know} that dimensions match.
\item[\code{...}] optional arguments to \code{FUN}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The consistency check among \code{STATS}, \code{MARGIN} and \code{x}
is stricter if \code{STATS} is an array than if it is a vector.
In the vector case, some kinds of recycling are allowed without a
warning. Use \code{sweep(x,MARGIN,as.array(STATS))} if \code{STATS}
is a vector and you want to be warned if any recycling occurs.
\end{Details}
\begin{Value}
An array with the same shape as \code{x}, but with the summary
statistics swept out.
\end{Value}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{apply}{apply}} on which \code{sweep} used to be based;
\code{\LinkA{scale}{scale}} for centering and scaling.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(stats) # for median
med.att <- apply(attitude, 2, median)
sweep(data.matrix(attitude), 2, med.att)# subtract the column medians

## More sweeping:
A <- array(1:24, dim = 4:2)

## no warnings in normal use
sweep(A, 1, 5)
(A.min <- apply(A, 1, min)) # == 1:4
sweep(A, 1, A.min)
sweep(A, 1:2, apply(A, 1:2, median))

## warnings when mismatch
sweep(A, 1, 1:3)## STATS does not recycle
sweep(A, 1, 6:1)## STATS is longer

## exact recycling:
sweep(A, 1, 1:2)## no warning
sweep(A, 1, as.array(1:2))## warning
\end{ExampleCode}
\end{Examples}

