__Title__

**[P] _getcovcorr** -- Programmer's utility for parsing correlation and
covariance matrix options

__Syntax__

**_getcovcorr** *matname* [ **,** *options* ]

*options* Description
-------------------------------------------------------------------------
__cor__**relation** return a correlation matrix
__cov__**ariance** return a covariance matrix
__sh__**ape(***shape***)** shape (storage method) of *matname*
__nam__**es(***namelist***)** namelist; required with vectorized input
**sds(***vector***)** vector of standard deviations
__me__**ans(***vector***)** vector of means
**force** fixes input problems in names (see below)
**check(***pd***)** checks that *matname* is positive definite
**check(***psd***)** checks that *matname* is positive semidefinite
**forcepsd** modifies *matname* to be positive semidefinite
**tol(***#***)** tolerance for checking eigenvalues (see below)
-------------------------------------------------------------------------

*shape* *matname* is stored as a
-------------------------------------------------------------------------
__f__**ull** square symmetric matrix
__l__**ower** vector of rowwise lower triangle (with diagonal)
__u__**pper** vector of rowwise lower triangle (with diagonal)
-------------------------------------------------------------------------

__Description__

**_getcovcorr** processes the options related to correlation or covariance
matrices, checks for errors, and returns the information in standard form
in **r()**. The options processed by **_getcovcorr** allow users to specify the
correlation or covariance matrix *matname* in several ways. It can be a
square symmetric matrix, or a vector representing the lower or upper
triangle of the matrix.

__Options__

**correlation** and **covariance** declare that a correlation or covariance
matrix is to be returned in **r(C)** and that **r(Ctype)** is to be set to
"**correlation**" or "**covariance**", respectively.

By default, if *matname* represents a correlation matrix, a correlation
matrix will be returned. Likewise, if *matname* represents a
covariance matrix, a covariance matrix will be returned. **correlation**
and **covariance** may be used to override the default.

If *matname* represents a correlation matrix, and you specify the
**covariance** option, then you must also provide the standard deviations
with the **sds()** option.

**shape(***mode***)** specifies the shape or storage method for the covariance or
correlation matrix *matname*. The following storage methods are
supported:

**full** specifies that *matname* is stored as a symmetric *k*x*k* matrix.

**lower** specifies that *matname* is stored in a vector in rowwise
lower-triangle order. The vector is verified to have *k*(*k*+1)/2
elements (representing *k* variables), and are placed in the
following order:

C(11) C(21) C(22) C(31) C(32) C(33) ... C(*k*1) C(*k*2) ... C(*kk*)

**upper** specifies that *matname* is recorded in a vector in rowwise
upper-triangle order. The vector is verified to have *k*(*k*+1)/2
elements (representing *k* variables), and are placed in the
following order:

C(11) C(12) C(13) ... C(1*k*) C(22) C(23) ... C(2*k*) ...
C(*k*-1*k*-1) C(*k*-1*k*) C(*kk*)

Specifying **shape(full)** is optional if *matname* is square. Specifying
either **shape(lower)** or **shape(upper)** is required for the vectorized
storage methods. See storage modes for examples.

**names(***namelist***)** specifies a list of *k* different names for the row and
column names of **r(C)**. **names()** is required with **cstorage(lower)** or
**cstorage(upper)**. **names()** implies **force**.

**sds(***vector***)**, a row or column vector with *k* positive elements, specifies
the standard deviations, and is allowed only when *matname* is
represented as a correlation matrix. The standard deviations are
returned in the row vector **r(sds)**.

**means(***vector***)**, a row or column vector with *k* elements, specifies the
means corresponding with the correlation or covariance matrix. This
is not used in the construction of **r(C)**, but is checked for
conformability. The means are returned in the row vector **r(means)**.

**force** suppresses the check that matrix name stripes match. The option
**names()** automatically implies **force**.

**check(***opt***)** specifies a check to be performed on *matname*.

**pd** verifies that *matname* is positive definite; that is, all
eigenvalues are "really positive" (see option **tol()**).

**psd** verifies that *matname* is positive semidefinite; that is, none of
the eigenvalues of *matname* are "really negative" (see option
**tol()**).

**forcepsd** makes sure that *matname* is positive semidefinite by replacing
negative eigenvalues with 0. The number of "really negative"
eigenvalues is reported.

**tol(***tol***)** specifies a tolerance for classifying the sign of an eigenvalue
*ev* as

really positive *ev* > *etol*
really negative *ev* < -*etol*
possibly 0 -*etol* <= *ev* <= *etol*
where *etol* = *tol***mev*, with *mev* the maximum absolute eigenvalue of
*matname*.

__Remarks__

**_getcovcorr** does the following.

1. If *matname* is a vector, the corresponding full symmetric matrix is
constructed. This matrix may represent either a covariance or
correlation matrix.

2. From the input covariance or correlation matrix one of the following
is constructed.

A. A correlation matrix (if **correlation** was specified).

B. A covariance matrix (if **covariance** was specified). If *matname*
represents a correlation matrix, then a covariance is constructed
from *matname* using the standard deviations provided by **sds()**.

The resulting matrix is checked for symmetry and that diagonal
elements are strictly positive (1 if **correlation**).

3. An error message is produced if *matname*, **sds()**, or **means()** contain
missing values or are not conformable. Unless **force** or **names()** are
specified, an error is also produced if the name stripes do not
agree.

4. **r(means)** and **r(sds)** are returned as row vectors if **means()** and **sds()**
are specified.

__Stored results__

**_getcovcorr** stores in **r()**:

Macro
**r(Ctype)** **correlation** or **covariance**

Matrices
**r(C)** the correlation or covariance matrix
**r(sds)** vector of std deviations (if **sds()** specified)
**r(means)** vector of means (if **means()** specified)

Scalars
**r(npos)** number of positive eigenvalues of C