Settings help

CL Name Style:

## 1Purpose

g03adc performs canonical correlation analysis upon input data matrices.

## 2Specification

 #include
 void g03adc (Integer n, Integer m, const double z[], Integer tdz, const Integer isz[], Integer nx, Integer ny, const double wt[], double e[], Integer tde, Integer *ncv, double cvx[], Integer tdcvx, double cvy[], Integer tdcvy, double tol, NagError *fail)
The function may be called by the names: g03adc or nag_mv_canon_corr.

## 3Description

Let there be two sets of variables, $x$ and $y$. For a sample of $n$ observations on ${n}_{x}$ variables in a data matrix $X$ and ${n}_{y}$ variables in a data matrix $Y$, canonical correlation analysis seeks to find a small number of linear combinations of each set of variables in order to explain or summarise the relationships between them. The variables thus formed are known as canonical variates.
Let the variance-covariance matrix of the two datasets be
 $( S xx S xy S yx S yy )$
and let
 $Σ = S yy −1 S yx S xx −1 S xy$
then the canonical correlations can be calculated from the eigenvalues of the matrix $\Sigma$. However, g03adc calculates the canonical correlations by means of a singular value decomposition (SVD) of a matrix $V$. If the rank of the data matrix $X$ is ${k}_{x}$ and the rank of the data matrix $Y$ is ${k}_{y}$, and both $X$ and $Y$ have had variable (column) means subtracted, then the ${k}_{x}×{k}_{y}$ matrix $V$ is given by:
 $V = QxT Q y ,$
where ${Q}_{x}$ is the first ${k}_{x}$ rows of the orthogonal matrix $Q$ either from the $QR$ decomposition of $X$ if $X$ is of full column rank, i.e., ${k}_{x}={n}_{x}$:
 $X = Q x R x$
or from the SVD of $X$ if ${k}_{x}<{n}_{x}$:
 $X = Q x D x PxT .$
Similarly ${Q}_{y}$ is the first ${k}_{y}$ rows of the orthogonal matrix $Q$ either from the $QR$ decomposition of $Y$ if $Y$ is of full column rank, i.e., ${k}_{y}={n}_{y}$:
 $Y = Q y R y$
or from the SVD of $Y$ if ${k}_{y}<{n}_{y}$:
 $Y = Q y D y PyT .$
Let the SVD of $V$ be:
 $V = U x Δ UyT$
then the nonzero elements of the diagonal matrix $\Delta$, ${\delta }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,l$, are the $l$ canonical correlations associated with the $l$ canonical variates, where $l=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({k}_{x},{k}_{y}\right)$.
The eigenvalues, ${\lambda }_{i}^{2}$, of the matrix $\Sigma$ are given by:
 $λ i 2 = δ i 2 1 + δ i 2 .$
The value of ${\pi }_{i}={\lambda }_{i}^{2}/\sum {\lambda }_{i}^{2}$ gives the proportion of variation explained by the $i$th canonical variate. The values of the ${\pi }_{i}$ give an indication as to how many canonical variates are needed to adequately describe the data, i.e., the dimensionality of the problem.
To test for a significant dimensionality greater than $i$ the ${\chi }^{2}$ statistic:
 $(n- 1 2 ( k x + k y +3)) ∑ j = i + 1 l log(1+ λ j 2 )$
can be used. This is asymptotically distributed as a ${\chi }^{2}$ distribution with $\left({k}_{x}-i\right)\left({k}_{y}-i\right)$ degrees of freedom. If the test for $i={k}_{\mathrm{min}}$ is not significant, then the remaining tests for $i>{k}_{\mathrm{min}}$ should be ignored.
The loadings for the canonical variates are calculated from the matrices ${U}_{x}$ and ${U}_{y}$ respectively. These matrices are scaled so that the canonical variates have unit variance.
Chatfield C and Collins A J (1980) Introduction to Multivariate Analysis Chapman and Hall
Kendall M G and Stuart A (1976) The Advanced Theory of Statistics (Volume 3) (3rd Edition) Griffin
Morrison D F (1967) Multivariate Statistical Methods McGraw–Hill

## 5Arguments

