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