## File: afill.Rd

package info (click to toggle)
abind 1.4-5-1
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151 \name{afill} \alias{afill} \alias{afill<-} \alias{afill<-.default} %- Also NEED an '\alias' for EACH other topic documented here. \title{ Fill an array with subarrays } \description{ Fill an array with subarrays. \code{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. \code{afill()} is a S3 generic, with one method, \code{afill.default}, supplied in the \code{abind} package. } \usage{ afill(x, ..., excess.ok = FALSE, local = TRUE) <- value } %- maybe also 'usage' for other objects documented here. \arguments{ \item{x}{ An array to be changed } \item{\dots}{ Arguments that specify indices for \code{x}. If \code{length(dim(value)) < length(dim(x))}, then exactly \code{length(dim(x))} anonymous arguments must be supplied, with empty ones corresponding to dimensions of \code{x} that are supplied in \code{value}. } \item{excess.ok}{ If there are elements of the dimensions of \code{value} that are not found in the corresponding dimensions of x, they will be discarded if \code{excess.ok=TRUE}.} \item{local}{ Should the assignment be done in on a copy of x, and the result returned (normal behavior). If \code{local=FALSE} the assignment will be done directly on the actual argument supplied as \code{x}, which can be more space efficient.} \item{value}{ A vector or array, with dimension names that match some dimensions of \code{x} } } \details{ The simplest use of \code{afill} is to fill a sub-matrix. Here is an example of this usage: \preformatted{ > (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 \preformatted{ > x[match(rownames(y), rownames(x)), match(colnames(y), colnames(x))] <- y } A more complex usage of \code{afill} is to fill a sub-matrix in a slice of a higher-dimensional array. In this case, indices for \code{x} must be supplied as arguments to \code{afill}, with the dimensions corresponding to those of \code{value} being empty, e.g.: \preformatted{ > 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 \code{afill} is to fill a sub-matrix in multiple slice of a higher-dimensional array. Again, indices for \code{x} must be supplied as arguments to \code{afill}, with the dimensions corresponding to those of \code{value} being empty. Indices in which all slices should be filled can be supplied as \code{TRUE}. E.g.: \preformatted{ > 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, \code{afill} takes care of replicating \code{value} in the appropriate fashion (which is not straghtforward in some cases). } \value{ The object \code{x} is changed. The return value of the assignment is the parts of the object \code{x} that are changed. This is similar to how regular subscript-replacement behaves, e.g., the expression \code{x[2:3] <- 1:2} returns the vector \code{1:2}, not the entire object \code{x}. However, note that there can be differences } % \references{ ~put references to the literature/web site here ~ } \author{Tony Plate \email{tplate@acm.org}} % \note{ ~~further notes~~ } \seealso{ \code{\link{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 } \keyword{ manip } \keyword{ array }