NAG CL Interface
g07ebc (robust_2var_ci)
1
Purpose
g07ebc calculates a rank based (nonparametric) estimate and confidence interval for the difference in location between two independent populations.
2
Specification
void 
g07ebc (Nag_RCIMethod method,
Integer n,
const double x[],
Integer m,
const double y[],
double clevel,
double *theta,
double *thetal,
double *thetau,
double *estcl,
double *ulower,
double *uupper,
NagError *fail) 

The function may be called by the names: g07ebc, nag_univar_robust_2var_ci or nag_rank_ci_2var.
3
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={\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)}^{\mathrm{T}}$, have distribution $F\left(x\right)$ and the random sample, $y={\left({y}_{1},{y}_{2},\dots ,{y}_{m}\right)}^{\mathrm{T}}$, have distribution $F\left(x\theta \right)$.
g07ebc finds a point estimate,
$\hat{\theta}$, of the difference in location
$\theta $ together with an associated confidence interval. The estimates are based on the ordered differences
${y}_{j}{x}_{i}$. The estimate
$\hat{\theta}$ is defined by
Let
${d}_{\mathit{k}}$, for
$\mathit{k}=1,2,\dots ,nm$, denote the
$nm$ (ascendingly) ordered differences
${y}_{\mathit{j}}{x}_{\mathit{i}}$, for
$\mathit{i}=1,2,\dots ,n$ and
$\mathit{j}=1,2,\dots ,m$. Then
 if $nm$ is odd, $\hat{\theta}={d}_{k}$ where $k=\left(nm1\right)/2$;
 if $nm$ is even, $\hat{\theta}=\left({d}_{k}+{d}_{k+1}\right)/2$ where $k=nm/2$.
