collect                package:memisc                R Documentation

_C_o_l_l_e_c_t _O_b_j_e_c_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     'collect' gathers several objects into one, matching the elements
     or subsets of the objects by 'names' or 'dimnames'.

_U_s_a_g_e:

     collect(...,names=NULL,inclusive=TRUE)
     ## Default S3 method:
     collect(...,names=NULL,inclusive=TRUE)
     ## S3 method for class 'array':
     collect(...,names=NULL,inclusive=TRUE)
     ## S3 method for class 'matrix':
     collect(...,names=NULL,inclusive=TRUE)
     ## S3 method for class 'table':
     collect(...,names=NULL,sourcename="arg",fill=0)
     ## S3 method for class 'data.frame':
     collect(...,names=NULL,inclusive=TRUE,
                                       fussy=FALSE,warn=TRUE,sourcename="arg")
     ## S3 method for class 'data.set':
     collect(...,names=NULL,inclusive=TRUE,
                                       fussy=FALSE,warn=TRUE,sourcename="arg")

_A_r_g_u_m_e_n_t_s:

     ...: more atomic vectors, arrays, matrices, tables, data.frames or
          data.sets

   names: optional character vector; in case of the default and array
          methods, giving 'dimnames' for the new dimension that
          identifies the collected objects; in case of the data.frame
          and data.set methods, levels of a factor indentifying the
          collected objects. 

inclusive: logical, defaults to TRUE; should unmatched elements
          included? See details below.

   fussy: logical, defaults to FALSE; should it count as an error, if
          variables with same names of collected data.frames/data.sets
          have different attributes?

    warn: logical, defaults to TRUE; should an warning be given, if
          variables with same names of collected data.frames/data.sets
          have different attributes?

sourcename: name of the factor that identifies the collected
          data.frames or data.sets

    fill: numeric; with what to fill empty table cells, defaults to
          zero, assuming the table contains counts

_V_a_l_u_e:

     If 'x' and all following ... arguments are vectors of the same
     mode (numeric,character, or logical) the result is a matrix with
     as many columns as vectors. If argument 'inclusive' is TRUE, then
     the number of rows equals the number of names that appear at least
     once in each of the vector names and the matrix is filled with
     'NA' where necessary, otherwise the number of rows equals the
     number of names that are present in _all_ vector names.

     If 'x' and all ... arguments are matrices or arrays of the same
     mode (numeric,character, or logical) and n dimension the result
     will be a n+1 dimensional array or table. The extend of the n+1th
     dimension equals the number of matrix, array or table arguments,
     the extends of the lower dimension depends on the 'inclusive'
     argument: either they equal to the number of dimnames that appear
     at least once for each given dimension and the array is filled
     with 'NA' where necessary, or they equal to the number of dimnames
     that appear in all arguments for each given dimension.

     If 'x' and all ... arguments are tables then the result will be a
     table. The result

     If 'x' and all ... arguments are data frames or data sets, the
     result is a data frame or data set. The number of variables of the
     resulting data frame or data set depends on the 'inclusive'
     argument. If it is true, the number of variables equals the number
     of variables that appear in each of the arguments at least once
     and variables are filled with 'NA' where necessary, otherwise the
     number of variables equals the number of variables that are
     present in all arguments.

_E_x_a_m_p_l_e_s:

     x <- c(a=1,b=2)
     y <- c(a=10,c=30)

     x
     y

     collect(x,y)
     collect(x,y,inclusive=FALSE)

     X <- matrix(1,nrow=2,ncol=2,dimnames=list(letters[1:2],LETTERS[1:2]))
     Y <- matrix(2,nrow=3,ncol=2,dimnames=list(letters[1:3],LETTERS[1:2]))
     Z <- matrix(3,nrow=2,ncol=3,dimnames=list(letters[1:2],LETTERS[1:3]))

     X
     Y
     Z

     collect(X,Y,Z)
     collect(X,Y,Z,inclusive=FALSE)

     X <- matrix(1,nrow=2,ncol=2,dimnames=list(a=letters[1:2],b=LETTERS[1:2]))
     Y <- matrix(2,nrow=3,ncol=2,dimnames=list(a=letters[1:3],c=LETTERS[1:2]))
     Z <- matrix(3,nrow=2,ncol=3,dimnames=list(a=letters[1:2],c=LETTERS[1:3]))

     collect(X,Y,Z)
     collect(X,Y,Z,inclusive=FALSE)

     df1 <- data.frame(a=rep(1,5),b=rep(1,5))
     df2 <- data.frame(a=rep(2,5),b=rep(2,5),c=rep(2,5))
     collect(df1,df2)
     collect(df1,df2,inclusive=FALSE)

     data(UCBAdmissions)
     Male <- as.table(UCBAdmissions[,1,])
     Female <- as.table(UCBAdmissions[,2,])
     collect(Male,Female,sourcename="Gender")
     collect(unclass(Male),unclass(Female))

     Male1 <- as.table(UCBAdmissions[,1,-1])
     Female2 <- as.table(UCBAdmissions[,2,-2])
     Female3 <- as.table(UCBAdmissions[,2,-3])
     collect(Male=Male1,Female=Female2,sourcename="Gender")
     collect(Male=Male1,Female=Female3,sourcename="Gender")
     collect(Male=Male1,Female=Female3,sourcename="Gender",fill=NA)

     f1 <- gl(3,5,labels=letters[1:3])
     f2 <- gl(3,6,labels=letters[1:3])
     collect(f1=table(f1),f2=table(f2))

