# pdNatural

##### General Positive-Definite Matrix in Natural Parametrization

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 \(\sigma_{ij}\) denote the \(ij\)-th
element of the underlying positive definite matrix and
\(\rho_{ij}=\sigma_{i}/\sqrt{\sigma_{ii}\sigma_{jj}},\;i\neq j\) denote the associated
"correlations", the "natural" parameters are given by
\(\sqrt{\sigma_{ii}}, \;i=1,\ldots,n\) and
\(\log((1+\rho_{ij})/(1-\rho_{ij})),\; i \neq
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.

- Keywords
- models

##### Usage

`pdNatural(value, form, nam, data)`

##### Arguments

- 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.

##### Value

a `pdNatural`

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

.

##### References

Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models in S and S-PLUS", Springer, esp. p. 162.

##### See Also

##### Examples

```
# NOT RUN {
pdNatural(diag(1:3))
# }
```

*Documentation reproduced from package nlme, version 3.1-145, License: GPL (>= 2) | file LICENCE*