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_univar_robust_2var_ci (g07eb)

## Purpose

nag_univar_robust_2var_ci (g07eb) calculates a rank based (nonparametric) estimate and confidence interval for the difference in location between two independent populations.

## Syntax

[theta, thetal, thetau, estcl, ulower, uupper, ifail] = g07eb(method, x, y, clevel, 'n', n, 'm', m)
[theta, thetal, thetau, estcl, ulower, uupper, ifail] = nag_univar_robust_2var_ci(method, x, y, clevel, 'n', n, 'm', m)

## Description

Consider two random samples from two populations which have the same continuous distribution except for a shift in the location. Let the random sample, x = (x1,x2,,xn)T$x={\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)}^{\mathrm{T}}$, have distribution F(x)$F\left(x\right)$ and the random sample, y = (y1,y2,,ym)T$y={\left({y}_{1},{y}_{2},\dots ,{y}_{m}\right)}^{\mathrm{T}}$, have distribution F(xθ)$F\left(x-\theta \right)$.
nag_univar_robust_2var_ci (g07eb) finds a point estimate, θ̂$\stackrel{^}{\theta }$, of the difference in location θ$\theta$ together with an associated confidence interval. The estimates are based on the ordered differences yjxi${y}_{j}-{x}_{i}$. The estimate θ̂$\stackrel{^}{\theta }$ is defined by
 θ̂ = median {yj − xi,  i = 1,2, … ,n;j = 1,2, … ,m} . $θ^ = median { yj-xi , i=1,2,…,n ; j=1,2,…,m } .$
Let dk${d}_{\mathit{k}}$, for k = 1,2,,nm$\mathit{k}=1,2,\dots ,nm$, denote the nm$nm$ (ascendingly) ordered differences yjxi${y}_{\mathit{j}}-{x}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$ and j = 1,2,,m$\mathit{j}=1,2,\dots ,m$. Then
• if nm$nm$ is odd, θ̂ = dk$\stackrel{^}{\theta }={d}_{k}$ where k = (nm1) / 2$k=\left(nm-1\right)/2$;
• if nm$nm$ is even, θ̂ = (dk + dk + 1) / 2$\stackrel{^}{\theta }=\left({d}_{k}+{d}_{k+1}\right)/2$ where k = nm / 2$k=nm/2$.
This estimator arises from inverting the two sample Mann–Whitney rank test statistic, U(θ0)$U\left({\theta }_{0}\right)$, for testing the hypothesis that θ = θ0$\theta ={\theta }_{0}$. Thus U(θ0)$U\left({\theta }_{0}\right)$ is the value of the Mann–Whitney U$U$ statistic for the two independent samples {(xi + θ0), for ​i = 1,2,,n} $\left\{\left({x}_{i}+{\theta }_{0}\right)\text{, for ​}i=1,2,\dots ,n\right\}$ and {yj, for ​j = 1,2,,m} $\left\{{y}_{j}\text{, for ​}j=1,2,\dots ,m\right\}$. Effectively U(θ0)$U\left({\theta }_{0}\right)$ is a monotonically increasing step function of θ0${\theta }_{0}$ with
 mean ​(U) = μ = (nm)/2, var(U) = σ2(nm(n + m + 1))/12.
