naginterfaces.library.mv.canon_​var

naginterfaces.library.mv.canon_var(weight, x, isx, ing, ng, wt, tol)

canon_var performs a canonical variate (canonical discrimination) analysis.

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

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g03/g03acf.html

Parameters

weightstr, length 1

Indicates if weights are to be used.

$weight=\text{'U'}$

No weights are used.

$weight=\text{'W'}$ or $\text{'V'}$

Weights are used and must be supplied in $wt$.

If $weight=\text{'W'}$, the weights are treated as frequencies and the effective number of observations is the sum of the weights.

If $weight=\text{'V'}$, the weights are treated as being inversely proportional to the variance of the observations and the effective number of observations is the number of observations with nonzero weights.

xfloat, array-like, shape $(n,m)$

$x[\text{i}-1,\text{j}-1]$ must contain the $\text{i}$th observation for the $\text{j}$th variable, for $\text{j}=1,2,\dots ,m$, for $\text{i}=1,2,\dots ,n$.

isxint, array-like, shape $\left(m\right)$

$isx[j-1]$ indicates whether or not the $j$th variable is to be included in the analysis.

If $isx[\text{j}-1]>0$, the variables contained in the $\text{j}$th column of $x$ is included in the canonical variate analysis, for $\text{j}=1,2,\dots ,m$.

ingint, array-like, shape $\left(n\right)$

$ing[\text{i}-1]$ indicates which group the $\text{i}$th observation is in, for $\text{i}=1,2,\dots ,n$. The effective number of groups is the number of groups with nonzero membership.

ngint

The number of groups, $n_g$.

wtfloat, array-like, shape $(:)$

Note: the required length for this argument is determined as follows: if $weight\text{in}(\text{'W'},\text{'V'})$: $n$; otherwise: $1$.

If $weight=\text{'W'}$ or $\text{'V'}$, the first $n$ elements of $wt$ must contain the weights to be used in the analysis.

If $wt[i-1]=0.0$, the $i$th observation is not included in the analysis.

If $weight=\text{'U'}$, $wt$ is not referenced.

tolfloat

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, the square root of machine precision is used instead.

Returns

nigint, ndarray, shape $\left(ng\right)$

$nig[\text{j}-1]$ gives the number of observations in group $\text{j}$, for $\text{j}=1,2,\dots ,n_g$.

cvmfloat, ndarray, shape $(ng,\text{nx})$

$cvm[\text{i}-1,\text{j}-1]$ contains the mean of the $\text{j}$th canonical variate for the $\text{i}$th group, for $\text{j}=1,2,\dots ,l$, for $\text{i}=1,2,\dots ,n_g$; the remaining columns, if any, are used as workspace.

efloat, ndarray, shape $(min(\text{nx},ng-1),6)$

The statistics of the canonical variate analysis.

$e[i-1,0]$

The canonical correlations, ${\delta }_{\text{i}}$, for $\text{i}=1,2,\dots ,l$.

$e[i-1,1]$

The eigenvalues of the within-group sum of squares matrix, ${\lambda }_{\text{i}}^2$, for $\text{i}=1,2,\dots ,l$.

$e[i-1,2]$

The proportion of variation explained by the $\text{i}$th canonical variate, for $\text{i}=1,2,\dots ,l$.

$e[i-1,3]$

The ${\chi }^2$ statistic for the $\text{i}$th canonical variate, for $\text{i}=1,2,\dots ,l$.

$e[i-1,4]$

The degrees of freedom for ${\chi }^2$ statistic for the $\text{i}$th canonical variate, for $\text{i}=1,2,\dots ,l$.

$e[i-1,5]$

The significance level for the ${\chi }^2$ statistic for the $\text{i}$th canonical variate, for $\text{i}=1,2,\dots ,l$.

ncvint

The number of canonical variates, $l$. This will be the minimum of $n_g-1$ and the rank of $x$.

cvxfloat, ndarray, shape $(\text{nx},ng-1)$

The canonical variate loadings. $cvx[\text{i}-1,\text{j}-1]$ contains the loading coefficient for the $\text{i}$th variable on the $\text{j}$th canonical variate, for $\text{j}=1,2,\dots ,l$, for $\text{i}=1,2,\dots ,n_x$; the remaining columns, if any, are used as workspace.

irankxint

The rank of the dependent variables.

If the variables are of full rank then $irankx=\text{nx}$.

If the variables are not of full rank then $irankx$ is an estimate of the rank of the dependent variables. $irankx$ is calculated as the number of singular values greater than $tol\times \text{(largest singular value)}$.

Raises

NagValueError

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol\ge 0.0$.

(errno $1$)

On entry, $weight=⟨value⟩$.

Constraint: $weight=\text{'U'}$, $\text{'W'}$ or $\text{'V'}$.

