naginterfaces.library.linsys.real_​gen_​lsq_​covmat

naginterfaces.library.linsys.real_gen_lsq_covmat(job, sigma, a, svd, irank, sv)

real_gen_lsq_covmat returns elements of the estimated variance-covariance matrix of the sample regression coefficients for the solution of a linear least squares problem.

The function can be used to find the estimated variances of the sample regression coefficients.

For full information please refer to the NAG Library document for f04ya

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f04/f04yaf.html

Parameters

jobint

Specifies which elements of $C$ are required.

$job=-1$

The upper triangular part of $C$ is required.

$job=0$

The diagonal elements of $C$ are required.

$job>0$

The elements of column $job$ of $C$ are required.

sigmafloat

The standard error of the residual vector.

afloat, array-like, shape $(:,p)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $not\left(svd\right)\text{or}job=-1$: $p$; if $svd=True\text{and}job\ge 0$: $irank$; otherwise: $0$.

If $svd=False$, $a$ must contain the upper triangular matrix $U$ of the $QU$ factorization of $X$, or of the Cholesky factorization of $X^{T}X$; elements of the array below the diagonal need not be set.

If $svd=True$, $A$ must contain the first $k$ rows of the matrix $V^T$, where $k$ is the rank of $X$ and $V$ is the right-hand orthogonal matrix of the singular value decomposition of $X$.

Thus the $i$th row must contain the $i$th right-hand singular vector of $X$.

svdbool

Must be $True$ if the least squares solution was obtained from a singular value decomposition of $X$. $svd$ must be $False$ if the least squares solution was obtained from either a $QU$ factorization of $X$ or a Cholesky factorization of $X^{T}X$. In the latter case the rank of $X$ is assumed to be $p$ and so is applicable only to full rank problems with $n\ge p$.

irankint

If $svd=True$, $irank$ must specify the rank $k$ of the matrix $X$.

If $svd=False$, $irank$ is not referenced and the rank of $X$ is assumed to be $p$.

svfloat, array-like, shape $\left(p\right)$

If $svd=True$, $sv$ must contain the first $irank$ singular values of $X$.

If $svd=False$, $sv$ is not referenced.

Returns

afloat, ndarray, shape $(:,p)$

If $job\ge 0$, $A$ is unchanged.

If $job=-1$, $a$ contains the upper triangle of the symmetric matrix $C$.

If $svd=True$, elements of the array below the diagonal are used as workspace.

If $svd=False$, they are unchanged.

cjfloat, ndarray, shape $\left(p\right)$

If $job=0$, $cj$ returns the diagonal elements of $C$.

If $job=j>0$, $cj$ returns the $j$th column of $C$.

If $job=-1$, $cj$ is not referenced.

Raises

NagValueError

(errno $1$)

On entry, $\text{lda}=⟨value⟩$ and $p=⟨value⟩$.

Constraint: if $svd=False$, $\text{lda}\ge p$.

(errno $1$)

On entry, $\text{lda}=⟨value⟩$ and $p=⟨value⟩$.

Constraint: if $svd=True$ and $job=-1$, $\text{lda}\ge p$.

(errno $1$)

On entry, $job=⟨value⟩$, $\text{lda}=⟨value⟩$ and $irank=⟨value⟩$.

Constraint: if $svd=True$ and $job\ge 0$, $\text{lda}\ge max(1,irank)$.

(errno $1$)

On entry, $irank=⟨value⟩$ and $p=⟨value⟩$.

Constraint: if $svd=True$, $irank\ge 0$ and $irank\le p$.

(errno $1$)

On entry, $job=⟨value⟩$ and $p=⟨value⟩$.

Constraint: $job\ge -1$ and $job\le p$.

(errno $1$)

On entry, $sigma=⟨value⟩$.

Constraint: $sigma\ge 0.0$.

(errno $1$)

On entry, $p=⟨value⟩$.

Constraint: $p\ge 1$.

(errno $2$)

On entry, $irank=⟨value⟩$.

Constraint: if $svd=True$, $irank>0$.

(errno $3$)

On entry, $svd=False$ and overflow would occur in calculating an element of $C$. The upper triangular matrix $U$ must be very nearly singular.

(errno $4$)

On entry, $svd=False$ and one of the first $irank$ singular values is zero. Either the first $irank$ singular values or $irank$ must be incorrect: $irank=⟨value⟩$.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

The estimated variance-covariance matrix $C$ of the sample regression coefficients is given by

$$C={\sigma }^2{\left(X^{T}X\right)}^{-1},X^{T}X\text{nonsingular,}$$

where $X^{T}X$ is the normal matrix for the linear least squares regression problem

$$min:{\parallel y-Xb\parallel }_2\text{,}$$

${\sigma }^2$ is the estimated variance of the residual vector $r=y-Xb$, and $X$ is an $n\times p$ observation matrix.

When $X^{T}X$ is singular, $C$ is taken to be

$$C={\sigma }^2{\left(X^{T}X\right)}^{†}\text{,}$$

where ${\left(X^{T}X\right)}^{†}$ is the pseudo-inverse of $X^{T}X$; this assumes that the minimal least squares solution of (1) has been found.

The diagonal elements of $C$ are the estimated variances of the sample regression coefficients, $b$.

The function can be used to find either the diagonal elements of $C$, or the elements of the $j$th column of $C$, or the upper triangular part of $C$.

This function must be preceded by a function that returns either the upper triangular matrix $U$ of the $QU$ factorization of $X$ or of the Cholesky factorization of $X^{T}X$, or the singular values and right singular vectors of $X$. In particular this function can be preceded by one of the functions lapackeig.dgelss or real_gen_solve(), which return the arguments $irank$, $sigma$, $a$ and $sv$ in the required form. real_gen_solve() returns the argument $svd$, but when this function is used following function lapackeig.dgelss the argument $svd$ should be set to $True$. The argument $\text{p}$ of this function corresponds to the argument $\text{n}$ in functions lapackeig.dgelss and real_gen_solve().

References

Anderson, T W, 1958, An Introduction to Multivariate Statistical Analysis, Wiley

Lawson, C L and Hanson, R J, 1974, Solving Least Squares Problems, Prentice–Hall