$mean ​(U)=μ= nm2, var(U)=σ2 nm(n+m+1)12.$
The estimate θ̂$\stackrel{^}{\theta }$ is the solution to the equation U(θ̂) = μ$U\left(\stackrel{^}{\theta }\right)=\mu$; two methods are available for solving this equation. These methods avoid the computation of all the ordered differences dk${d}_{k}$; this is because for large n$n$ and m$m$ both the storage requirements and the computation time would be high.
The first is an exact method based on a set partitioning procedure on the set of all differences yjxi${y}_{\mathit{j}}-{x}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$ and j = 1,2,,m$\mathit{j}=1,2,\dots ,m$. This is adapted from the algorithm proposed by Monahan (1984) for the computation of the Hodges–Lehmann estimator for a single population.
The second is an iterative algorithm, based on the Illinois method which is a modification of the regula falsi method, see McKean and Ryan (1977). This algorithm has proved suitable for the function U(θ0)$U\left({\theta }_{0}\right)$ which is asymptotically linear as a function of θ0${\theta }_{0}$.
The confidence interval limits are also based on the inversion of the Mann–Whitney test statistic.
Given a desired percentage for the confidence interval, 1α$1-\alpha$, expressed as a proportion between 0.0$0.0$ and 1.0$1.0$ initial estimates of the upper and lower confidence limits for the Mann–Whitney U$U$ statistic are found;
 Ul = μ − 0.5 + (σ × Φ − 1(α / 2)) Uu = μ + 0.5 + (σ × Φ − 1((1 − α) / 2))
$Ul=μ-0.5+(σ×Φ-1(α/2)) Uu=μ+0.5+(σ×Φ-1((1-α)/2))$
where Φ1${\Phi }^{-1}$ is the inverse cumulative Normal distribution function.
Ul${U}_{l}$ and Uu${U}_{u}$ are rounded to the nearest integer values. These estimates are refined using an exact method, without taking ties into account, if n + m40$n+m\le 40$ and max (n,m)30$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(n,m\right)\le 30$ and a Normal approximation otherwise, to find Ul${U}_{l}$ and Uu${U}_{u}$ satisfying
 P(U ≤ Ul) ≤ α / 2 P(U ≤ Ul + 1) > α / 2
$P(U≤Ul)≤α/2 P(U≤Ul+1)>α/2$
and
 P(U ≥ Uu) ≤ α / 2 P(U ≥ Uu − 1) > α / 2.
$P(U≥Uu)≤α /2 P(U≥Uu- 1)>α /2.$
The function U(θ0)$U\left({\theta }_{0}\right)$ is a monotonically increasing step function. It is the number of times a score in the second sample, yj${y}_{j}$, precedes a score in the first sample, xi + θ${x}_{i}+\theta$, where we only count a half if a score in the second sample actually equals a score in the first.
Let Ul = k${U}_{l}=k$; then θl = dk + 1${\theta }_{l}={d}_{k+1}$. This is the largest value θl${\theta }_{l}$ such that U(θl) = Ul$U\left({\theta }_{l}\right)={U}_{l}$.
Let Uu = nmk${U}_{u}=nm-k$; then θu = dnmk${\theta }_{u}={d}_{nm-k}$. This is the smallest value θu${\theta }_{u}$ such that U(θu) = Uu$U\left({\theta }_{u}\right)={U}_{u}$.
As in the case of θ̂$\stackrel{^}{\theta }$, these equations may be solved using either the exact or iterative methods to find the values θl${\theta }_{l}$ and θu${\theta }_{u}$.
Then (θl,θu)$\left({\theta }_{l},{\theta }_{u}\right)$ is the confidence interval for θ$\theta$. The confidence interval is thus defined by those values of θ0${\theta }_{0}$ such that the null hypothesis, θ = θ0$\theta ={\theta }_{0}$, is not rejected by the Mann–Whitney two sample rank test at the (100 × α)%$\left(100×\alpha \right)%$ level.

## References

Lehmann E L (1975) Nonparametrics: Statistical Methods Based on Ranks Holden–Day
McKean J W and Ryan T A (1977) Algorithm 516: An algorithm for obtaining confidence intervals and point estimates based on ranks in the two-sample location problem ACM Trans. Math. Software 10 183–185
Monahan J F (1984) Algorithm 616: Fast computation of the Hodges–Lehman location estimator ACM Trans. Math. Software 10 265–270

## Parameters

### Compulsory Input Parameters

