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

Calculate and Plot the semi-parametric ROC curve
------------------------------------------------

    ^dfroc^ test_var disease_var [^if^ exp] [^in^ range]
         [^,^ ^nog^raph ^nobs^trap ^n^samp^(^#^)^ ^cc^samp graph_options
           ^l^ink^(logit^|^probit)^ ^roc^t^(^t^)^ ^par^tial^(^#^)^ ^l^evel^(^#^)^
           ^res^file^(^filename^)^ ^replace^]

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

^dfroc^ calculates the distribution-free estimator of the ROC curve within
a GLM binary regression framework.  Bootstrap standard errors for the binormal
ROC parameters and corresponding area under the curve (AUC) estimates are
obtained.  ^test_var^ is the continuous test measure variable and ^disease_var^
is the  0/1 (disease) group indicator variable.

Parameters a & b correspond to the binormal ROC curve:

    ROC(t) = PHI(a + b*PHI^^(-1)(t))

Binormal ROC parameter estimates and bootstrap standard errors are available as
returned results after running the program, as are the AUC and bootstrap
standard error estimates:

    r(a)   r(a_se)
    r(b)   r(b_se)
    r(auc) r(auc_se)

The bootstrap Variance-Covariance matrix for (a,b) is available as:

    r(Cov)

The parameteric ROC(t) and bootstrap se estimates are optionally calculated
from the binormal parameter estimates for specified t, and are returned as:

    r(roc)   r(roc_se)


Options
-------

^nograph^ suppresses graphical output.

^nobstrap^ omits bootstrap calculation of standard errors.

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

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

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

^link(^linkname^)^ specifies the type of GLM model to be used for estimation.
    Currently only ^probit^ and ^logit^ are allowed.  ^probit^ is the default.

^partial(^fp%^)^ specifies that estimates of the ROC curve parameters are to be
    based on a restricted range of the false positive rate, FP <= fp%.  The
    argument for ^partial()^ must be a number between 1 & 100.  If this option
    is specified results for the auc and its standard error are not returned.

^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.

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

^resfile(^filename^)^ creates a Stata file (^.dta^ file) with the bootstrap
    distribution of parameters a, b, and the AUC estimate.

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


Remarks
-------

^dfroc^ generates datasets with all possible pairwise combinations of diseased
and non-diseased observations in a given sample and may require that a large
amount of memory be specified before running (see help @memory@).  If the error
message "no room to add more variables" results, allocate more memory and try
again.

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

This program may run slowly on some platforms when large numbers of bootstrap
samples are specified.  It is recommended that a trial run be done with a small
number of samples.


References
----------

    Pepe, MS. An interpretation for the ROC curve and inference using GLM
        procedures.  Biometrics, 56:352-359, 2000.


Authors
-------

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

        Margaret Pepe, Univ. of Washington & Fred Hutchinson Cancer Research Ctr.
        mspepe@@u.washington.edu


Also see
--------

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