sweep                  package:base                  R Documentation

Sweep out Array Summaries

Description:

     Return an array obtained from an input array by sweeping out a
     summary statistic.

Usage:

     sweep(x, MARGIN, STATS, FUN="-", check.margin=TRUE, ...)

Arguments:

       x: an array.

  MARGIN: a vector of indices giving the extents of 'x' which
          correspond to 'STATS'.

   STATS: the summary statistic which is to be swept out.

     FUN: the function to be used to carry out the sweep.  In the case
          of binary operators such as '"/"' etc., the function name
          must backquoted or quoted. ('FUN' is found by a call to
          'match.fun'.)

check.margin: logical.  If 'TRUE' (the default), warn if the length or
          dimensions of 'STATS' do not match the specified dimensions
          of 'x'.  Set to 'FALSE' for a small speed gain when you
          _know_ that dimensions match.

     ...: optional arguments to 'FUN'.

Details:

     The consistency check among 'STATS', 'MARGIN' and 'x' is stricter
     if 'STATS' is an array than if it is a vector. In the vector case,
     some kinds of recycling are allowed without a warning. Use
     'sweep(x,MARGIN,as.array(STATS))' if 'STATS' is a vector and you
     want to be warned if any recycling occurs.

Value:

     An array with the same shape as 'x', but with the summary
     statistics swept out.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'apply' on which 'sweep' used to be based; 'scale' for centering
     and scaling.

Examples:

     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

