R: Binds arrays corner-to-corner

adiag {magic} | R Documentation

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

### Details

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

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 length-one vector, but any 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.

### Value

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

### Note

In `adiag(a,b)`, if `a` is a length-one vector, it is coerced to an array of dimensions `rep(1,length(dim(b)))`; likewise `b`. If both `a` and `b` are length-one vectors, return `diag(c(a,b))`.

If `a` and `b` are arrays, 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 except if of length one.

`adiag()` is used when padding magic hypercubes in the context of evaluating subarray sums.

### Author(s)

Peter Wolf with some additions by Robin Hankin

### 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:
    z <- array(dim=c(0,3))
    colnames(z) <- c("foo","bar","baz")

    adiag(a,z)        # Observe how this has
                      # added no (ie zero) rows to "a" but
                      # three extra columns filled with the pad value

    adiag(a,t(z))
    adiag(z,t(z))     # just the pad value

[Package magic version 1.5-6 Index]