divDyn (version 0.8.3)

repmatch: Replicate matching and merging

Description

This pseudo-generic function iterates a function on the subelements of a list of objects that have the same class and matching dimensions/names and reorganizes the result to match the structure of the replicates or a prototype template.

Usage

repmatch(x, FUN = NULL, proto = NULL, direct = c("dim", "name"), ...)

Value

If FUN is a function, the output is vector for vector-like replicates, matrix when x is a list of matrix objects, and data.frames for data.frame replicates. In case FUN=NULL: if x is a list of vectors, the function will return a matrix; an array is returned, if x is a list of matrix class obejcts; if x is a list of data.frame objects, the function returns a data.frame.

Arguments

x

(list): A list of replicates.

FUN

(function): A function to merge with and to be applied to the values of identical positions in different replicates. This function must have a single output value, vectors are not allowed. The default NULL option returns an element-wise reorganization of the data.

proto

(same as x[[1]]): The prototype for matching/merging. The prototype is used as a check ("dim") or a template ("name") during the matching process, depending on the used directive (direct argument). It is an object with the same class as the replicates, and have the same dimensions and/or overlapping names. If the "name" directive is used and a prototype is provided, the funtion will force the output to have the same structure as the prototype, by omitting unnecessary information and inserting missing values (NAs). The prototype is expected to be an object that has more or equal elements than the replicates, otherwise the call will result in a warning.

direct

(character): Matching directive(s). Can either be dimension-based ("dim") and/or name-based (name). Dimension-based directive matches the replicates if they have the same dimesions. The "name" directive requires named input (for matrices and data.frames colnames and rownames attributes). Replicates will be matched if the values have the same names. In case both directives are specified (default), dimension-based directive takes higher priority, if matching is unsuccessful with dimensions, names will be tried after.

...

arguments passed to FUN.

Details

The function is designed to unify/merge objects that result from the same function applied to different source data (e.g. the results of subsample()). In its current form, the function supports vectors (including one-dimensional tables and arrays), matrix and data.frame objects.

Examples

# basic example
vect <- rnorm(100)
# make 50 replicates
repl <- rep(list(vect), 50)
repmatch(repl, FUN=mean, direct="dim")

# named input
  # two vectors
    # a
    a<- 1:10
    names(a) <- letters[1:length(a)]
    a[c(3,5,8)] <- NA
    a <- a[!is.na(a)]
  
    #b
    b<- 10:1
    names(b) <- letters[length(b):1]
    b[c(1, 3,6, length(b))]<- NA
    b <- b[!is.na(b)]

  # list
  x2 <- rep(c(list(a),list(b)), 3)

# simple match - falling through "dim" to "name" directive
repmatch(x2, FUN=NULL)

# prototyped
prot <- 1:10
names(prot) <-letters[1:10]

repmatch(x2, FUN=mean, proto=prot, na.rm=TRUE)