pdBlocked                package:nlme                R Documentation

Positive-Definite Block Diagonal Matrix

Description:

     This function is a constructor for the 'pdBlocked' class,
     representing a positive-definite block-diagonal matrix. Each
     block-diagonal element of the underlying  matrix is itself a
     positive-definite matrix and is represented internally as an
     individual 'pdMat' object. When 'value' is 'numeric(0)', a list of
     uninitialized 'pdMat' objects, a list of one-sided formulas, or a
     list of vectors  of character strings,  'object' is returned as an
     uninitialized 'pdBlocked' object (with just some of its attributes
     and its class defined) and needs to have its coefficients assigned
     later, generally using the 'coef' or 'matrix' replacement
     functions. If 'value' is a list of  initialized 'pdMat' objects,
     'object' will be constructed from the list obtained by applying
     'as.matrix' to each of the 'pdMat' elements of 'value'. Finally,
     if 'value' is a list of numeric vectors, they are assumed to
     represent the unrestricted coefficients of the block-diagonal
     elements of the  underlying positive-definite matrix.

Usage:

     pdBlocked(value, form, nam, data, pdClass)

Arguments:

   value: an optional list with elements to be used as the 'value'
          argument to other 'pdMat' constructors. These include:
          'pdMat' objects, positive-definite matrices, one-sided linear
          formulas, vectors of character strings, or numeric vectors.
          All elements in the list must be similar (e.g. all one-sided
          formulas, or all numeric vectors). Defaults to 'numeric(0)',
          corresponding to an uninitialized object.

    form: an optional list of one-sided linear formulas specifying the
          row/column names for the block-diagonal elements of the
          matrix represented by 'object'. Because factors may be
          present in 'form', the formulas needs to be evaluated on a
          data.frame to resolve the names they define. This argument is
          ignored when 'value' is a list of one-sided formulas.
          Defaults to 'NULL'.

     nam: an optional list of vector of character strings specifying
          the row/column names for the block-diagonal elements of the
          matrix represented by object. Each of its components must
          have   length equal to the dimension of the corresponding
          block-diagonal element and unreplicated elements. This
          argument is ignored when  'value' is a list of vector of
          character strings. Defaults to  'NULL'.

    data: an optional data frame in which to evaluate the variables
          named in 'value' and 'form'. It is used to obtain the levels
          for 'factors', which affect the dimensions and the row/column
          names of the underlying matrix. If 'NULL', no attempt is made
          to obtain information on any 'factors' appearing in the
          formulas. Defaults to the parent frame from which the
          function was called.

 pdClass: an optional vector of character strings naming the 'pdMat'
          classes to be assigned to the individual blocks in the
          underlying matrix. If a single class is specified, it is used
          for all block-diagonal elements. This argument will only be
          used when 'value' is missing, or its elements are not 'pdMat'
          objects. Defaults to '"pdSymm"'.

Value:

     a 'pdBlocked' object representing a positive-definite
     block-diagonal matrix, also inheriting from class 'pdMat'.

Author(s):

     Jose Pinheiro Jose.Pinheiro@pharma.novartis.com and Douglas Bates
     bates@stat.wisc.edu

References:

     Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models in S
     and S-PLUS", Springer, esp. p. 162.

See Also:

     'as.matrix.pdMat', 'coef.pdMat', 'pdClasses', 'matrix<-.pdMat'

Examples:

     pd1 <- pdBlocked(list(diag(1:2), diag(c(0.1, 0.2, 0.3))),
                      nam = list(c("A","B"), c("a1", "a2", "a3")))
     pd1

