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

Arguments

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

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 efficie

value

A vector or array, with dimension names that match some dimensions of
    x

`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

`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`

Run this code# fill a submatrix
(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
# 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,,]
# 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,,]
Run the code above in your browser using DataLab