R: Fill an array with subarrays

afill {abind} | R Documentation

## Fill an array with subarrays

### Description

Fill an array with subarrays. `afill` uses the dimension names in the value in determining how to fill the LHS, unlike standard array assignment, which ignores dimension names in the value. `afill()` is a S3 generic, with one method, `afill.default`, supplied in the `abind` package.

### Usage

    afill(x, ..., excess.ok = FALSE, local = TRUE) <- value

### Arguments

`x` | An array to be changed
`...` | Arguments that specify indices for `x`. If `length(dim(value)) < length(dim(x))`, then exactly `length(dim(x))` anonymous arguments must be supplied, with empty ones corresponding to dimensions of `x` that are supplied in `value`.
`excess.ok` | If there are elements of the dimensions of `value` that are not found in the corresponding dimensions of x, they will be discarded if `excess.ok=TRUE`.
`local` | Should the assignment be done in on a copy of x, and the result returned (normal behavior). If `local=FALSE` the assignment will be done directly on the actual argument supplied as `x`, which can be more space efficient.
`value` | A vector or array, with dimension names that match some dimensions of `x`

### Details

The simplest use of `afill` is to fill a sub-matrix. Here is an example of this usage:

    > (x <- matrix(0, ncol=3, nrow=4, dimnames=list(letters[1:4], LETTERS[24:26])))
      X Y Z
    a 0 0 0
    b 0 0 0
    c 0 0 0
    d 0 0 0
    > (y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26])))
      Y Z
    b 1 3
    c 2 4
    > afill(x) <- y
    > x
      X Y Z
    a 0 0 0
    b 0 1 3
    c 0 2 4
    d 0 0 0
    >

The above usage is equivalent (when x and y have appropriately matching dimnames) to

    > x[match(rownames(y), rownames(x)), match(colnames(y), colnames(x))] <- y

A more complex usage of `afill` is to fill a sub-matrix in a slice of a higher-dimensional array. In this case, indices for `x` must be supplied as arguments to `afill`, with the dimensions corresponding to those of `value` being empty, e.g.:

    > x <- array(0, dim=c(2,4,3), dimnames=list(LETTERS[1:2], letters[1:4], LETTERS[24:26]))
    > y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26]))
    > afill(x, 1, , ) <- y
    > x[1,,]
      X Y Z
    a 0 0 0
    b 0 1 3
    c 0 2 4
    d 0 0 0
    > x[2,,]
      X Y Z
    a 0 0 0
    b 0 0 0
    c 0 0 0
    d 0 0 0
    >

The most complex usage of `afill` is to fill a sub-matrix in multiple slice of a higher-dimensional array. Again, indices for `x` must be supplied as arguments to `afill`, with the dimensions corresponding to those of `value` being empty. Indices in which all slices should be filled can be supplied as `TRUE`. E.g.:

    > x <- array(0, dim=c(2,4,3), dimnames=list(LETTERS[1:2], letters[1:4], LETTERS[24:26]))
    > y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26]))
    > afill(x, TRUE, , ) <- y
    > x[1,,]
      X Y Z
    a 0 0 0
    b 0 1 3
    c 0 2 4
    d 0 0 0
    > x[2,,]
      X Y Z
    a 0 0 0
    b 0 1 3
    c 0 2 4
    d 0 0 0
    >

In the above usage, `afill` takes care of replicating `value` in the appropriate fashion (which is not straghtforward in some cases).

### Value

The object `x` is changed. The return value of the assignment is the parts of the object `x` that are changed. This is similar to how regular subscript-replacement behaves, e.g., the expression `x[2:3] <- 1:2` returns the vector `1:2`, not the entire object `x`. However, note that there can be differences

### Author(s)

Tony Plate tplate@acm.org

### See Also

`Extract`

### Examples

    # fill a submatrix defined by the dimnames on y
    (x <- matrix(0, ncol=3, nrow=4, dimnames=list(letters[1:4], LETTERS[24:26])))
    (y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26])))
    afill(x) <- y
    x
    all.equal(asub(x, dimnames(y)), y) # TRUE
    # fill a slice in a higher dimensional array
    x <- array(0, dim=c(2,4,3), dimnames=list(LETTERS[1:2], letters[1:4], LETTERS[24:26]))
    y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26]))
    afill(x, 1, , ) <- y
    x[1,,]
    x[2,,]
    all.equal(asub(x, c(1,dimnames(y))), y) # TRUE
    # fill multiple slices
    x <- array(0, dim=c(2,4,3), dimnames=list(LETTERS[1:2], letters[1:4], LETTERS[24:26]))
    y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26]))
    afill(x, TRUE, , ) <- y
    x[1,,]
    x[2,,]
    all.equal(asub(x, c(1,dimnames(y))), y) # TRUE
    all.equal(asub(x, c(2,dimnames(y))), y) # TRUE

[Package abind version 1.4-5 Index]