survplot               package:Design               R Documentation

_P_l_o_t _S_u_r_v_i_v_a_l _C_u_r_v_e_s _a_n_d _H_a_z_a_r_d _F_u_n_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Plot estimated survival curves, and for parametric survival
     models, plot hazard functions.  There is an option to print the
     number of subjects at risk at the start of each time interval. 
     Curves are automatically labeled at the points of maximum
     separation (using the 'labcurve' function), and there are many
     other options for labeling that can be specified with the
     'label.curves' parameter.  For example, different plotting symbols
     can be placed at constant x-increments and a legend linking the
     symbols with category labels can automatically positioned on the
     most empty portion of the plot.

_U_s_a_g_e:

     survplot(fit, ...)
     ## S3 method for class 'Design':
     survplot(fit, ..., xlim,
              ylim=if(loglog) c(-5, 1.5) else if
                      (what == "survival" & missing(fun)) c(0, 1),
              xlab, ylab, time.inc,
              what=c("survival","hazard"),
              type=c("tsiatis","kaplan-meier"),
              conf.type=c("log-log","log","plain","none"),
              conf.int=FALSE, conf=c("bars","bands"),
              add=FALSE, label.curves=TRUE,
              abbrev.label=FALSE, lty, lwd=par("lwd"), col=1,
              adj.subtitle, loglog=FALSE, fun,
              n.risk=FALSE, logt=FALSE, dots=FALSE, dotsize=.003,
              grid=FALSE, srt.n.risk=0, sep.n.risk=0.056, adj.n.risk=1, 
              y.n.risk, cex.n.risk=.6, pr=FALSE)
     ## S3 method for class 'survfit':
     survplot(fit, xlim, 
              ylim, xlab, ylab, time.inc,
              conf=c("bars","bands","none"), add=FALSE, 
              label.curves=TRUE, abbrev.label=FALSE,
              lty,lwd=par('lwd'),col=1,
              loglog=FALSE,fun,n.risk=FALSE,logt=FALSE,
              dots=FALSE,dotsize=.003,
              grid=FALSE,
              srt.n.risk=0,sep.n.risk=.056,adj.n.risk=1,
              y.n.risk,cex.n.risk=.6, pr=FALSE, ...)

_A_r_g_u_m_e_n_t_s:

     fit: result of fit ('cph', 'psm', 'survfit', 'survest.psm') 

     ...: list of factors with names used in model. For fits from
          'survfit', these arguments do not appear - all strata are
          plotted. Otherwise the first factor  listed is the factor
          used to determine different survival curves.  Any other
          factors are used to specify single constants to be adjusted
          to, when defaults given to fitting routine (through 'limits')
          are not used.   The value given to factors is the original
          coding of data given to fit, except that for categorical or
          strata factors the text string levels may be specified.  The
          form of values given to the first factor are 'NA' (use
          default range or list of all values if variable is discrete),
          '"text"' if factor is categorical, 'c(value1, value2, ...)',
          or a function which returns a vector, such as 
          'seq(low,high,by=increment)'.  'NA' may be specified only for
          the first factor. In this case the 'Low effect', 'Adjust to',
          and 'High effect' values will be used from 'datadist' if the
          variable is continuous. For variables not defined to
          'datadist', you must specify non-missing constant settings
          (or a vector of settings for the one displayed variable).
          Note that since 'survfit' objects do not use the variable
          list in '...', you can specify any extra arguments to
          'labcurve' by adding them at the end of the list of
          arguments. 

    xlim: a vector of two numbers specifiying the x-axis range for
          follow-up time. Default is '(0,maxtime)' where 'maxtime' was
          the 'pretty()'d version of the maximum follow-up time in any
          stratum, stored in 'fit$maxtime'.  If 'logt=TRUE', default is
          '(1, log(maxtime))'. 

    ylim: y-axis limits.  Default is 'c(0,1)' for survival, and
          'c(-5,1.5)' if 'loglog=TRUE'. If 'fun' or 'loglog=TRUE' are
          given and 'ylim' is not,  the limits will be computed from
          the data.  For 'what="hazard"', default limits are computed
          from the first hazard function plotted. 

    xlab: x-axis label.  Default is 'units' attribute of failure time
          variable given to 'Surv'. 

    ylab: y-axis label.  Default is '"Survival Probability"' or 
          '"log(-log Survival Probability)"'. If 'fun' is given, the
          default is '""'.  For 'what="hazard"', the default is
          '"Hazard Function"'. 

