\HeaderA{pdNatural}{General Positive-Definite Matrix in Natural Parametrization}{pdNatural}
\keyword{models}{pdNatural}
\begin{Description}\relax
This function is a constructor for the \code{pdNatural} class,
representing a general positive-definite matrix, using a natural
parametrization . If the matrix associated with \code{object} is of
dimension \eqn{n}{}, it is represented by \eqn{n(n+1)/2}{n*(n+1)/2}
parameters. Letting \eqn{\sigma_{ij}}{S(i,j)} denote the \eqn{ij}{}-th
element of the underlying positive definite matrix and
\eqn{\rho_{ij}=\sigma_{i}/\sqrt{\sigma_{ii}\sigma_{jj}},\;i\neq j}{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
\eqn{\sqrt{\sigma_{ii}}, \;i=1,\ldots,n}{sqrt(Sii), i=1,..,n} and
\eqn{\log((1+\rho_{ij})/(1-\rho_{ij})),\; i \neq
j}{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 \code{value} is
\code{numeric(0)}, an uninitialized \code{pdMat} object, a one-sided
formula, or a vector of character strings, \code{object} is returned
as an uninitialized \code{pdSymm} object (with just some of its
attributes and its class defined) and needs to have its coefficients
assigned later, generally using the \code{coef} or \code{matrix} replacement
functions. If \code{value} is an initialized \code{pdMat} object,
\code{object} will be constructed from
\code{as.matrix(value)}. Finally, if \code{value} is a numeric 
vector, it is assumed to represent the natural parameters of the
underlying positive-definite matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
pdNatural(value, form, nam, data)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{value}] an optional initialization value, which can be any of the
following: a \code{pdMat} object, a positive-definite
matrix, a one-sided linear formula (with variables separated by
\code{+}), a vector of character strings, or a numeric
vector. Defaults to \code{numeric(0)}, corresponding to an
uninitialized object.
\item[\code{form}] an optional one-sided linear formula specifying the
row/column names for the matrix represented by \code{object}. Because
factors may be present in \code{form}, the formula needs to be
evaluated on a data.frame to resolve the names it defines. This
argument is ignored when \code{value} is a one-sided
formula. Defaults to \code{NULL}.
\item[\code{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
\code{value} is a vector of character strings. Defaults to
\code{NULL}.
\item[\code{data}] an optional data frame in which to evaluate the variables
named in \code{value} and \code{form}. It is used to
obtain the levels for \code{factors}, which affect the
dimensions and the row/column names of the underlying matrix. If
\code{NULL}, no attempt is made to obtain information on 
\code{factors} appearing in the formulas. Defaults to the
parent frame from which the function was called.
\end{ldescription}
\end{Arguments}
\begin{Value}
a \code{pdNatural} object representing a general positive-definite
matrix in natural parametrization, also inheriting from class
\code{pdMat}.
\end{Value}
\begin{Author}\relax
Jose Pinheiro \email{Jose.Pinheiro@pharma.novartis.com} and Douglas Bates \email{bates@stat.wisc.edu}
\end{Author}
\begin{References}\relax
Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models
in S and S-PLUS", Springer, esp. p. 162.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{as.matrix.pdMat}{as.matrix.pdMat}},
\code{\LinkA{coef.pdMat}{coef.pdMat}},
\code{\LinkA{pdClasses}{pdClasses}},
\code{\LinkA{matrix<\Rdash.pdMat}{matrix<.Rdash..pdMat}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
pdNatural(diag(1:3))
\end{ExampleCode}
\end{Examples}

