NAG FL Interface
g07eaf (robust_1var_ci)
1
Purpose
g07eaf computes a rank based (nonparametric) estimate and confidence interval for the location parameter of a single population.
2
Specification
Fortran Interface
Subroutine g07eaf ( 
method, n, x, clevel, theta, thetal, thetau, estcl, wlower, wupper, wrk, iwrk, ifail) 
Integer, Intent (In) 
:: 
n 
Integer, Intent (Inout) 
:: 
ifail 
Integer, Intent (Out) 
:: 
iwrk(3*n) 
Real (Kind=nag_wp), Intent (In) 
:: 
x(n), clevel 
Real (Kind=nag_wp), Intent (Out) 
:: 
theta, thetal, thetau, estcl, wlower, wupper, wrk(4*n) 
Character (1), Intent (In) 
:: 
method 

C Header Interface
#include <nag.h>
void 
g07eaf_ (const char *method, const Integer *n, const double x[], const double *clevel, double *theta, double *thetal, double *thetau, double *estcl, double *wlower, double *wupper, double wrk[], Integer iwrk[], Integer *ifail, const Charlen length_method) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
g07eaf_ (const char *method, const Integer &n, const double x[], const double &clevel, double &theta, double &thetal, double &thetau, double &estcl, double &wlower, double &wupper, double wrk[], Integer iwrk[], Integer &ifail, const Charlen length_method) 
}

The routine may be called by the names g07eaf or nagf_univar_robust_1var_ci.
3
Description
Consider a vector of independent observations,
$x={\left({x}_{1},{x}_{2},\dots ,{x}_{n}\right)}^{\mathrm{T}}$ with unknown common symmetric density
$f\left({x}_{i}\theta \right)$.
g07eaf computes the Hodges–Lehmann location estimator (see
Lehmann (1975)) of the centre of symmetry
$\theta $, together with an associated confidence interval. The Hodges–Lehmann estimate is defined as
Let
$m=\left(n\left(n+1\right)\right)/2$ and let
${a}_{\mathit{k}}$, for
$\mathit{k}=1,2,\dots ,m$ denote the
$m$ ordered averages
$\left({x}_{i}+{x}_{j}\right)/2$ for
$1\le i\le j\le n$. Then
 if $m$ is odd, $\hat{\theta}={a}_{k}$ where $k=\left(m+1\right)/2$;
 if $m$ is even, $\hat{\theta}=\left({a}_{k}+{a}_{k+1}\right)/2$ where $k=m/2$.
This estimator arises from inverting the onesample Wilcoxon signedrank test statistic,
$W\left(x{\theta}_{0}\right)$, for testing the hypothesis that
$\theta ={\theta}_{0}$. Effectively
$W\left(x{\theta}_{0}\right)$ is a monotonically decreasing step function of
${\theta}_{0}$ with
The estimate
$\hat{\theta}$ is the solution to the equation
$W\left(x\hat{\theta}\right)=\mu $; two methods are available for solving this equation. These methods avoid the computation of all the ordered averages
${a}_{k}$; this is because for large
$n$ both the storage requirements and the computation time would be excessive.
The first is an exact method based on a set partitioning procedure on the set of all ordered averages
$\left({x}_{i}+{x}_{j}\right)/2$ for
$i\le j$. This is based on the algorithm proposed by
Monahan (1984).
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
$W\left(x{\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 Wilcoxon test statistic.
Given a desired percentage for the confidence interval,
$1\alpha $, expressed as a proportion between
$0$ and
$1$, initial estimates for the lower and upper confidence limits of the Wilcoxon statistic are found from
and
where
${\Phi}^{1}$ is the inverse cumulative Normal distribution function.
${W}_{l}$ and
${W}_{u}$ are rounded to the nearest integer values. These estimates are then refined using an exact method if
$n\le 80$, and a Normal approximation otherwise, to find
${W}_{l}$ and
${W}_{u}$ satisfying
and
Let
${W}_{u}=mk$; then
${\theta}_{l}={a}_{k+1}$. This is the largest value
${\theta}_{l}$ such that
$W\left(x{\theta}_{l}\right)={W}_{u}$.
Let ${W}_{l}=k$; then ${\theta}_{u}={a}_{mk}$. This is the smallest value ${\theta}_{u}$ such that $W\left(x{\theta}_{u}\right)={W}_{l}$.
As in the case of $\hat{\theta}$, these equations may be solved using either the exact or the 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 Wilcoxon signedrank test at the $\left(100\times \alpha \right)\%$ level.
4
References
Lehmann E L (1975) Nonparametrics: Statistical Methods Based on Ranks Holden–Day
Marazzi A (1987) Subroutines for robust estimation of location and scale in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 1 Institut Universitaire de Médecine Sociale et Préventive, Lausanne
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}$ – Character(1)
Input

On entry: specifies the method to be used.
 ${\mathbf{method}}=\text{'E'}$
 The exact algorithm is used.
 ${\mathbf{method}}=\text{'A'}$
 The iterative algorithm is used.
Constraint:
${\mathbf{method}}=\text{'E'}$ or $\text{'A'}$.

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

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

3:
$\mathbf{x}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) array
Input

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

4:
$\mathbf{clevel}$ – Real (Kind=nag_wp)
Input

On entry: the confidence interval desired.
For example, for a $95\%$ confidence interval set ${\mathbf{clevel}}=0.95$.
Constraint:
$0.0<{\mathbf{clevel}}<1.0$.

5:
$\mathbf{theta}$ – Real (Kind=nag_wp)
Output

On exit: the estimate of the location, $\hat{\theta}$.

6:
$\mathbf{thetal}$ – Real (Kind=nag_wp)
Output

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

7:
$\mathbf{thetau}$ – Real (Kind=nag_wp)
Output

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

8:
$\mathbf{estcl}$ – Real (Kind=nag_wp)
Output

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

9:
$\mathbf{wlower}$ – Real (Kind=nag_wp)
Output

On exit: the upper value of the Wilcoxon test statistic, ${W}_{u}$, corresponding to the lower limit of the confidence interval.

10:
$\mathbf{wupper}$ – Real (Kind=nag_wp)
Output

On exit: the lower value of the Wilcoxon test statistic, ${W}_{l}$, corresponding to the upper limit of the confidence interval.

11:
$\mathbf{wrk}\left(4\times {\mathbf{n}}\right)$ – Real (Kind=nag_wp) array
Workspace

12:
$\mathbf{iwrk}\left(3\times {\mathbf{n}}\right)$ – Integer array
Workspace


13:
$\mathbf{ifail}$ – Integer
Input/Output

On entry:
ifail must be set to
$0$,
$1$ or
$1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value
$1$ or
$1$ is recommended. If message printing is undesirable, then the value
$1$ is recommended. Otherwise, the value
$0$ is recommended.
When the value $\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{clevel}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: $0.0<{\mathbf{clevel}}<1.0$.
On entry, ${\mathbf{method}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{method}}=\text{'E'}$ or $\text{'A'}$.
On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}\ge 2$.
 ${\mathbf{ifail}}=2$

Not enough information to compute an interval estimate since the whole sample is identical. The common value is returned in
theta,
thetal and
thetau.
 ${\mathbf{ifail}}=3$

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.
The iterative procedure used to estimate $\theta $ has not converged. This is an unlikely exit but the estimate should still be a reasonable approximation.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
g07eaf should produce 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
g07eaf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
The time taken increases with the sample size $n$.
10
Example
The following program calculates a 95% confidence interval for $\theta $, a measure of symmetry of the sample of $50$ observations.
10.1
Program Text
10.2
Program Data
10.3
Program Results