.-
help for ^aucbs^                                                   (version 1.3)
.-

Calculate the nonparametric AUC and bootstrapped s.e.
-----------------------------------------------------

    ^aucbs^ test_var [test_var2] disease_var [^if^ exp] [^in^ range]
         [^,^ ^cc^samp ^n^samp^(^#^)^ ^roc^_e^(^t^)^ ^par^tial^(^#^)^ ^l^evel^(^#^)^
          ^cl^uster^(^varnames^)^ ^res^file^(^filename^)^ ^replace^]


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

^aucbs^ calculates a nonparametric estimate of the area under the ROC curve
(AUC) and a bootstrapped standard error estimate.   ^test_var^ is the
continuous test measure variable and ^disease_var^ is the  0/1 (disease) group
indicator variable.

Optionally the partial AUC for a restricted false positive range, FPR < a
specified fp%, is calculated, along with its standard error.

The empirical ROC estimate is optionally returned at specified false positive
rate (fp%).

If a second test variable, ^test_var2^ is included, The AUC difference and its
standard error are included along with AUC estimates for both tests.  ROC
difference statistics are included if the ^roc(t)^ option is included.

The nonparametric AUC estimate comes from the Mann-Whitney form of the
two-sample Wilcoxon rank-sum statistic and is equivalent to the trapezoidal
area under the empirical ROC curve.

The AUC and bootstrap standard error are available as returned results after
running the program:

    r(auc)        or    r(auc1)      r(auc2)       r(aucdelta)
    r(se_auc)     or    r(se_auc1)   r(se_auc2)    r(se_aucdl)

Alternatively, the partial AUC and bootstrap standard error are returned, along
with the upper boundary for the false positive rate specified with the
partial(#) option.

    r(pauc)       or  r(pauc1)     r(pauc2)       r(aucdelta)
    r(se_pauc)    or  r(se_pauc1)  r(se_pauc2)    r(se_aucdl)
    r(pauc_t)

The empirical ROC estimate and bootstrap standard error are optionally
returned for false postive rate, t, specified with the roc_t(#) option.

    r(roct)       or  r(roc1t)     r(roc2t)       r(rocdelta)
    r(se_roct)    or  r(se_roc1t)  r(se_roc2t)    r(se_rocdl)
    r(t)


Options
-------

^test_var2^: AUC [and ROC(t)] for both screening tests are returned along
    with difference statistics.  Assumes paired data, i.e that results for
    both screening tests are available for each subject, and that observations
    correspond to subjects.

^ccsamp^ specifies that case/control sampling is to be done.  I.e. bootstrap
    samples are drawn separately from the observed case and control samples.
    If this option is not specified, bootstrap samples are drawn from the
    observed data without respect to disease status.

^nsamp(^#^)^ specifies the number of bootstrap samples to be drawn.  The default
    is 50.

^resfile(^filename^)^ creates a Stata file (^.dta^ file) with the bootstrap
    distribution of the AUC estimate.  @bstat@ can be run on this file, when
    loaded in memory, to view bootstrap results again.

^replace^ requests that if an existing file is specified for saving bootstrap
    results it should be overwritten.

^partial(^fp%^)^ specifies that the partial AUC for FP <= fp% is to be returned
    instead of the total AUC.  The argument for the ^partial()^ must be a
    number between 1 & 100.  The partial AUC and the corresponding fp% are
    available as returned results r(pauc) & r(pauc_t).

^roc_e(^fp%^)^ requests that the empirical ROC estimate and bootstrap se at
    specified false positive rate, t = fp%, be calculated and returned.  The
    argument for ^roc_e()^ must be a number between 1 & 100.

^level(^#^)^ specifies the confidence level, in percent, for calculation of
    confidence limits for the AUC.  See help @level@.  Confidence limits are
    calculated by @bstat@ using 3 different methods: normal approximation,
    percentile, and bias-corrected.

^cluster(^varnames^)^ specifies the variables identifying resampling clusters.
    If specified, each bootstrap sample drawn is a sample of clusters.
    (see help @bsample@).  The number of clusters drawn is the number of
    clusters in the original dataset.  Unless all clusters contain the same
    number of observations, resulting sample sizes will differ from sample to
    sample.


Remarks
-------

Persons interested in reproducibility of results should set the random-number
seed by typing set seed # before running ^aucbs^; see help @generate@.

When two test variables are specified, observations with data missing for
either of the test variables are ignored in the calculation of statistics for
both screening tests.


Author
------

        Gary Longton, Fred Hutchinson Cancer Research Ctr.
        glongton@@fhcrc.org


Also see
--------

 On line: help for @emroc@ if installed, @roctab@ if installed,
          @dfroc@ if installed, @bsample@ or @bstat@, @postfile@.
