naginterfaces.library.mv.discrim_​mahal

naginterfaces.library.mv.discrim_mahal(equal, mode, gmn, gc, nobs, isx, x)

discrim_mahal computes Mahalanobis squared distances for group or pooled variance-covariance matrices. It is intended for use after discrim().

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/g03/g03dbf.html

Parameters

equalstr, length 1

Indicates whether or not the within-group variance-covariance matrices are assumed to be equal and the pooled variance-covariance matrix used.

$equal=\text{'E'}$

The within-group variance-covariance matrices are assumed equal and the matrix $R$ stored in the first $p(p+1)/2$ elements of $gc$ is used.

$equal=\text{'U'}$

The within-group variance-covariance matrices are assumed to be unequal and the matrices $R_{\text{j}}$, for $\text{j}=1,2,\dots ,n_g$, stored in the remainder of $gc$ are used.

modestr, length 1

Indicates whether distances from sample points are to be calculated or distances between the group means.

$mode=\text{'S'}$

The distances between the sample points given in $x$ and the group means are calculated.

$mode=\text{'M'}$

The distances between the group means will be calculated.

gmnfloat, array-like, shape $(\text{ng},\text{nvar})$

The $\text{j}$th row of $gmn$ contains the means of the $p$ selected variables for the $\text{j}$th group, for $\text{j}=1,2,\dots ,n_g$. These are returned by discrim().

gcfloat, array-like, shape $((\text{ng}+1)\times \text{nvar}\times (\text{nvar}+1)/2)$

The first $p(p+1)/2$ elements of $gc$ should contain the upper triangular matrix $R$ and the next $n_g$ blocks of $p(p+1)/2$ elements should contain the upper triangular matrices $R_j$. All matrices must be stored packed by column. These matrices are returned by discrim(). If $equal=\text{'E'}$ only the first $p(p+1)/2$ elements are referenced, if $equal=\text{'U'}$ only the elements $p(p+1)/2+1$ to $(n_g+1)p(p+1)/2$ are referenced.

nobsint

If $mode=\text{'S'}$, the number of sample points in $x$ for which distances are to be calculated.

If $mode=\text{'M'}$, $nobs$ is not referenced.

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

If $mode=\text{'S'}$, $isx[\text{l}-1]$ indicates if the $\text{l}$th variable in $x$ is to be included in the distance calculations. If $isx[\text{l}-1]>0$ the $\text{l}$th variable is included, for $\text{l}=1,2,\dots ,m$; otherwise the $\text{l}$th variable is not referenced.

If $mode=\text{'M'}$, $isx$ is not referenced.

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

Note: the required extent for this argument in dimension 1 is determined as follows: if $mode=\text{'S'}$: $nobs$; otherwise: $1$.

If $mode=\text{'S'}$ the $\text{k}$th row of $x$ must contain $x_{\text{k}}$. That is $x[\text{k}-1,\text{l}-1]$ must contain the $\text{k}$th sample value for the $\text{l}$th variable, for $\text{l}=1,2,\dots ,m$, for $\text{k}=1,2,\dots ,nobs$. Otherwise $x$ is not referenced.

Returns

dfloat, ndarray, shape $(:,\text{ng})$

The squared distances.

If $mode=\text{'S'}$, $d[\text{k}-1,\text{j}-1]$ contains the squared distance of the $\text{k}$th sample point from the $\text{j}$th group mean, $D_{\text{k}\text{j}}^2$, for $\text{j}=1,2,\dots ,n_g$, for $\text{k}=1,2,\dots ,nobs$.

If $mode=\text{'M'}$ and $equal=\text{'U'}$, $d[\text{i}-1,\text{j}-1]$ contains the squared distance between the $\text{i}$th mean and the $\text{j}$th mean, $D_{\text{i}\text{j}}^2$, for $\text{j}=1,2,\dots ,\text{i}-1,\text{i}+1,\dots ,n_g$, for $\text{i}=1,2,\dots ,n_g$.

