pdNatural                package:nlme                R Documentation

_G_e_n_e_r_a_l _P_o_s_i_t_i_v_e-_D_e_f_i_n_i_t_e _M_a_t_r_i_x _i_n _N_a_t_u_r_a_l _P_a_r_a_m_e_t_r_i_z_a_t_i_o_n

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

     This function is a constructor for the `pdNatural' class,
     representing a general positive-definite matrix, using a natural
     parametrization . If the matrix associated with `object' is of
     dimension n, it is represented by n*(n+1)/2 parameters. Letting
     S(i,j) denote the ij-th element of the underlying positive
     definite matrix and r(i,j) = S(i,j)/sqrt(S(i,i)S(j,j)), i not
     equal to j denote the associated "correlations", the "natural"
     parameters are given by sqrt(Sii), i=1,..,n and
     log((1+r(i,j))/(1-r(i,j))), i not equal to j. Note that all
     natural parameters are individually unrestricted, but not jointly
     unrestricted (meaning that not all unrestricted vectors would give
     positive-definite matrices). Therefore, this parametrization
     should NOT be used for optimization. It is mostly used for
     deriving approximate confidence intervals on parameters following
     the optimization of an objective function. When `value' is
     `numeric(0)', an uninitialized `pdMat' object, a one-sided
     formula, or a vector of character strings, `object' is returned as
     an uninitialized `pdSymm' 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 an initialized `pdMat' object, `object'
     will be constructed from `as.matrix(value)'. Finally, if `value'
     is a numeric  vector, it is assumed to represent the natural
     parameters of the underlying positive-definite matrix.

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

     pdNatural(value, form, nam, data)

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

   value: an optional initialization value, which can be any of the
          following: a `pdMat' object, a positive-definite matrix, a
          one-sided linear formula (with variables separated by `+'), a
          vector of character strings, or a numeric vector. Defaults to
          `numeric(0)', corresponding to an uninitialized object.

    form: an optional one-sided linear formula specifying the
          row/column names for the matrix represented by `object'.
          Because factors may be present in `form', the formula needs
          to be evaluated on a data.frame to resolve the names it
          defines. This argument is ignored when `value' is a one-sided
          formula. Defaults to `NULL'.

     nam: an optional vector of character strings specifying the
          row/column names for the matrix represented by object. It
          must have  length equal to the dimension of the underlying
          positive-definite matrix and unreplicated elements. This
          argument is ignored when `value' is a 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  `factors' appearing in the
          formulas. Defaults to the parent frame from which the
          function was called.

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

     a `pdNatural' object representing a general positive-definite
     matrix in natural parametrization, also inheriting from class
     `pdMat'.

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

     Jose Pinheiro and Douglas Bates

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

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

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

     pdNatural(diag(1:3))