1:     method – string (length ≥ 1)
Specifies the method to be used.
method = 'E'${\mathbf{method}}=\text{'E'}$
The exact algorithm is used.
method = 'A'${\mathbf{method}}=\text{'A'}$
The iterative algorithm is used.
Constraint: method = 'E'${\mathbf{method}}=\text{'E'}$ or 'A'$\text{'A'}$.
2:     x(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
The observations of the first sample, xi${x}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$.
3:     y(m) – double array
m, the dimension of the array, must satisfy the constraint m1${\mathbf{m}}\ge 1$.
The observations of the second sample, yj${y}_{\mathit{j}}$, for j = 1,2,,m$\mathit{j}=1,2,\dots ,m$.
4:     clevel – double scalar
The confidence interval required, 1α$1-\alpha$; e.g., for a 95%$95%$ confidence interval set clevel = 0.95${\mathbf{clevel}}=0.95$.
Constraint: 0.0 < clevel < 1.0$0.0<{\mathbf{clevel}}<1.0$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array x.
n$n$, the size of the first sample.
Constraint: n1${\mathbf{n}}\ge 1$.
2:     m – int64int32nag_int scalar
Default: The dimension of the array y.
m$m$, the size of the second sample.
Constraint: m1${\mathbf{m}}\ge 1$.

wrk iwrk

### Output Parameters

1:     theta – double scalar
The estimate of the difference in the location of the two populations, θ̂$\stackrel{^}{\theta }$.
2:     thetal – double scalar
The estimate of the lower limit of the confidence interval, θl${\theta }_{l}$.
3:     thetau – double scalar
The estimate of the upper limit of the confidence interval, θu${\theta }_{u}$.
4:     estcl – double scalar
An estimate of the actual percentage confidence of the interval found, as a proportion between (0.0,1.0)$\left(0.0,1.0\right)$.
5:     ulower – double scalar
The value of the Mann–Whitney U$U$ statistic corresponding to the lower confidence limit, Ul${U}_{l}$.
6:     uupper – double scalar
The value of the Mann–Whitney U$U$ statistic corresponding to the upper confidence limit, Uu${U}_{u}$.
7:     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:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
 On entry, method ≠ 'E'${\mathbf{method}}\ne \text{'E'}$ or 'A'$\text{'A'}$, or n < 1${\mathbf{n}}<1$, or m < 1${\mathbf{m}}<1$, or clevel ≤ 0.0${\mathbf{clevel}}\le 0.0$, or clevel ≥ 1.0${\mathbf{clevel}}\ge 1.0$.
W ifail = 2${\mathbf{ifail}}=2$
Each sample consists of identical values. All estimates are set to the common difference between the samples.
W ifail = 3${\mathbf{ifail}}=3$
For at least one of the estimates θ̂$\stackrel{^}{\theta }$, θl${\theta }_{l}$ and θu${\theta }_{u}$, the underlying iterative algorithm (when method = 'A'${\mathbf{method}}=\text{'A'}$) failed to converge. This is an unlikely exit but the estimate should still be a reasonable approximation.

## Accuracy

nag_univar_robust_2var_ci (g07eb) should return results accurate to five significant figures in the width of the confidence interval, that is the error for any one of the three estimates should be less than 0.00001 × (thetauthetal)$0.00001×\left({\mathbf{thetau}}-{\mathbf{thetal}}\right)$.

The time taken increases with the sample sizes n$n$ and m$m$.

## Example

```function nag_univar_robust_2var_ci_example
method = 'Approx';
x = [-0.582;
0.157;
-0.523;
-0.769;
2.338;
1.664;
-0.981;
1.549;
1.131;
-0.46;
-0.484;
1.932;
0.306;
-0.602;
-0.979;
0.132;
0.256;
-0.094;
1.065;
-1.084;
-0.969;
-0.524;
0.239;
1.512;
-0.782;
-0.252;
-1.163;
1.376;
1.674;
0.831;
1.478;
-1.486;
-0.808;
-0.429;
-2.002;
0.482;
-1.584;
-0.105;
0.429;
0.568;
0.944;
2.558;
-1.801;
0.242;
0.763;
-0.461;
-1.497;
-1.353;
0.301;
1.941];
y = [1.995;
0.007;
0.997;
1.089;
2.004;
0.171;
0.294;
2.448;
0.214;
0.773;
2.96;
0.025;
0.638;
0.937;
-0.568;
-0.711;
0.931;
2.601;
1.121;
-0.251;
-0.05;
1.341;
2.282;
0.745;
1.633;
0.944;
2.37;
0.293;
0.895;
0.938;
0.199;
0.812;
1.253;
0.59;
1.522;
-0.685;
1.259;
0.571;
1.579;
0.568;
0.381;
0.829;
0.277;
0.656;
2.497;
1.779;
1.922;
-0.174;
2.132;
2.793;
0.102;
1.569;
1.267;
0.49;
0.077;
1.366;
0.056;
0.605;
0.628;
1.65;
0.104;
2.194;
2.869;
-0.171;
-0.598;
2.134;
0.917;
0.63;
0.209;
1.328;
0.368;
0.756;
2.645;
1.161;
0.347;
0.92;
1.256;
-0.052;
1.474;
0.51;
1.386;
3.55;
1.392;
-0.358;
1.938;
1.727;
-0.372;
0.911;
0.499;
0.066;
1.467;
1.898;
1.145;
0.501;
2.23;
0.212;
0.536;
1.69;
1.086;
0.494];
clevel = 0.95;
[theta, thetal, thetau, estcl, ulower, uupper, ifail] = ...
nag_univar_robust_2var_ci(method, x, y, clevel)
```
```

theta =

0.9505

thetal =

0.5650

thetau =

1.3050

estcl =

0.9511

ulower =

2007

uupper =

2993

ifail =

0

```
```function g07eb_example
method = 'Approx';
x = [-0.582;
0.157;
-0.523;
-0.769;
2.338;
1.664;
-0.981;
1.549;
1.131;
-0.46;
-0.484;
1.932;
0.306;
-0.602;
-0.979;
0.132;
0.256;
-0.094;
1.065;
-1.084;
-0.969;
-0.524;
0.239;
1.512;
-0.782;
-0.252;
-1.163;
1.376;
1.674;
0.831;
1.478;
-1.486;
-0.808;
-0.429;
-2.002;
0.482;
-1.584;
-0.105;
0.429;
0.568;
0.944;
2.558;
-1.801;
0.242;
0.763;
-0.461;
-1.497;
-1.353;
0.301;
1.941];
y = [1.995;
0.007;
0.997;
1.089;
2.004;
0.171;
0.294;
2.448;
0.214;
0.773;
2.96;
0.025;
0.638;
0.937;
-0.568;
-0.711;
0.931;
2.601;
1.121;
-0.251;
-0.05;
1.341;
2.282;
0.745;
1.633;
0.944;
2.37;
0.293;
0.895;
0.938;
0.199;
0.812;
1.253;
0.59;
1.522;
-0.685;
1.259;
0.571;
1.579;
0.568;
0.381;
0.829;
0.277;
0.656;
2.497;
1.779;
1.922;
-0.174;
2.132;
2.793;
0.102;
1.569;
1.267;
0.49;
0.077;
1.366;
0.056;
0.605;
0.628;
1.65;
0.104;
2.194;
2.869;
-0.171;
-0.598;
2.134;
0.917;
0.63;
0.209;
1.328;
0.368;
0.756;
2.645;
1.161;
0.347;
0.92;
1.256;
-0.052;
1.474;
0.51;
1.386;
3.55;
1.392;
-0.358;
1.938;
1.727;
-0.372;
0.911;
0.499;
0.066;
1.467;
1.898;
1.145;
0.501;
2.23;
0.212;
0.536;
1.69;
1.086;
0.494];
clevel = 0.95;
[theta, thetal, thetau, estcl, ulower, uupper, ifail] = g07eb(method, x, y, clevel)
```
```

theta =

0.9505

thetal =

0.5650

thetau =

1.3050

estcl =

0.9511

ulower =

2007

uupper =

2993

ifail =

0

```