

   KKaappllaann--MMeeiieerr ssuurrvviivvaall ccuurrvvee aanndd ppeerrcceennttaaggeess aatt sseelleecctteedd
   ttiimmeess

        survsum(formula, data=sys.parent(), sptms=NULL, xlim,
        tlines=T, log=F, xscale=1,yscale=100, mark.time=F, mark=3,
        cex=1, xlab="Time", ylab="Survival (%)", lgd="bl",
        ttl="K-M Survival",...)

   AArrgguummeennttss::

    formula: a formula expression as for other survival models,
             of the  form Surv(time,  status) ~ predictors.
             Same formula expression as used in 'survfit'. See
             help file for survfit.  Maximum of 6 groups.

       data: a data.frame in which to interpret the variables
             named in the formula.

      sptms: a specified vector of positive times at which to
             compute the survival percentages, standard errors,
             and numbers at risk.  A maximum of four times can
             be specified.

       xlim: a vector of the form: c(x1,x2).  The approximate
             minimum and maximum values to  be  put  on  x-
             axis.  Default sets x1=0 and x2=maximum time
             value.

     tlines: a logical value indicating whether vertical lines
             and labels should be drawn on the plot at the
             specified times.

        log: logical value: should the y axis be on a log
             scale?

     xscale: a scalar to be used to divide the x axis.  A value
             of 365, for instance, would be used to convert
             from days to years.

     yscale: a scalar to be used to multiply the y axis.  The
             default value of 100 is used to get a percent
             scale.  'yscale=1' would set the y axis from 0 to
             1.

   mark.time: controls the labeling of the curves.  If set to
             True then curves are marked at each censoring
             time.  If mark.time is a numeric vector, then
             curves are marked at these specified time points.

       mark: vector of mark parameters, which will be used to
             label the  curves.  The vector is resued cycli-
             cally if it  is shorter than the number of curves.

        cex: parameter available to change the size of "mark".
             Not a vector; all marks have the same size.

       xlab: character string label for the x axis.

       ylab: character string label for the y axis.

        lgd: legend placement.  "tr"=top right corner of the
             plot, "under"=under the plot, "n" omits the leg-
             end.  The default is: "bl"=bottom left corner of
             the plot.

        ttl: title to be printed in the center top.

        ...: In addition, the high-level graphics arguments
             described under par and the arguments to title may
             be supplied to this function.

   DDeessccrriippttiioonn::

        The total number of points and events is reported for
        each group.  For each specified time point, group sur-
        vival percentages (followed by standard error and num-
        ber left at risk) are computed.

        The test for a difference bewteen survival curves uses
        the chisquare statistic from the 'survdiff' function
        with rho=0.  This is the log-rank test.

   VVaalluuee::

        A list of class `"htest"', containing the following
        components:

     no.pts: the total number of data points in each group.

   no.events: the total number of events in each group.

      chisq: the chisquare statistic for the test of a differ-
             ence between survival curves.

          p: the p-value for the above test.

         t1: a matrix containing the survival percentages,
             standard errors, and numbers at risk for all
             groups at time t1.

   t2,t3,t4: see above.

   SSiiddee EEffffeeccttss::

        A plot with multiple survival curves is drawn (one for
        each group). This plot includes: overall group statis-
        tics and group statistics at each specified time point
        and a test for a difference between survival curves.

   AAUUTTHHOORR::

        Mark Dietrich, Mayo Clinic Section of Medical Research
        Statistics summer student 1992.

   SSeeee AAllssoo::

        `Surv' `survdiff' `survexp' `survfit'

   EExxaammpplleess::

        survsum (Surv (futime,dead)~sex+dose,data=blood.Dat,sptms=c(20,30,45),
        xlim=c(0,50))
        ##groups are all combinations of 'sex' and 'dose', specified times are 20, 30,
        and 45.

