adiag                 package:magic                 R Documentation

_B_i_n_d_s _a_r_r_a_y_s _c_o_r_n_e_r-_t_o-_c_o_r_n_e_r

_D_e_s_c_r_i_p_t_i_o_n:

     Array generalization of blockdiag()

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

     ...: Arrays to be binded together

     pad: Value to pad array with

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

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

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

_N_o_t_e:

     In 'adiag(a,b)', if 'a' is a scalar, it is coerced into being an
     array of dimensions 'rep(1,length(dim(b)))'; likewise 'b'.  If
     both 'a' and 'b' are scalars, return 'diag(c(a,b))'.

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

_A_u_t_h_o_r(_s):

     Peter Wolf with some additions by Robin Hankin

_S_e_e _A_l_s_o:

     'subsums'

_E_x_a_m_p_l_e_s:

      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)

