G07EAF (PDF version)
G07 Chapter Contents
G07 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G07EAF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

G07EAF computes a rank based (nonparametric) estimate and confidence interval for the location parameter of a single population.

2  Specification

SUBROUTINE G07EAF ( METHOD, N, X, CLEVEL, THETA, THETAL, THETAU, ESTCL, WLOWER, WUPPER, WRK, IWRK, IFAIL)
INTEGER  N, IWRK(3*N), IFAIL
REAL (KIND=nag_wp)  X(N), CLEVEL, THETA, THETAL, THETAU, ESTCL, WLOWER, WUPPER, WRK(4*N)
CHARACTER(1)  METHOD

3  Description

Consider a vector of independent observations, x=x1,x2,,xnT with unknown common symmetric density fxi-θ. G07EAF computes the Hodges–Lehmann location estimator (see Lehmann (1975)) of the centre of symmetry θ, together with an associated confidence interval. The Hodges–Lehmann estimate is defined as
θ^=median xi+xj2,1ijn .  
Let m=nn+1/2 and let ak, for k=1,2,,m denote the m ordered averages xi+xj/2 for 1ijn. Then
This estimator arises from inverting the one-sample Wilcoxon signed-rank test statistic, Wx-θ0, for testing the hypothesis that θ=θ0. Effectively Wx-θ0 is a monotonically decreasing step function of θ0 with
mean ​W=μ= nn+14, varW=σ2= nn+12n+124.  
The estimate θ^ is the solution to the equation Wx-θ^=μ; two methods are available for solving this equation. These methods avoid the computation of all the ordered averages ak; 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 xi+xj/2 for ij. 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 Wx-θ0 which is asymptotically linear as a function of θ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-α, expressed as a proportion between 0 and 1, initial estimates for the lower and upper confidence limits of the Wilcoxon statistic are found from
Wl=μ-0.5+σΦ-1α/2  
and
Wu=μ+ 0.5+σ Φ-11-α /2,  
where Φ-1 is the inverse cumulative Normal distribution function.
Wl and Wu are rounded to the nearest integer values. These estimates are then refined using an exact method if n80, and a Normal approximation otherwise, to find Wl and Wu satisfying
PWWlα/2 PWWl+1>α/2  
and
PWWuα /2 PWWu- 1>α /2.  
Let Wu=m-k; then θl=ak+1. This is the largest value θl such that Wx-θl=Wu.
Let Wl=k; then θu=am-k. This is the smallest value θu such that Wx-θu=Wl.
As in the case of θ^, these equations may be solved using either the exact or the iterative methods to find the values θl and θu.
Then θl,θu is the confidence interval for θ. The confidence interval is thus defined by those values of θ0 such that the null hypothesis, θ=θ0, is not rejected by the Wilcoxon signed-rank test at the 100×α% 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 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

5  Parameters

1:     METHOD – CHARACTER(1)Input
On entry: specifies the method to be used.
METHOD='E'
The exact algorithm is used.
METHOD='A'
The iterative algorithm is used.
Constraint: METHOD='E' or 'A'.
2:     N – INTEGERInput
On entry: n, the sample size.
Constraint: N2.
3:     XN – REAL (KIND=nag_wp) arrayInput
On entry: the sample observations, xi, for i=1,2,,n.
4:     CLEVEL – REAL (KIND=nag_wp)Input
On entry: the confidence interval desired.
For example, for a 95% confidence interval set CLEVEL=0.95.
Constraint: 0.0<CLEVEL<1.0.
5:     THETA – REAL (KIND=nag_wp)Output
On exit: the estimate of the location, θ^.
6:     THETAL – REAL (KIND=nag_wp)Output
On exit: the estimate of the lower limit of the confidence interval, θl.
7:     THETAU – REAL (KIND=nag_wp)Output
On exit: the estimate of the upper limit of the confidence interval, θu.
8:     ESTCL – REAL (KIND=nag_wp)Output
On exit: an estimate of the actual percentage confidence of the interval found, as a proportion between 0.0,1.0.
9:     WLOWER – REAL (KIND=nag_wp)Output
On exit: the upper value of the Wilcoxon test statistic, Wu, corresponding to the lower limit of the confidence interval.
10:   WUPPER – REAL (KIND=nag_wp)Output
On exit: the lower value of the Wilcoxon test statistic, Wl, corresponding to the upper limit of the confidence interval.
11:   WRK4×N – REAL (KIND=nag_wp) arrayWorkspace
12:   IWRK3×N – INTEGER arrayWorkspace
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

If on entry 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:
IFAIL=1
On entry,METHOD'E' or 'A',
orN<2,
orCLEVEL0.0,
orCLEVEL1.0.
IFAIL=2
There is not enough information to compute a confidence interval since the whole sample consists of identical values.
IFAIL=3
For at least one of the estimates θ^, θl and θu, the underlying iterative algorithm (when METHOD='A') failed to converge. This is an unlikely exit but the estimate should still be a reasonable approximation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.8 in the Essential Introduction for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.7 in the Essential Introduction for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.6 in the Essential Introduction 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×THETAU-THETAL.

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 implementation-specific information.

9  Further Comments

The time taken increases with the sample size n.

10  Example

The following program calculates a 95% confidence interval for θ, a measure of symmetry of the sample of 50 observations.

10.1  Program Text

Program Text (g07eafe.f90)

10.2  Program Data

Program Data (g07eafe.d)

10.3  Program Results

Program Results (g07eafe.r)


G07EAF (PDF version)
G07 Chapter Contents
G07 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2015