Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_correg_coeffs_kspearman_overwrite (g02bn)

## Purpose

nag_correg_coeffs_kspearman_overwrite (g02bn) computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data; the data array is overwritten with the ranks of the observations.

## Syntax

[x, rr, ifail] = g02bn(x, itype, 'n', n, 'm', m)
[x, rr, ifail] = nag_correg_coeffs_kspearman_overwrite(x, itype, 'n', n, 'm', m)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 22: n has been made optional
.

## Description

The input data consists of n$n$ observations for each of m$m$ variables, given as an array
 [xij],  i = 1,2, … ,n (n ≥ 2),j = 1,2, … ,m(m ≥ 2), $[xij], i=1,2,…,n (n≥2),j=1,2,…,m(m≥2),$
where xij${x}_{ij}$ is the i$i$th observation of the j$j$th variable.
The quantities calculated are:
(a) Ranks
For a given variable, j$j$ say, each of the n$n$ observations, x1j,x2j,,xnj${x}_{1j},{x}_{2j},\dots ,{x}_{nj}$, has associated with it an additional number, the ‘rank’ of the observation, which indicates the magnitude of that observation relative to the magnitudes of the other n1$n-1$ observations on that same variable.
The smallest observation for variable j$j$ is assigned the rank 1$1$, the second smallest observation for variable j$j$ the rank 2$2$, the third smallest the rank 3$3$, and so on until the largest observation for variable j$j$ is given the rank n$n$.
If a number of cases all have the same value for the given variable, j$j$, then they are each given an ‘average’ rank, e.g., if in attempting to assign the rank h + 1$h+1$, k$k$ observations were found to have the same value, then instead of giving them the ranks
 h + 1,h + 2, … ,h + k, $h+1,h+2,…,h+k,$
all k$k$ observations would be assigned the rank
 (2h + k + 1)/2 $2h+k+12$
and the next value in ascending order would be assigned the rank
 h + k + 1. $h+k+ 1.$
The process is repeated for each of the m$m$ variables.
Let yij${y}_{ij}$ be the rank assigned to the observation xij${x}_{ij}$ when the j$j$th variable is being ranked. The actual observations xij${x}_{ij}$ are replaced by the ranks yij${y}_{ij}$.
(b) Nonparametric rank correlation coefficients
(i) Kendall's tau:
 Rjk = ( ∑ h = 1n ∑ i = 1nsign(yhj − yij)sign(yhk − yik))/(sqrt([n(n − 1) − Tj][n(n − 1) − Tk])),  j,k = 1,2, … ,m, $Rjk=∑h=1n∑i=1nsign(yhj-yij)sign(yhk-yik) [n(n-1)-Tj][n(n-1)-Tk] , j,k=1,2,…,m,$
 where signu = 1$\mathrm{sign}u=1$ if u > 0$u>0$, signu = 0$\mathrm{sign}u=0$ if u = 0$u=0$, signu = − 1$\mathrm{sign}u=-1$ if u < 0$u<0$,
and Tj = tj(tj1)${T}_{j}=\sum {t}_{j}\left({t}_{j}-1\right)$, where tj${t}_{j}$ is the number of ties of a particular value of variable j$j$, and the summation is over all tied values of variable j$j$
(ii) Spearman's:
 Rjk * = (n(n2 − 1) − 6 ∑ i = 1n(yij − yik)2 − (1/2)(Tj * + Tk * ))/(sqrt([n(n2 − 1) − Tj * ][n(n2 − 1) − Tk * ])),  j,k = 1,2, … ,m, $Rjk*=n(n2-1)-6∑i=1n (yij-yik) 2-12(Tj*+Tk*) [n(n2-1)-Tj*][n(n2-1)-Tk*] , j,k=1,2,…,m,$
where Tj * = tj(tj21)${T}_{j}^{*}=\sum {t}_{j}\left({t}_{j}^{2}-1\right)$, tj${t}_{j}$ being the number of ties of a particular value of variable j$j$, and the summation being over all tied values of variable j$j$.

## References

Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill

## Parameters

### Compulsory Input Parameters

1:     x(ldx,m) – double array
ldx, the first dimension of the array, must satisfy the constraint ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
x(i,j)${\mathbf{x}}\left(\mathit{i},\mathit{j}\right)$ must be set to xij${x}_{\mathit{i}\mathit{j}}$, the value of the i$\mathit{i}$th observation on the j$\mathit{j}$th variable, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$ and j = 1,2,,m$\mathit{j}=1,2,\dots ,m$.
2:     itype – int64int32nag_int scalar
The type of correlation coefficients which are to be calculated.
itype = -1${\mathbf{itype}}=-1$
Only Kendall's tau coefficients are calculated.
itype = 0${\mathbf{itype}}=0$
Both Kendall's tau and Spearman's coefficients are calculated.
itype = 1${\mathbf{itype}}=1$
Only Spearman's coefficients are calculated.
Constraint: itype = -1${\mathbf{itype}}=-1$, 0$0$ or 1$1$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the array x.
n$n$, the number of observations or cases.
Constraint: n2${\mathbf{n}}\ge 2$.
2:     m – int64int32nag_int scalar
Default: The second dimension of the array x.
m$m$, the number of variables.
Constraint: m2${\mathbf{m}}\ge 2$.