1: $\mathbf{n}$Integer Input
On entry: the number of observations, $n$.
Constraint: ${\mathbf{n}}>{\mathbf{nx}}+{\mathbf{ny}}$.
2: $\mathbf{m}$Integer Input
On entry: the total number of variables, $m$.
Constraint: ${\mathbf{m}}\ge {\mathbf{nx}}+{\mathbf{ny}}$.
3: $\mathbf{z}\left[{\mathbf{n}}×{\mathbf{tdz}}\right]$const double Input
On entry: ${\mathbf{z}}\left[\left(\mathit{i}-1\right)×{\mathbf{tdz}}+\mathit{j}-1\right]$ must contain the $\mathit{i}$th observation for the $\mathit{j}$th variable, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2,\dots ,m$.
Both $x$ and $y$ variables are to be included in z, the indicator array, isz, being used to assign the variables in z to the $x$ or $y$ sets as appropriate.
4: $\mathbf{tdz}$Integer Input
On entry: the stride separating matrix column elements in the array z.
Constraint: ${\mathbf{tdz}}\ge {\mathbf{m}}$.
5: $\mathbf{isz}\left[{\mathbf{m}}\right]$const Integer Input
On entry: ${\mathbf{isz}}\left[j-1\right]$ indicates whether or not the $j$th variable is to be included in the analysis and to which set of variables it belongs.
If ${\mathbf{isz}}\left[j-1\right]>0$, then the variable contained in the $j$th column of z is included as an $x$ variable in the analysis.
If ${\mathbf{isz}}\left[j-1\right]<0$, then the variable contained in the $j$th column of z is included as a $y$ variable in the analysis.
If ${\mathbf{isz}}\left[j-1\right]=0$, then the variable contained in the $j$th column of z is not included in the analysis.
Constraint: only nx elements of isz can be $>0$ and only ny elements of isz can be $<0$.
6: $\mathbf{nx}$Integer Input
On entry: the number of $x$ variables in the analysis, ${n}_{x}$.
Constraint: ${\mathbf{nx}}\ge 1$.
7: $\mathbf{ny}$Integer Input
On entry: the number of $y$ variables in the analysis, ${n}_{y}$.
Constraint: ${\mathbf{ny}}\ge 1$.
8: $\mathbf{wt}\left[{\mathbf{n}}\right]$const double Input
On entry: the elements of wt must contain the weights to be used in the analysis. The effective number of observations is the sum of the weights. If ${\mathbf{wt}}\left[i-1\right]=0.0$ then the $i$th observation is not included in the analysis.
If weights are not provided then wt must be set to NULL and the effective number of observations is n.
Constraints:
• if wt is not NULL, ${\mathbf{wt}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n$;
• ${\sum }_{i=1}^{n}{\mathbf{wt}}\left[i-1\right]\ge {\mathbf{nx}}+{\mathbf{ny}}+1$.
9: $\mathbf{e}\left[\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{nx}},{\mathbf{ny}}\right)×{\mathbf{tde}}\right]$double Output
On exit: the statistics of the canonical variate analysis. ${\mathbf{e}}\left[\left(\mathit{i}-1\right)×{\mathbf{tde}}\right]$, the canonical correlations, ${\delta }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,l$.
${\mathbf{e}}\left[\left(i-1\right)×{\mathbf{tde}}+1\right]$, the eigenvalues of $\Sigma$, ${\lambda }_{\mathit{i}}^{2}$, for $\mathit{i}=1,2,\dots ,l$.
${\mathbf{e}}\left[\left(\mathit{i}-1\right)×{\mathbf{tde}}+2\right]$, the proportion of variation explained by the $\mathit{i}$th canonical variate, for $\mathit{i}=1,2,\dots ,l$.
${\mathbf{e}}\left[\left(i-1\right)×{\mathbf{tde}}+3\right]$, the ${\chi }^{2}$ statistic for the $\mathit{i}$th canonical variate, for $\mathit{i}=1,2,\dots ,l$.
${\mathbf{e}}\left[\left(i-1\right)×{\mathbf{tde}}+4\right]$, the degrees of freedom for ${\chi }^{2}$ statistic for the $\mathit{i}$th canonical variate, for $\mathit{i}=1,2,\dots ,l$.
${\mathbf{e}}\left[\left(i-1\right)×{\mathbf{tde}}+5\right]$, the significance level for the ${\chi }^{2}$ statistic for the $\mathit{i}$th canonical variate, for $\mathit{i}=1,2,\dots ,l$.
10: $\mathbf{tde}$Integer Input
On entry: the stride separating matrix column elements in the array e.
Constraint: ${\mathbf{tde}}\ge 6$.
11: $\mathbf{ncv}$Integer * Output
On exit: the number of canonical correlations, $l$. This will be the minimum of the rank of $X$ and the rank of $Y$.
12: $\mathbf{cvx}\left[{\mathbf{nx}}×{\mathbf{tdcvx}}\right]$double Output
On exit: the canonical variate loadings for the $x$ variables. ${\mathbf{cvx}}\left[\left(i-1\right)×{\mathbf{tdcvx}}+j-1\right]$ contains the loading coefficient for the $i$th $x$ variable on the $j$th canonical variate.
13: $\mathbf{tdcvx}$Integer Input
On entry: the stride separating matrix column elements in the array cvx.
Constraint: ${\mathbf{tdcvx}}\ge \mathrm{min}$(nx,ny).
14: $\mathbf{cvy}\left[{\mathbf{ny}}×{\mathbf{tdcvy}}\right]$double Output
On exit: the canonical variate loadings for the $y$ variables. ${\mathbf{cvy}}\left[\left(i-1\right)×{\mathbf{tdcvy}}+j-1\right]$ contains the loading coefficient for the $i$th $y$ variable on the $j$th canonical variate.
15: $\mathbf{tdcvy}$Integer Input
On entry: the stride separating matrix column elements in the array cvy.
Constraint: ${\mathbf{tdcvy}}\ge \mathrm{min}$(nx,ny).
16: $\mathbf{tol}$double Input
On entry: the value of tol is used to decide if the variables are of full rank and, if not, what is the rank of the variables. The smaller the value of tol the stricter the criterion for selecting the singular value decomposition. If a non-negative value of tol less than machine precision is entered, then the square root of machine precision is used instead.
Constraint: ${\mathbf{tol}}\ge 0.0$.
17: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, ${\mathbf{tdz}}=⟨\mathit{\text{value}}⟩$ while ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{tdz}}\ge {\mathbf{m}}$.
NE_3_INT_ARG_CONS
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{nx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ny}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{m}}\ge {\mathbf{nx}}+{\mathbf{ny}}$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{nx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ny}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{n}}>{\mathbf{nx}}+{\mathbf{ny}}$.
On entry, ${\mathbf{tdcvx}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{nx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ny}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{tdcvx}}\ge \mathrm{min}$(nx,ny).
On entry, ${\mathbf{tdcvy}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{nx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ny}}=⟨\mathit{\text{value}}⟩$. These arguments must satisfy ${\mathbf{tdcvy}}\ge \mathrm{min}$(nx,ny).
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_CANON_CORR_1
A canonical correlation is equal to one. This will happen if the $x$ and $y$ variables are perfectly correlated.
NE_INT_ARG_LT
On entry, ${\mathbf{nx}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nx}}\ge 1$.
On entry, ${\mathbf{ny}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ny}}\ge 1$.
On entry, ${\mathbf{tde}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{tde}}\ge 6$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_MAT_RANK_ZERO
The rank of the $X$ matrix or the rank of the $Y$ matrix is zero. This will happen if all the $x$ and $y$ variables are constants.
NE_NEG_WEIGHT_ELEMENT
On entry, ${\mathbf{wt}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
Constraint: when referenced, all elements of wt must be non-negative.
NE_OBSERV_LT_VAR
With weighted data, the effective number of observations given by the sum of weights $\text{}=⟨\mathit{\text{value}}⟩$, while number of variables included in the analysis, ${\mathbf{nx}}+{\mathbf{ny}}=⟨\mathit{\text{value}}⟩$.
Constraint: Effective number of observations $\ge {\mathbf{nx}}+{\mathbf{ny}}+1$.
NE_REAL_ARG_LT
On entry, tol must not be less than $0.0$: ${\mathbf{tol}}=⟨\mathit{\text{value}}⟩$.
NE_SVD_NOT_CONV
The singular value decomposition has failed to converge. This is an unlikely error exit.
NE_VAR_INCL_INDICATED
The number of variables, nx in the analysis $\text{}=⟨\mathit{\text{value}}⟩$, while the number of $x$ variables included in the analysis via array ${\mathbf{isz}}=⟨\mathit{\text{value}}⟩$.
Constraint: these two numbers must be the same.
The number of variables, ny in the analysis $\text{}=⟨\mathit{\text{value}}⟩$, while the number of $y$ variables included in the analysis via array ${\mathbf{isz}}=⟨\mathit{\text{value}}⟩$.
Constraint: these two numbers must be the same.

## 7Accuracy

As the computation involves the use of orthogonal matrices and a singular value decomposition rather than the traditional computing of a sum of squares matrix and the use of an eigenvalue decomposition, g03adc should be less affected by ill conditioned problems.

None.

## 10Example

A sample of nine observations with two variables in each set is read in. The second and third variables are $x$ variables while the first and last are $y$ variables. Canonical variate analysis is performed and the results printed.