.-
help for ^permband^                                     (STB-47: sbe25)
.-

Permutation bands for assessing independence
--------------------------------------------


    ^permband^ yvar [xvar] [^in^ range] [^if^ exp] [^,^ ^al^pha^(^#^)^ ^mom^ent^(^#^)^ ^re^ps^(^#^)^ 
        ^se^ed^(^#^)^ ^sp^an^(^#^)^ ^nogr^aph graph_options ]


Description
-----------

^permband^ calculates and displays "permutation bands" for assessing whether a 
selected moment of yvar is indpendent of xvar. If xvar is not supplied it is 
taken to be the order number (1,2,3,..) of the non-missing observations.


Options
-------

^alpha(^#^)^ sets the significance level. The default is 0.05.

^moment(^#^)^ specifies which moment (1,2,3,4) is to be investigated.  The 
    hypothesis test is not performed for the fourth moment. Default: 1.

^reps(^#^)^ sets the number of permutations to be calculated. The hypothesis test
    has been validated only for 50 reps. Default: 50.

^seed(^#^)^ defines the random number seed for selecting random permutations of
    yvar. Default: the current system default value.

^span(^#^)^ determines the width of smoothing window that is applied to yvar.
    Default: as set by @running@ with the ^double^ option.

graph_options is any of Stata's ^graph, twoway^ options except ^sort^.


Remarks
-------

In many applications it may be hypothesised that yvar is independent of xvar.
An example is in age-specific reference intervals, where yvar may be the 
SD- or Z-scores which are supposed to have a standard Normal distribution
independent of time (xvar). The alternative is that some kind of trend of
unspecified (but possibly complex) functional form is present. Another 
example is in regression analysis, where yvar are residuals and xvar is
a covariate in or out of the model, or perhaps the order of the observations,
which might represent time ordering.

^permband^ first smooths yvar^^moment on xvar using a locally linear smoother
(^running^). The process is then repeated ^reps(^#^)^ times, with the order of
the yvar values permuted at random at each replicate. The minimum and maximum
values of the resulting smooths at each value of xvar form the "permutation
band". This band and the original smooth are plotted against xvar. 

If yvar^^moment and xvar are independent we would expect the original smooth to
wander between the lower and upper boundaries of the permutation band. If
it crosses a boundary somewhere, there may be evidence of dependence. Based
on 50 replications and the default span, the proportions of values expected 
outside the permutation band have been evaluated and are formulated as a 
hypothesis test. For more details see Royston and Wright (1998).


Examples
--------

 . ^use igg.dta^
 . ^xrigls sqrtigg age^
 . ^permband Z_gls age^
 . ^permband Z_gls age, moment(2) seed(12)^


Reference
---------

Atkinson AC. 1985. Plots, transformations and regression. Oxford Statistical
    Science Series - 1, pp 34-37. Oxford University Press, Oxford.

P. Royston and E.M. Wright (1998) "Goodness-of-fit statistics for age-specific
 reference intervals."


Authors
-------

       Eileen M. Wright, 
       Imperial College School of Medicine, UK
       ewright@@rpms.ac.uk

       Patrick Royston,
       Imperial College School of Medicine, UK
       proyston@@rpms.ac.uk


Also see
--------

    STB:  STB-47 sbe25
On-line:  ^help^ for @running@