

   GGeenneerraall PPoossiittiivvee--DDeeffiinniittee MMaattrriixx iinn NNaattuurraall PPaarraammeettrriizzaattiioonn

        pdNatural(value, form, nam, data)

   AArrgguummeennttss::

      value: an optional initialization value, which can be any
             of the following: a code{pdMat} object, a posi-
             tive-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 the
             random effects model. Defaults to parent frame
             from which the function was called.

   DDeessccrriippttiioon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}
        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.

   VVaalluuee::

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

   AAuutthhoorr((ss))::

        Jose Pinheiro and Douglas Bates

   SSeeee AAllssoo::

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

   EExxaammpplleess::

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