time.inc: time increment for labeling the x-axis and printing numbers
          at risk.  If not specified, the value of 'time.inc' stored
          with the model fit will be used. 

    type: specifies type of estimates, '"tsiatis"' (the default) or
          '"kaplan-meier"'. '"tsiatis"' here corresponds to the Breslow
          estimator. This is ignored if survival estimates stored with
          'surv=TRUE' are being used. For fits from 'survfit', this
          argument is also ignored, since it is specified as an
          argument to 'survfit'. 

conf.type: specifies the basis for confidence limits. If estimates
          stored with 'surv=TRUE' are being used, always uses
          '"log-log"', the default. This argument is ignored for fits
          from 'survfit'. 

conf.int: Default is 'FALSE'.  Specify e.g. '.95' to plot 0.95
          confidence bands. For fits from parametric survival models,
          or Cox models with 'x=TRUE' and 'y=TRUE' specified to the
          fit, the exact asymptotic formulas will be used to compute
          standard errors, and confidence limits are based on 'log(-log
          S(t))'. If 'x=TRUE' and 'y=TRUE' were not specified to 'cph'
          but 'surv=TRUE' was, the standard errors stored for the
          underlying survival curve(s) will be used. These agree with
          the former if predictions are requested at the mean value of
          X beta or if there are only stratification factors in the
          model. This argument is ignored for fits from 'survfit',
          which must have previously specified confidence interval
          specifications. 

    conf: '"bars"' for confidence bars at each 'time.inc' time point.
          If the fit was from 'cph(..., surv=TRUE)', the 'time.inc'
          used will be that stored with the fit. Use 'conf="bands"' for
          bands using standard errors at each failure time. For
          'survfit' objects only, 'conf' may also be '"none"',
          indicating that confidence interval information stored with
          the 'survfit' result should be ignored. 

    what: defaults to '"survival"' to plot survival estimates.  Set to
          '"hazard"' or an abbreviation to plot the hazard function
          (for 'psm' fits only). Confidence intervals are not available
          for 'what="hazard"'. 

     add: set to 'TRUE' to add curves to an existing plot. 

label.curves: default is 'TRUE' to use 'labcurve' to label curves where
          they are farthest apart.  Set 'label.curves' to a 'list' to
          specify options to 'labcurve', e.g.,
          'label.curves=list(method="arrow", cex=.8)'. These option
          names may be abbreviated in the usual way arguments are
          abbreviated.  Use for example 'label.curves=list(keys=1:5)'
          to draw symbols (as in 'pch=1:5' - see 'points') on the
          curves and automatically position a legend in the most empty
          part of the plot.  Set 'label.curves=FALSE' to suppress
          drawing curve labels.  The 'col', 'lty', 'lwd', and 'type'
          parameters are automatically passed to 'labcurve', although
          you can override them here.  To distinguish curves by line
          types and still have 'labcurve' construct a legend, use for
          example 'label.curves=list(keys="lines")'.  The negative
          value for the plotting symbol will suppress a plotting symbol
          from being drawn either on the curves or in the legend. 

abbrev.label: set to 'TRUE' to 'abbreviate()' curve labels that are
          plotted 

     lty: vector of line types to use for different factor levels. 
          Default is 'c(1,3,4,5,6,7,...)'. 

     lwd: vector of line widths to use for different factor levels. 
          Default is current 'par' setting for 'lwd'. 

     col: color for curve, default is '1'.  Specify a vector to assign
          different colors to different curves. 

adj.subtitle: set to 'FALSE' to suppress plotting subtitle with levels
          of adjustment factors not plotted. Defaults to 'TRUE' if
          there are 4 or fewer adjustment factors. This argument is
          ignored for 'survfit'. 

  loglog: set to 'TRUE' to plot 'log(-log Survival)' instead of
          'Survival' 

     fun: specifies any function to translate estimates and confidence
          limits before plotting 

    logt: set to 'TRUE' to plot 'log(t)' instead of 't' on the x-axis 

  n.risk: set to 'TRUE' to add number of subjects at risk for each
          curve, using the 'surv.summary' created by 'cph' or using the
          failure times used in fitting the model if 'y=TRUE' was
          specified to the fit or if the fit was from 'survfit'. The
          numbers are placed at the bottom of the graph unless
          'y.n.risk' is given.  If the fit is from 'survest.psm',
          'n.risk' does not apply. 

srt.n.risk: angle of rotation for leftmost number of subjects at risk
          (since this number may run into the second or into the
          y-axis).  Default is '0'. 

adj.n.risk: justification for leftmost number at risk. Default is '1'
          for right  justification. Use '0' for left justification,
          '.5' for centered. 

sep.n.risk: multiple of upper y limit - lower y limit for separating
          lines of text containing number of subjects at risk.  Default
          is '.056*(ylim[2]-ylim[1])'. 