This estimator arises from inverting the two sample Mann–Whitney rank test statistic,
$U\left({\theta}_{0}\right)$, for testing the hypothesis that
$\theta ={\theta}_{0}$. Thus
$U\left({\theta}_{0}\right)$ is the value of the Mann–Whitney
$U$ statistic for the two independent samples
$\left\{\left({x}_{i}+{\theta}_{0}\right)\text{, for}i=1,2,\dots ,n\right\}$ and
$\left\{{y}_{j}\text{, for}j=1,2,\dots ,m\right\}$. Effectively
$U\left({\theta}_{0}\right)$ is a monotonically increasing step function of
${\theta}_{0}$ with
The estimate
$\hat{\theta}$ is the solution to the equation
$U\left(\hat{\theta}\right)=\mu $; two methods are available for solving this equation. These methods avoid the computation of all the ordered differences
${d}_{k}$; this is because for large
$n$ and
$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
${y}_{\mathit{j}}{x}_{\mathit{i}}$, for
$\mathit{i}=1,2,\dots ,n$ and
$\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\left({\theta}_{0}\right)$ which is asymptotically linear as a function of
${\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\alpha $, expressed as a proportion between
$0.0$ and
$1.0$ initial estimates of the upper and lower confidence limits for the Mann–Whitney
$U$ statistic are found;
where
${\Phi}^{1}$ is the inverse cumulative Normal distribution function.
${U}_{l}$ and
${U}_{u}$ are rounded to the nearest integer values. These estimates are refined using an exact method, without taking ties into account, if
$n+m\le 40$ and
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(n,m\right)\le 30$ and a Normal approximation otherwise, to find
${U}_{l}$ and
${U}_{u}$ satisfying
and
The function
$U\left({\theta}_{0}\right)$ is a monotonically increasing step function. It is the number of times a score in the second sample,
${y}_{j}$, precedes a score in the first sample,
${x}_{i}+\theta $, where we only count a half if a score in the second sample actually equals a score in the first.
Let ${U}_{l}=k$; then ${\theta}_{l}={d}_{k+1}$. This is the largest value ${\theta}_{l}$ such that $U\left({\theta}_{l}\right)={U}_{l}$.
Let ${U}_{u}=nmk$; then ${\theta}_{u}={d}_{nmk}$. This is the smallest value ${\theta}_{u}$ such that $U\left({\theta}_{u}\right)={U}_{u}$.
As in the case of $\hat{\theta}$, these equations may be solved using either the exact or iterative methods to find the values ${\theta}_{l}$ and ${\theta}_{u}$.
Then $\left({\theta}_{l},{\theta}_{u}\right)$ is the confidence interval for $\theta $. The confidence interval is thus defined by those values of ${\theta}_{0}$ such that the null hypothesis, $\theta ={\theta}_{0}$, is not rejected by the Mann–Whitney two sample rank test at the $\left(100\times \alpha \right)\%$ level.
4
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 twosample 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
5
Arguments

1:
$\mathbf{method}$ – Nag_RCIMethod
Input

On entry: specifies the method to be used.
 ${\mathbf{method}}=\mathrm{Nag\_RCI\_Exact}$
 The exact algorithm is used.
 ${\mathbf{method}}=\mathrm{Nag\_RCI\_Approx}$
 The iterative algorithm is used.
Constraint:
${\mathbf{method}}=\mathrm{Nag\_RCI\_Exact}$ or $\mathrm{Nag\_RCI\_Approx}$.

2:
$\mathbf{n}$ – Integer
Input

On entry: $n$, the size of the first sample.
Constraint:
${\mathbf{n}}\ge 1$.

3:
$\mathbf{x}\left[{\mathbf{n}}\right]$ – const double
Input

On entry: the observations of the first sample,
${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.

4:
$\mathbf{m}$ – Integer
Input

On entry: $m$, the size of the second sample.
Constraint:
${\mathbf{m}}\ge 1$.

5:
$\mathbf{y}\left[{\mathbf{m}}\right]$ – const double
Input

On entry: the observations of the second sample,
${y}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,m$.

6:
$\mathbf{clevel}$ – double
Input

On entry: the confidence interval required, $1\alpha $; e.g., for a $95\%$ confidence interval set ${\mathbf{clevel}}=0.95$.
Constraint:
$0.0<{\mathbf{clevel}}<1.0$.

7:
$\mathbf{theta}$ – double *
Output

On exit: the estimate of the difference in the location of the two populations, $\hat{\theta}$.

8:
$\mathbf{thetal}$ – double *
Output

On exit: the estimate of the lower limit of the confidence interval, ${\theta}_{l}$.

9:
$\mathbf{thetau}$ – double *
Output

On exit: the estimate of the upper limit of the confidence interval, ${\theta}_{u}$.

10:
$\mathbf{estcl}$ – double *
Output

On exit: an estimate of the actual percentage confidence of the interval found, as a proportion between $\left(0.0,1.0\right)$.

11:
$\mathbf{ulower}$ – double *
Output

On exit: the value of the Mann–Whitney $U$ statistic corresponding to the lower confidence limit, ${U}_{l}$.

12:
$\mathbf{uupper}$ – double *
Output

On exit: the value of the Mann–Whitney $U$ statistic corresponding to the upper confidence limit, ${U}_{u}$.

13:
$\mathbf{fail}$ – NagError *
Input/Output

The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error Indicators and Warnings
 NE_ALLOC_FAIL

Dynamic memory allocation failed.
See
Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
 NE_BAD_PARAM

On entry, argument $\u2329\mathit{\text{value}}\u232a$ had an illegal value.
 NE_CONVERGENCE

The iterative procedure used to estimate $\theta $ has not converged. This is an unlikely exit but the estimate should still be a reasonable approximation.
The iterative procedure used to estimate, ${\theta}_{l}$, the lower confidence limit has not converged. This is an unlikely exit but the estimate should still be a reasonable approximation.
The iterative procedure used to estimate, ${\theta}_{u}$, the upper confidence limit has not converged. This is an unlikely exit but the estimate should still be a reasonable approximation.
 NE_INT

On entry, ${\mathbf{m}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{m}}\ge 1$.
On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}\ge 1$.
 NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact
NAG for assistance.
See
Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
 NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library CL Interface for further information.
 NE_REAL

On entry, ${\mathbf{clevel}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: $0.0<{\mathbf{clevel}}<1.0$.
 NE_SAMPLE_IDEN

Not enough information to compute an interval estimate since each sample has identical values. The common difference is returned in
theta,
thetal and
thetau.
7
Accuracy
g07ebc 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\times \left({\mathbf{thetau}}{\mathbf{thetal}}\right)$.
8
Parallelism and Performance
g07ebc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g07ebc makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
The time taken increases with the sample sizes $n$ and $m$.
10
Example
The following program calculates a 95% confidence interval for the difference in location between the two populations from which the two samples of sizes $50$ and $100$ are drawn respectively.
10.1
Program Text
10.2
Program Data
10.3
Program Results