apply                  package:base                  R Documentation

_A_p_p_l_y _F_u_n_c_t_i_o_n_s _O_v_e_r _A_r_r_a_y _M_a_r_g_i_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Returns a vector or array or list of values obtained by applying a
     function to margins of an array.

_U_s_a_g_e:

     apply(X, MARGIN, FUN, ...)

_A_r_g_u_m_e_n_t_s:

       X: the array to be used.

  MARGIN: a vector giving the subscripts which the function will be
          applied over. '1' indicates rows, '2' indicates columns,
          'c(1,2)' indicates rows and columns.

     FUN: the function to be applied: see Details. In the case of
          functions like '+', '%*%', etc., the function name must be
          backquoted or quoted.

     ...: optional arguments to 'FUN'.

_D_e_t_a_i_l_s:

     If 'X' is not an array but has a dimension attribute, 'apply'
     attempts to coerce it to an array via 'as.matrix' if it is
     two-dimensional (e.g., data frames) or via 'as.array'.

     'FUN' is found by a call to 'match.fun' and typically is either a
     function or a symbol (e.g. a backquoted name) or a character
     string specifying a function to be searched for from the 
     environment of the call to 'apply'.

_V_a_l_u_e:

     If each call to 'FUN' returns a vector of length 'n', then 'apply'
     returns an array of dimension 'c(n, dim(X)[MARGIN])' if 'n > 1'. 
     If 'n' equals '1', 'apply' returns a vector if 'MARGIN' has length
     1 and an array of dimension 'dim(X)[MARGIN]' otherwise. If 'n' is
     '0', the result has length 0 but not necessarily the "correct"
     dimension.

     If the calls to 'FUN' return vectors of different lengths, 'apply'
     returns a list of length 'prod(dim(X)[MARGIN])' with 'dim' set to
     'MARGIN' if this has length greater than one.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'lapply', 'tapply', and convenience functions 'sweep' and
     'aggregate'.

_E_x_a_m_p_l_e_s:

     ## Compute row and column sums for a matrix:
     x <- cbind(x1 = 3, x2 = c(4:1, 2:5))
     dimnames(x)[[1]] <- letters[1:8]
     apply(x, 2, mean, trim = .2)
     col.sums <- apply(x, 2, sum)
     row.sums <- apply(x, 1, sum)
     rbind(cbind(x, Rtot = row.sums), Ctot = c(col.sums, sum(col.sums)))

     stopifnot( apply(x, 2, is.vector)) # not ok in R <= 0.63.2

     ## Sort the columns of a matrix
     apply(x, 2, sort)

     ##- function with extra args:
     cave <- function(x, c1, c2) c(mean(x[c1]), mean(x[c2]))
     apply(x,1, cave,  c1="x1", c2=c("x1","x2"))

     ma <- matrix(c(1:4, 1, 6:8), nr = 2)
     ma
     apply(ma, 1, table)  #--> a list of length 2
     apply(ma, 1, quantile)# 5 x n matrix with rownames

     stopifnot(dim(ma) == dim(apply(ma, 1:2, sum)))## wasn't ok before R 0.63.1

     ## Example with different lengths for each call
     z <- array(1:24, dim=2:4)
     zseq <- apply(z, 1:2, function(x) seq(length=max(x)))
     zseq         ## a 2 x 3 matrix
     typeof(zseq) ## list
     dim(zseq) ## 2 3
     zseq[1,]
     apply(z, 3, function(x) seq(length=max(x))) # a list without a dim attribute

