.-
help for ^emroc^                                                     (vers 1.3)
.-

Plot the empirical ROC curve
-----------------------------

    ^emroc^ test_var disease_var [^if^ exp] [^in^ range]
        [^,^ ^nog^raph ^l^evel^(^#^)^ graph_options
        ^par^tial^(^#^)^
        ^gense^ns^(^varname^) gensp^ec^(^varname^)^
        ^conf^band ^kern^al^(^kernal name^)^ ^kwid^th^(^#^)^
        ^genk^d^(^newvar_kdd newvar_kddb^)^ ^replace^]


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

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

The empirical ROC is a plot of observed sensitivities vs. 1-specificities at
cutpoints corresponding to distinct test values in the dataset.

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 Var(AUC) are available as returned results after running the program:
    r(auc)
    r(aucvar)

Sensitivities and specificities are optionally saved as new variables.

Confidence bands are optionally plotted with the ROC.

Kernal density estimates used in calculating the confidence bands are
  optionally saved as new variables.

Options
-------

^nograph^ suppresses graphical output.

graph_options are any of the options allowed with ^graph, twoway^; see help
    @grtwoway@.

^partial(^fp%^)^ specifies that the partial AUC for FP <= fp% is to be returned
    in addition to 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).

^gensens(^varname^)^, and ^genspec(^varname^)^ specify the names of new variables
    created to contain sensitivities and specificities.

^replace^ requests that if existing variables are specified for ^gensens()^,
    ^genspec()^, or ^genkd()^, they should be overwritten.

^confband^ specifies that confidence bands are to be plotted with the ROC curve.

^level^ specifies the confidence level, in percent, for calculation of confidence
    bands around the ROC curve.

^kernal(^kernal name^)^ specifies the kernal option for the kernal density
    calculation used in computing the confidence bands.  This is passed to the
    kdensity command.  see help ^kdensity^.  By default the Epanechnikov
    density is used.

^kwidth(^#^)^ specifies the halfwidth of the kernal, the width of the density
    window around each point.  See ^[R] kdensity^ regarding the default
    "optimal width".

^genkd(^newvar_kdd newvar_kddb^)^ specifies the names of variables to contain the
    kernal density estimates of the test measure distribution among diseased and
    non-diseased respectively.

Remarks
-------

Calculation of the AUC assumes that higher test values are associated with
disease.  (Alternatively the correct AUC will be 1-AUC calculated here.)

In defining sensitivities and specificities, a positive test is defined by
y >= c for cutpoint c.


References
----------


Author
------

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


Also see
--------

   Manual:  [R]roc

  On line:  help for @roctab@, @lroc@,
            @dfroc@ if installed, @aucbs@ if installed
            @rocsize@ if installed, @aucsize@ if installed

