Stata 15 help for _getcovcorr

Title

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

Syntax

_getcovcorr matname [ , options ]

options Description ------------------------------------------------------------------------- correlation return a correlation matrix covariance return a covariance matrix shape(shape) shape (storage method) of matname names(namelist) namelist; required with vectorized input sds(vector) vector of standard deviations means(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 ------------------------------------------------------------------------- full square symmetric matrix lower vector of rowwise lower triangle (with diagonal) upper 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 kxk 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(k1) C(k2) ... 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(1k) C(22) C(23) ... C(2k) ... C(k-1k-1) C(k-1k) 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


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index