

pdNatural(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 associ-
     ated 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 deriv-
     ing approximate confidence intervals on parameters fol-
     lowing 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 parame-
     ters 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 inher-
     iting 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_:

     library(nlme)
     pdNatural(diag(1:3))