y.n.risk: When 'n.risk=TRUE', the default is to place numbers of
          patients at risk above the x-axis.  You can specify a
          y-coordinate for the bottom line of the numbers using
          'y.n.risk'. 

cex.n.risk: character size for number of subjects at risk (when
          'n.risk' is 'TRUE') 

    dots: set to 'TRUE' to plot a grid of dots.  Will be plotted at
          every 'time.inc' (see 'cph') and at survival increments of .1
          (if 'd>.4'), .05 (if '.2 < d <= .4'), or .025 (if 'd <= .2'),
          where 'd' is the range of survival displayed. 

 dotsize: size of dots in inches 

    grid: defaults to 'FALSE'. Set to a color shading to plot faint
          lines. Set to '1' to plot solid lines.  Default is '.05' if
          'TRUE'. 

      pr: set to 'TRUE' to print survival curve coordinates used in the
          plots 

_D_e_t_a_i_l_s:

     'survplot' will not work for Cox models with time-dependent
     covariables. Use 'survest' or 'survfit' for that purpose.

     Use 'ps.slide', 'win.slide', 'gs.slide' to set up nice defaults
     for plotting.  These also set a system option 'mgp.axis.labels' to
     allow x and y-axes to have differing 'mgp' graphical parameters
     (see 'par'). This is important when labels for y-axis tick marks
     are to be written horizontally ('par(las=1)'), as a larger gap
     between the labels and the tick marks are needed.  You can set the
     axis-specific 2nd component of 'mgp' using
     'mgp.axis.labels(c(xvalue,yvalue))'.

_V_a_l_u_e:

     list with components adjust (text string specifying adjustment
     levels) and 'curve.labels' (vector of text strings corresponding
     to levels of factor used to distinguish curves). For 'survfit',
     the returned value is the vector of strata labels, or NULL if
     there are no strata.

_S_i_d_e _E_f_f_e_c_t_s:

     plots. If 'par()$mar[4]<4', issues 'par(mar=)' to increment
     'mar[4]' by 2 if 'n.risk=TRUE' and 'add=FALSE'. The user may want
     to reset 'par(mar)' in this case to not leave such a wide right
     margin for plots. You usually would issue
     'par(mar=c(5,4,4,2)+.1)'.

_S_e_e _A_l_s_o:

     'datadist', 'Design', 'cph', 'psm', 'survest', 'predict.Design',
     'plot.Design',  'units', 'errbar',   'survfit',
     'survreg.distributions', 'labcurve', 'mgp.axis.labels', 'par',
     'ps.slide'

_E_x_a_m_p_l_e_s:

     # Simulate data from a population model in which the log hazard
     # function is linear in age and there is no age x sex interaction
     n <- 1000
     set.seed(731)
     age <- 50 + 12*rnorm(n)
     label(age) <- "Age"
     sex <- factor(sample(c('male','female'), n, TRUE))
     cens <- 15*runif(n)
     h <- .02*exp(.04*(age-50)+.8*(sex=='Female'))
     dt <- -log(runif(n))/h
     label(dt) <- 'Follow-up Time'
     e <- ifelse(dt <= cens,1,0)
     dt <- pmin(dt, cens)
     units(dt) <- "Year"
     dd <- datadist(age, sex)
     options(datadist='dd')
     S <- Surv(dt,e)

     #Plot stratified survival curves by sex, adj for quadratic age effect
     # with age x sex interaction (2 d.f. interaction)

     f <- cph(S ~ pol(age,2)*strat(sex), surv=TRUE)
     #or f <- psm(S ~ pol(age,2)*sex)

     survplot(f, sex=NA, n.risk=TRUE)           #Adjust age to median
     survplot(f, sex=NA, logt=TRUE, loglog=TRUE)   #Check for Weibull-ness (linearity)
     survplot(f, sex=c("male","female"), age=50)
                                             #Would have worked without datadist
                                             #or with an incomplete datadist
     survplot(f, sex=NA, label.curves=list(keys=c(2,0), point.inc=2))
                                             #Identify curves with symbols

     survplot(f, sex=NA, label.curves=list(keys=c('m','f')))
                                             #Identify curves with single letters

     #Plots by quintiles of age, adjusting sex to male
     options(digits=3)
     survplot(f, age=quantile(age,seq(0,1,by=.2)), sex="male")

     #Plot survival Kaplan-Meier survival estimates for males
     f <- survfit(S, subset=sex=="male")
     survplot(f)

     #Plot survival for both sexes
     f <- survfit(S ~ sex)
     survplot(f)
     #Check for log-normal and log-logistic fits
     survplot(f, fun=qnorm, ylab="Inverse Normal Transform")
     survplot(f, fun=function(y)log(y/(1-y)), ylab="Logit S(t)")

     options(datadist=NULL)

