naginterfaces.library.mv.distance_​mat_​2

naginterfaces.library.mv.distance_mat_2(update, scal, stype, p, x, isv, y, sx, sy=None, d=None)

distance_mat_2 computes a distance (dissimilarity) matrix between two sets of observations.

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

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

Parameters

updatestr, length 1

Indicates whether or not an existing matrix is to be updated.

$update=\text{'U'}$

The matrix $D$ is updated and distances are added to $D$.

$update=\text{'I'}$

The matrix $D$ is initialized to zero before the distances are added to $D$.

scalstr, length 1

Indicates the standardization of the variables to be used.

$scal=\text{'S'}$

Standard deviation.

$scal=\text{'R'}$

Range.

$scal=\text{'G'}$

Standardizations given in array $sx$ (and posibly $sy$).

$scal=\text{'U'}$

Unscaled.

stypestr, length 1

Indicates how the standardization of the variables treats the two sets of observations.

$stype=\text{'A'}$

Amalgamated.

$stype=\text{'I'}$

Independent.

$stype=\text{'X'}$

Standardization is based purley on observations in $x$.

pfloat

The order $p$ of the Minkowski distance metric.

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

$x[\text{i}-1,\text{k}-1]$ must contain the value of the $\text{k}$th variable for the $\text{i}$th observation in the first set of observations, for $\text{k}=1,2,\dots ,l$, for $\text{i}=1,2,\dots ,m$.

isvint, array-like, shape $\left(l\right)$

$isv[j-1]$ indicates whether or not the $j$th variable in $x$ and $y$ is to be included in the distance computations.

If $isv[\text{k}-1]=0$ the $\text{j}$th variable is not included., for $\text{k}=1,2,\dots ,l$.

If $isv[\text{k}-1]\ge 1$ the $\text{j}$th variable is included, for $\text{k}=1,2,\dots ,l$

yfloat, array-like, shape $(n,l)$

$y[\text{j}-1,\text{k}-1]$ must contain the value of the $\text{k}$th variable for the $\text{j}$th observation in the second set of observations, for $\text{k}=1,2,\dots ,l$, for $\text{j}=1,2,\dots ,n$.

sxfloat, array-like, shape $\left(l\right)$

If $scal=\text{'G'}$ and $isv[\text{k}-1]>0$ then $sx[\text{k}-1]$ must contain the scaling for variable $\text{k}$, for $\text{k}=1,2,\dots ,l$.

syNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $stype=\text{'I'}\text{and}scal\ne \text{'U'}$: $l$; otherwise: $0$.

If $scal=\text{'G'}$ and $stype=\text{'I'}$ and $isv[\text{k}-1]>0$ then $sy[\text{k}-1]$ must contain the scaling for variable $\text{k}$ , for $\text{k}=1,2,\dots ,l$.

If $stype\ne \text{'I'}$, or $scal=\text{'U'}$ then $sy$ is not referenced and may be None.

dNone or float, array-like, shape $(m,n)$, optional

The $m\times n$ distance matrix $D$.

If $update=\text{'U'}$, $d$ need not be set.

Returns

sxfloat, ndarray, shape $\left(l\right)$

If $scal=\text{'S'}$ and $isv[k-1]>0$ then $sx[k-1]$ contains the standard deviation of the variable in the $k$th column of $x$.

If $scal=\text{'R'}$ and $isv[k-1]>0$, $sx[k-1]$ contains the range of the variable in the $j$th column of $x$.

If $scal=\text{'U'}$ and $isv[k-1]>0$, $sx[k-1]=1.0$.

If $scal=\text{'G'}$, $sx$ is unchanged.

syNone or float, ndarray, shape $(:)$

If $scal=\text{'S'}$ and $stype=\text{'I'}$ and $isv[k-1]>0$ then $sy[k-1]$ contains the standard deviation of the variable in the $k$th column of $x$.

If $scal=\text{'R'}$ and $stype=\text{'I'}$ and $isv[k-1]>0$, $sy[k-1]$ contains the range of the variable in the $j$th column of $x$.

If $scal=\text{'U'}$, $sy$ is unchanged.

If $scal=\text{'G'}$, $sy$ is unchanged.

dfloat, ndarray, shape $(m,n)$

The (possibly updated) distance matrix $D$.

Raises

NagValueError

(errno $1$)

On entry, $update=⟨value⟩$.

Constraint: $update=\text{'U'}$ or $\text{'I'}$.

(errno $2$)

On entry, $scal=⟨value⟩$.

Constraint: $scal=\text{'S'}$, $\text{'R'}$, $\text{'G'}$ or $\text{'U'}$.

(errno $3$)

On entry, $stype=⟨value⟩$.

Constraint: $stype=\text{'A'}$, $\text{'I'}$ or $\text{'X'}$.

(errno $4$)

On entry, $p=⟨value⟩$.

Constraint: $p\ge 1.0$.

(errno $5$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge 1$.

(errno $6$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $7$)

On entry, $l=⟨value⟩$.

Constraint: $l\ge 1$.

(errno $8$)

Variable $⟨value⟩$ is constant.

(errno $10$)

On entry, $isv$ does not contain a positive element.

(errno $13$)

On entry, at least one element of $sx\le 0.0$ or $sy\le 0.0$.

(errno $13$)

On entry, at least one element of $sx\le 0.0$.

(errno $15$)

On entry, at least one element of $d<0.0$.

Notes

Given two sets of observations on $l$ variables, a distance matrix is such that the $ij$th element represents how far apart or how dissimilar the $i$th observation from the first set and the $j$th observation from the second set are.

Let $X$ and $Y$ be $m\times l$ and $n\times l$ data matrices of $m$ and $n$ observations, respectively, on $l$ variables. The distance between observation $i$ from $X$ and observation $j$ from $Y$, $d_{ij}$, is most commonly defined in terms of the scaled Minkowski $p$-norm:

$$d_{ij}={\left\{\sum _{k=1}^p{\left(|x_{ik}/{\text{sx}}_i-y_{jk}/{\text{sy}}_j|\right)}^p\right\}}^{1/p}\text{,}$$

where $x_{ik}$ and $y_{jk}$ are the $ik$th and $jk$th elements of $X$ and $Y$ respectively, ${\text{sx}}_i$ is a standardization for the $i$th variable in $X$, ${\text{sy}}_j$ is a standardization for the $j$th variable in $Y$, and $p$ is the order of the Minkowski norm.

Three standardizations (scalings) for the variables are available.

1. Standard deviation: ${\text{sx}}_i=\sqrt{{\sum }_{k=1}^n{(x_{ji}-\overline{x})}^2/(n-1)}$

2. Range: ${\text{sx}}_i=max(x_{1i},x_{2i},\dots ,x_{ni})-min(x_{1i},x_{2i},\dots ,x_{ni})$

3. User-supplied values of ${\text{sx}}_i$.

In addition to the Minkowski measure there are a large number of other dissimilarity measures, particularly for dichotomous variables (see Krzanowski (1990) and Everitt (1974)). For the dichotomous case these measures are simple to compute and can, if suitable scaling is used, be combined with the distances computed by distance_mat_2 using the updating option.

Dissimilarity measures for variables can be based on the correlation coefficient for continuous variables and contingency table statistics for dichotomous data, see submodule correg and submodule contab respectively.

distance_mat_2 returns the full rectangular distance matrix.

References

Everitt, B S, 1974, Cluster Analysis, Heinemann

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