### Input Parameters Omitted from the MATLAB Interface

ldx ldrr kworka kworkb work1 work2

### Output Parameters

1:     x(ldx,m) – double array
ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
x(i,j)${\mathbf{x}}\left(\mathit{i},\mathit{j}\right)$ contains the rank yij${y}_{\mathit{i}\mathit{j}}$ of the observation xij${x}_{\mathit{i}\mathit{j}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$ and j = 1,2,,m$\mathit{j}=1,2,\dots ,m$.
2:     rr(ldrr,m) – double array
ldrrm$\mathit{ldrr}\ge {\mathbf{m}}$.
The requested correlation coefficients.
If only Kendall's tau coefficients are requested (itype = 1${\mathbf{itype}}=-1$), rr(j,k)${\mathbf{rr}}\left(j,k\right)$ contains Kendall's tau for the j$j$th and k$k$th variables.
If only Spearman's coefficients are requested (itype = 1${\mathbf{itype}}=1$), rr(j,k)${\mathbf{rr}}\left(j,k\right)$ contains Spearman's rank correlation coefficient for the j$j$th and k$k$th variables.
If both Kendall's tau and Spearman's coefficients are requested (itype = 0${\mathbf{itype}}=0$), the upper triangle of rr contains the Spearman coefficients and the lower triangle the Kendall coefficients. That is, for the j$\mathit{j}$th and k$\mathit{k}$th variables, where j$\mathit{j}$ is less than k$\mathit{k}$, rr(j,k)${\mathbf{rr}}\left(\mathit{j},\mathit{k}\right)$ contains the Spearman rank correlation coefficient, and rr(k,j)${\mathbf{rr}}\left(\mathit{k},\mathit{j}\right)$ contains Kendall's tau, for j = 1,2,,m$\mathit{j}=1,2,\dots ,m$ and k = 1,2,,m$\mathit{k}=1,2,\dots ,m$.
(Diagonal terms, rr(j,j)${\mathbf{rr}}\left(j,j\right)$, are unity for all three values of itype.)
3:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
 On entry, n < 2${\mathbf{n}}<2$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, m < 2${\mathbf{m}}<2$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, ldx < n$\mathit{ldx}<{\mathbf{n}}$, or ldrr < m$\mathit{ldrr}<{\mathbf{m}}$.
ifail = 4${\mathbf{ifail}}=4$
 On entry, itype < − 1${\mathbf{itype}}<-1$, or itype > 1${\mathbf{itype}}>1$.

## Accuracy

The method used is believed to be stable.

The time taken by nag_correg_coeffs_kspearman_overwrite (g02bn) depends on n$n$ and m$m$.

## Example

```function nag_correg_coeffs_kspearman_overwrite_example
x = [1.7, 1, 0.5;
2.8, 4, 3;
0.6, 6, 2.5;
1.8, 9, 6;
0.99, 4, 2.5;
1.4, 2, 5.5;
1.8, 9, 7.5;
2.5, 7, 0;
0.99, 5, 3];
itype = int64(0);
[xOut, rr, ifail] = nag_correg_coeffs_kspearman_overwrite(x, itype)
```
```

xOut =

5.0000    1.0000    2.0000
9.0000    3.5000    5.5000
1.0000    6.0000    3.5000
6.5000    8.5000    8.0000
2.5000    3.5000    3.5000
4.0000    2.0000    7.0000
6.5000    8.5000    9.0000
8.0000    7.0000    1.0000
2.5000    5.0000    5.5000

rr =

1.0000    0.2246    0.1186
0.0294    1.0000    0.3814
0.1176    0.2353    1.0000

ifail =

0

```
```function g02bn_example
x = [1.7, 1, 0.5;
2.8, 4, 3;
0.6, 6, 2.5;
1.8, 9, 6;
0.99, 4, 2.5;
1.4, 2, 5.5;
1.8, 9, 7.5;
2.5, 7, 0;
0.99, 5, 3];
itype = int64(0);
[xOut, rr, ifail] = g02bn(x, itype)
```
```

xOut =

5.0000    1.0000    2.0000
9.0000    3.5000    5.5000
1.0000    6.0000    3.5000
6.5000    8.5000    8.0000
2.5000    3.5000    3.5000
4.0000    2.0000    7.0000
6.5000    8.5000    9.0000
8.0000    7.0000    1.0000
2.5000    5.0000    5.5000

rr =

1.0000    0.2246    0.1186
0.0294    1.0000    0.3814
0.1176    0.2353    1.0000

ifail =

0

```