magic (version 1.3-20)

adiag: Binds arrays corner-to-corner

Description

Array generalization of blockdiag()

Usage

adiag(... , pad=as.integer(0), do.dimnames=TRUE)

Arguments

...

Arrays to be binded together

pad

Value to pad array with; note default keeps integer status of arrays

do.dimnames

Boolean, with default TRUE meaning to return dimnames if possible. Set to FALSE if performance is an issue.

Value

• Returns an array of dimensions dim(a)+dim(b) as described above.

Details

Binds any number of arrays together, corner-to-corner. Because the function is associative, this page discusses the two array case.

Function adiag() requires length(dim(a))==length(dim(b)) (the function does not guess which dimensions have been dropped; see examples section). In particular, note that vectors are not coerced.

If x=adiag(a,b) and dim(a)=c(a_1,...,a_d), dim(b)=c(b_1,...,b_d); then all(dim(x)==dim(a)+dim(b)) and x[1:a_1,...,1:a_d]=a and x[(a_1+1):(a_1+b_1),...,(a_d+1):(a_d+b_d)]=b.

Dimnames are preserved, if both arrays have non-null dimnames, and do.dimnames is TRUE.

Argument pad is usually a scalar, but a vector is acceptable; standard recycling is used. Be aware that the output array (of dimension dim(a)+dim(b)) is filled with (copies of) pad before a and b are copied. This can be confusing.

See Also

subsums, apad

Examples

a <- array( 1,c(2,2))
 b <- array(-1,c(2,2))
 adiag(a,b)

 ##dropped dimensions can count:

 b2 <- b1 <- b
 dim(a) <- c(2,1,2)
 dim(b1) <- c(2,2,1)
 dim(b2) <- c(1,2,2)

 dim(adiag(a,b1))
 dim(adiag(a,b2))

##dimnames are preserved if not null:

a <- matrix(1,2,2,dimnames=list(col=c("red","blue"),size=c("big","small"))) 
b <- 8
dim(b) <- c(1,1)
dimnames(b) <- list(col=c("green"),size=c("tiny"))
adiag(a,b)   #dimnames preserved
adiag(a,8)   #dimnames lost because second argument has none.

##non scalar values for pad can be confusing:
q <- matrix(0,3,3)
adiag(q,q,pad=1:4)

##following example should make the pattern clear:
adiag(q,q,pad=1:36)



# Now, a use for arrays with dimensions of zero extent:
a <- matrix(1:9,3,3)
zero <- array(0,c(0,2))

adiag(a,zero)    # Observe how this has
                 # added no (ie zero) rows to a