repmatch {divDyn} | R Documentation

## 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"), ...)

### 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.

### 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.frame`s 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`.

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

[Package divDyn version 0.8.0 Index]