The elements $d[\text{i}-1,\text{i}-1]$ are not referenced, for $\text{i}=1,2,\dots ,n_g$.

If $mode=\text{'M'}$ and $equal=\text{'E'}$, $d[\text{i}-1,\text{j}-1]$ contains the squared distance between the $\text{i}$th mean and the $\text{j}$th mean, $D_{\text{i}\text{j}}^2$, for $\text{j}=1,2,\dots ,\text{i}-1$, for $\text{i}=1,2,\dots ,n_g$.

Since $D_{\text{i}\text{j}}=D_{\text{j}\text{i}}$ the elements $d[\text{i}-1,\text{j}-1]$ are not referenced, for $\text{j}=\text{i}+1,\dots ,n_g$, for $\text{i}=1,2,\dots ,n_g$.

Raises

NagValueError

(errno $1$)

On entry, $mode=⟨value⟩$.

Constraint: $mode=\text{'M'}$ or $\text{'S'}$.

(errno $1$)

On entry, $equal=⟨value⟩$.

Constraint: $equal=\text{'E'}$ or $\text{'U'}$.

(errno $1$)

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

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

(errno $1$)

On entry, $nobs=⟨value⟩$.

Constraint: $nobs\ge 1$.

(errno $1$)

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

Constraint: $\text{ng}\ge 2$.

(errno $1$)

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

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

(errno $2$)

On entry, $\text{nvar}=⟨value⟩$ and $⟨value⟩$ values of $isx>0$.

Constraint: exactly $\text{nvar}$ elements of $isx>0$.

(errno $2$)

On entry, diagonal element $⟨value⟩$ of $R_j=0$ for $j=⟨value⟩$.

(errno $2$)

On entry, diagonal element $⟨value⟩$ of $R=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.

Consider $p$ variables observed on $n_g$ populations or groups. Let ${\overline{x}}_j$ be the sample mean and $S_j$ the within-group variance-covariance matrix for the $j$th group and let $x_k$ be the $k$th sample point in a dataset. A measure of the distance of the point from the $j$th population or group is given by the Mahalanobis distance, $D_{kj}$:

$$D_{kj}^2={(x_k-{\overline{x}}_j)}^T{S}_j^{-1}(x_k-{\overline{x}}_j)\text{.}$$

If the pooled estimated of the variance-covariance matrix $S$ is used rather than the within-group variance-covariance matrices, then the distance is:

$$D_{kj}^2={(x_k-{\overline{x}}_j)}^T{S}^{-1}(x_k-{\overline{x}}_j)\text{.}$$

Instead of using the variance-covariance matrices $S$ and $S_j$, discrim_mahal uses the upper triangular matrices $R$ and $R_j$ supplied by discrim() such that $S=R^{T}R$ and $S_j=R_j^T{R}_j$. $D_{kj}^2$ can then be calculated as $z^{T}z$ where $R_{j}z=(x_k-{\overline{x}}_j)$ or $Rz=(x_k-{\overline{x}}_j)$ as appropriate.

A particular case is when the distance between the group or population means is to be estimated. The Mahalanobis squared distance between the $i$th and $j$th groups is:

$$D_{ij}^2={({\overline{x}}_i-{\overline{x}}_j)}^T{S}_j^{-1}({\overline{x}}_i-{\overline{x}}_j)$$

or

$$D_{ij}^2={({\overline{x}}_i-{\overline{x}}_j)}^T{S}^{-1}({\overline{x}}_i-{\overline{x}}_j)\text{.}$$

Note: $D_{jj}^2=0$ and that in the case when the pooled variance-covariance matrix is used $D_{ij}^2=D_{ji}^2$ so in this case only the lower triangular values of $D_{ij}^2$, $i>j$, are computed.

References

Aitchison, J and Dunsmore, I R, 1975, Statistical Prediction Analysis, Cambridge

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

Krzanowski, W J, 1990, Principles of Multivariate Analysis, Oxford University Press