NAG FL Interface
g02byf (corrmat_partial)
1
Purpose
g02byf computes a partial correlation/variancecovariance matrix from a correlation or variancecovariance matrix computed by
g02bxf.
2
Specification
Fortran Interface
Integer, Intent (In) 
:: 
m, ny, nx, isz(m), ldr, ldp 
Integer, Intent (Inout) 
:: 
ifail 
Real (Kind=nag_wp), Intent (In) 
:: 
r(ldr,m) 
Real (Kind=nag_wp), Intent (Inout) 
:: 
p(ldp,ny) 
Real (Kind=nag_wp), Intent (Out) 
:: 
wk(ny*nx+nx*(nx+1)/2) 

C Header Interface
#include <nag.h>
void 
g02byf_ (const Integer *m, const Integer *ny, const Integer *nx, const Integer isz[], const double r[], const Integer *ldr, double p[], const Integer *ldp, double wk[], Integer *ifail) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
g02byf_ (const Integer &m, const Integer &ny, const Integer &nx, const Integer isz[], const double r[], const Integer &ldr, double p[], const Integer &ldp, double wk[], Integer &ifail) 
}

The routine may be called by the names g02byf or nagf_correg_corrmat_partial.
3
Description
Partial correlation can be used to explore the association between pairs of random variables in the presence of other variables. For three variables,
${y}_{1}$,
${y}_{2}$ and
${x}_{3}$, the partial correlation coefficient between
${y}_{1}$ and
${y}_{2}$ given
${x}_{3}$ is computed as:
where
${r}_{ij}$ is the productmoment correlation coefficient between variables with subscripts
$i$ and
$j$. The partial correlation coefficient is a measure of the linear association between
${y}_{1}$ and
${y}_{2}$ having eliminated the effect due to both
${y}_{1}$ and
${y}_{2}$ being linearly associated with
${x}_{3}$. That is, it is a measure of association between
${y}_{1}$ and
${y}_{2}$ conditional upon fixed values of
${x}_{3}$. Like the full correlation coefficients the partial correlation coefficient takes a value in the range (
$1,1$) with the value
$0$ indicating no association.
In general, let a set of variables be partitioned into two groups
$Y$ and
$X$ with
${n}_{y}$ variables in
$Y$ and
${n}_{x}$ variables in
$X$ and let the variancecovariance matrix of all
${n}_{y}+{n}_{x}$ variables be partitioned into,
The variancecovariance of
$Y$ conditional on fixed values of the
$X$ variables is given by:
The partial correlation matrix is then computed by standardizing
${\Sigma}_{y\mid x}$,
To test the hypothesis that a partial correlation is zero under the assumption that the data has an approximately Normal distribution a test similar to the test for the full correlation coefficient can be used. If
$r$ is the computed partial correlation coefficient then the appropriate
$t$ statistic is
which has approximately a Student's
$t$distribution with
$n{n}_{x}2$ degrees of freedom, where
$n$ is the number of observations from which the full correlation coefficients were computed.
4
References
Krzanowski W J (1990) Principles of Multivariate Analysis Oxford University Press
Morrison D F (1967) Multivariate Statistical Methods McGraw–Hill
Osborn J F (1979) Statistical Exercises in Medical Research Blackwell
Snedecor G W and Cochran W G (1967) Statistical Methods Iowa State University Press
5
Arguments

1:
$\mathbf{m}$ – Integer
Input

On entry: the number of variables in the variancecovariance/correlation matrix given in
r.
Constraint:
${\mathbf{m}}\ge 3$.

2:
$\mathbf{ny}$ – Integer
Input

On entry: the number of $Y$ variables, ${n}_{y}$, for which partial correlation coefficients are to be computed.
Constraint:
${\mathbf{ny}}\ge 2$.

3:
$\mathbf{nx}$ – Integer
Input

On entry: the number of $X$ variables, ${n}_{x}$, which are to be considered as fixed.
Constraints:
 ${\mathbf{nx}}\ge 1$;
 ${\mathbf{ny}}+{\mathbf{nx}}\le {\mathbf{m}}$.

4:
$\mathbf{isz}\left({\mathbf{m}}\right)$ – Integer array
Input

On entry: indicates which variables belong to set
$X$ and
$Y$.
 ${\mathbf{isz}}\left(i\right)<0$
 The
$\mathit{i}$th variable is a $Y$ variable, for $\mathit{i}=1,2,\dots ,{\mathbf{m}}$.
 ${\mathbf{isz}}\left(i\right)>0$
 The $i$th variable is a $X$ variable.
 ${\mathbf{isz}}\left(i\right)=0$
 The $i$th variable is not included in the computations.
Constraints:
 exactly ny elements of isz must be $\text{}<0$;
 exactly nx elements of isz must be $\text{}>0$.