(errno $1$)

On entry, $\text{lde}=⟨value⟩$ and $min(\text{nx},ng-1)=⟨value⟩$.

Constraint: $\text{lde}\ge min(\text{nx},ng-1)$.

(errno $1$)

On entry, $n=⟨value⟩$ and $\text{nx}+ng=⟨value⟩$.

Constraint: $n\ge \text{nx}+ng$.

(errno $1$)

On entry, $m=⟨value⟩$ and $\text{nx}=⟨value⟩$.

Constraint: $m\ge \text{nx}$.

(errno $1$)

On entry, $ng=⟨value⟩$.

Constraint: $ng\ge 2$.

(errno $1$)

On entry, $\text{nx}=⟨value⟩$.

Constraint: $\text{nx}\ge 1$.

(errno $2$)

On entry, $i=⟨value⟩$ and $wt[i-1]<0.0$.

Constraint: $wt[i-1]\ge 0.0$.

(errno $3$)

On entry, $i=⟨value⟩$, $ing[i-1]=⟨value⟩$ and $ng=⟨value⟩$.

Constraint: $1\le ing[i-1]\le ng$.

(errno $4$)

On entry, $\text{nx}=⟨value⟩$, expected $\text{value}=⟨value⟩$.

Constraint: $\text{nx}$ must be consistent with $isx$.

(errno $5$)

The singular value decomposition has failed to converge.

(errno $7$)

The effective number of observations is less than the effective number of groups plus number of variables.

(errno $7$)

Less than $2$ groups have nonzero membership.

Warns

NagAlgorithmicWarning

(errno $6$)

A canonical correlation is equal to $1.0$.

(errno $8$)

The rank of $x$ is $0$.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Let a sample of $n$ observations on $n_x$ variables in a data matrix come from $n_g$ groups with $n_1,n_2,\dots ,n_{n_g}$ observations in each group, $\sum n_i=n$. Canonical variate analysis finds the linear combination of the $n_x$ variables that maximizes the ratio of between-group to within-group variation. The variables formed, the canonical variates can then be used to discriminate between groups.

The canonical variates can be calculated from the eigenvectors of the within-group sums of squares and cross-products matrix. However, canon_var calculates the canonical variates by means of a singular value decomposition (SVD) of a matrix $V$. Let the data matrix with variable (column) means subtracted be $X$, and let its rank be $k$; then the $k$ by ($n_g-1$) matrix $V$ is given by:

$$V=Q_X^T{Q}_g\text{,}$$

where $Q_g$ is an $n\times (n_g-1)$ orthogonal matrix that defines the groups and $Q_X$ is the first $k$ rows of the orthogonal matrix $Q$ either from the $QR$ decomposition of $X$:

$$X=QR$$

if $X$ is of full column rank, i.e., $k=n_x$, else from the SVD of $X$:

$$X=QD{P}^T\text{.}$$

Let the SVD of $V$ be:

$$V=U_x\Delta U_g^T$$

then the nonzero elements of the diagonal matrix $\Delta$, ${\delta }_{\text{i}}$, for $\text{i}=1,2,\dots ,l$, are the $l$ canonical correlations associated with the $l=min(k,n_g-1)$ canonical variates, where $l=min(k,n_g)$.

The eigenvalues, ${\lambda }_i^2$, of the within-group sums of squares matrix are given by:

$${\lambda }_i^2=\frac{{\delta }_i^2}{1-{\delta }_i^2}$$

and 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$’s 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-n_g-\frac{1}{2}(k-n_g))\sum _{j=i+1}^l\log (1+{\lambda }_j^2)$$

can be used. This is asymptotically distributed as a ${\chi }^2$-distribution with $(k-i)(n_g-1-i)$ degrees of freedom. If the test for $i=h$ is not significant, then the remaining tests for $i>h$ should be ignored.

The loadings for the canonical variates are calculated from the matrix $U_x$. This matrix is scaled so that the canonical variates have unit within-group variance.

In addition to the canonical variates loadings the means for each canonical variate are calculated for each group.

Weights can be used with the analysis, in which case the weighted means are subtracted from each column and then each row is scaled by an amount $\sqrt{w_i}$, where $w_i$ is the weight for the $i$th observation (row).

References

Chatfield, C and Collins, A J, 1980, Introduction to Multivariate Analysis, Chapman and Hall

Gnanadesikan, R, 1977, Methods for Statistical Data Analysis of Multivariate Observations, Wiley

Hammarling, S, 1985, The singular value decomposition in multivariate statistics, SIGNUM Newsl. (20(3)), 2–25

Kendall, M G and Stuart, A, 1969, The Advanced Theory of Statistics (Volume 1), (3rd Edition), Griffin