abind (version 1.4-8)

afill: 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

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

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

Author

Tony Plate

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

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