5:
$\mathbf{r}\left({\mathbf{ldr}},{\mathbf{m}}\right)$ – Real (Kind=nag_wp) array
Input

On entry: the variancecovariance or correlation matrix for the
m variables as given by
g02bxf. Only the upper triangle need be given.
Note: the matrix must be a full rank variancecovariance or correlation matrix and so be positive definite. This condition is not directly checked by the routine.

6:
$\mathbf{ldr}$ – Integer
Input

On entry: the first dimension of the array
r as declared in the (sub)program from which
g02byf is called.
Constraint:
${\mathbf{ldr}}\ge {\mathbf{m}}$.

7:
$\mathbf{p}\left({\mathbf{ldp}},{\mathbf{ny}}\right)$ – Real (Kind=nag_wp) array
Output

On exit: the strict upper triangle of
p contains the strict upper triangular part of the
${n}_{y}$ by
${n}_{y}$ partial correlation matrix. The lower triangle contains the lower triangle of the
${n}_{y}$ by
${n}_{y}$ partial variancecovariance matrix if the matrix given in
r is a variancecovariance matrix. If the matrix given in
r is a partial correlation matrix then the variancecovariance matrix is for standardized variables.

8:
$\mathbf{ldp}$ – Integer
Input

On entry: the first dimension of the array
p as declared in the (sub)program from which
g02byf is called.
Constraint:
${\mathbf{ldp}}\ge {\mathbf{ny}}$.

9:
$\mathbf{wk}\left({\mathbf{ny}}\times {\mathbf{nx}}+{\mathbf{nx}}\times \left({\mathbf{nx}}+1\right)/2\right)$ – Real (Kind=nag_wp) array
Workspace


10:
$\mathbf{ifail}$ – Integer
Input/Output

On entry:
ifail must be set to
$0$,
$1$ or
$1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value
$1$ or
$1$ is recommended. If message printing is undesirable, then the value
$1$ is recommended. Otherwise, the value
$0$ is recommended.
When the value $\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{ldp}}=\u2329\mathit{\text{value}}\u232a$ ${\mathbf{ny}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{ldp}}\ge {\mathbf{ny}}$.
On entry, ${\mathbf{ldr}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{m}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{ldr}}\ge {\mathbf{m}}$.
On entry, ${\mathbf{m}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{m}}>2$.
On entry, ${\mathbf{nx}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nx}}\ge 1$.
On entry, ${\mathbf{ny}}=\u2329\mathit{\text{value}}\u232a$, ${\mathbf{nx}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{m}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{ny}}+{\mathbf{nx}}\le {\mathbf{m}}$.
On entry, ${\mathbf{ny}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{ny}}>1$.
 ${\mathbf{ifail}}=2$

On entry,
$\u2329\mathit{\text{value}}\u232a$ values of
isz are greater than zero and
${\mathbf{nx}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: exactly
nx values of
isz must be greater than zero.
On entry,
$\u2329\mathit{\text{value}}\u232a$ values of
isz are less than zero and
${\mathbf{ny}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: exactly
ny values of
isz must be less than zero.
 ${\mathbf{ifail}}=3$

On entry, the correlation matrix of the independent variables is singular.
Try removing some of the $X$ variables by setting the appropriate element of ${\mathbf{isz}}=0$.
On entry, the square root of the correlation matrix of the independent variables is singular.
Try removing some of the $X$ variables by setting the appropriate element of ${\mathbf{isz}}=0$.
 ${\mathbf{ifail}}=4$

On entry, a diagonal element of the partial covariance matrix is zero.
Constraint:
r must be positive definite.
On entry, a diagonal element of the partial covariance matrix is zero and an element of the partial correlation matrix is greater than
$1$.
Constraint:
r must be positive definite.
On entry, an element of the partial correlation matrix is greater than
$1$.
Constraint:
r must be positive definite.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
g02byf computes the partial variancecovariance matrix,
${\Sigma}_{y\mid x}$, by computing the Cholesky factorization of
${\Sigma}_{xx}$. If
${\Sigma}_{xx}$ is not of full rank the computation will fail. For a statement on the accuracy of the Cholesky factorization see
f07gdf.
8
Parallelism and Performance
g02byf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g02byf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
Models that represent the linear associations given by partial correlations can be fitted using the multiple regression routine
g02daf.
10
Example
Data, given by
Osborn (1979), on the number of deaths, smoke (
$\mathrm{mg}/{\mathrm{m}}^{3}$) and sulphur dioxide (parts/million) during an intense period of fog is input. The correlations are computed using
g02bxf and the partial correlation between deaths and smoke given sulphur dioxide is computed using
g02byf. Both correlation matrices are printed using the routine
x04caf.
10.1
Program Text
10.2
Program Data
10.3
Program Results