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.

     In all cases the result is coerced by 'as.vector' to one of the
     basic vector types before the dimensions are set, so that (for
     example) factor results will be coerced to a character array.

_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))

     ## 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), nrow = 2)
     ma
     apply(ma, 1, table)  #--> a list of length 2
     apply(ma, 1, stats::quantile)# 5 x n matrix with rownames

     stopifnot(dim(ma) == dim(apply(ma, 1:2, sum)))

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