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 Jose.Pinheiro@pharma.novartis.com and Douglas Bates
     bates@stat.wisc.edu

_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))

