R: Add Lines or Points to a Survival Plot

lines.survfit {survival}

R Documentation

Add Lines or Points to a Survival Plot

Description

Often used to add the expected survival curve(s) to a Kaplan-Meier plot generated with plot.survfit.

Usage

## S3 method for class 'survfit'
lines(x, type="s", mark=3, col=1, lty=1,
        lwd=1, cex=1, mark.time=FALSE, 
	xscale=1,  firstx=0, firsty=1, xmax, fun, conf.int=FALSE,
        conf.times, conf.cap=.005, conf.offset=.012,  ...)
## S3 method for class 'survexp'
lines(x, type="l", ...)
## S3 method for class 'survfit'
points(x, xscale, xmax, fun, censor=FALSE, col=1, pch,
...)

Arguments

`x`	a survival object, generated from the `survfit` or `survexp` functions.
`type`	the line type, as described in `lines`. The default is a step function for `survfit` objects, and a connected line for `survexp` objects. All other arguments for `lines.survexp` are identical to those for `lines.survfit`.
`mark, col, lty, lwd, cex`	vectors giving the mark symbol, color, line type, line width and character size for the added curves. Of this set only color is applicable to `points`.
`pch`	plotting characters for points, in the style of `matplot`, i.e., either a single string of characters of which the first will be used for the first curve, etc; or a vector of characters or integers, one element per curve.
`censor`	should censoring times be displayed for the `points` function?
`...`	other graphical parameters
`mark.time`	controls the labeling of the curves. If `FALSE`, no labeling is done. If `TRUE`, then curves are marked at each censoring time. If `mark.time` is a numeric vector, then curves are marked at the specified time points.
`xscale`	this parameter is no longer necessary and is ignored. See the note in `plot.survfit`.
`firstx, firsty`	the starting point for the survival curves. If either of these is set to `NA` or < blank > the plot will start at the first time point of the curve.
`xmax`	the maximum horizontal plot coordinate. This shortens the curve before plotting it, so unlike using the `xlim` graphical parameter, warning messages about out of bounds points are not generated.
`fun`	an arbitrary function defining a transformation of the survival curve. For example `fun=log` is an alternative way to draw a log-survival curve (but with the axis labeled with log(S) values). Four often used transformations can be specified with a character argument instead: "log" is the same as using the `log=T` option, "event" plots cumulative events (f(y) = 1-y), "cumhaz" plots the cumulative hazard function (f(y) = -log(y)) and "cloglog" creates a complimentary log-log survival plot (f(y) = log(-log(y))) along with log scale for the x-axis.
`conf.int`	if `TRUE`, confidence bands for the curves are also plotted. If set to `"only"`, then only the CI bands are plotted, and the curve itself is left off. This can be useful for fine control over the colors or line types of a plot.
`conf.times`	optional vector of times at which to place a confidence bar on the curve(s). If present, these will be used instead of confidence bands.
`conf.cap`	width of the horizontal cap on top of the confidence bars; only used if conf.times is used. A value of 1 is the width of the plot region.
`conf.offset`	the offset for confidence bars, when there are multiple curves on the plot. A value of 1 is the width of the plot region. If this is a single number then each curve's bars are offset by this amount from the prior curve's bars, if it is a vector the values are used directly.

Details

When the survfit function creates a multi-state survival curve the resulting object has class ‘survfitms’. The only difference in the plots is that that it defaults to a curve that goes from lower left to upper right (starting at 0), where survival curves default to starting at 1 and going down. All other options are identical.

Value

a list with components x and y, containing the coordinates of the last point on each of the curves (but not of the confidence limits). This may be useful for labeling.

Side Effects

one or more curves are added to the current plot.

Examples

fit <- survfit(Surv(time, status==2) ~ sex, pbc,subset=1:312)
plot(fit, mark.time=FALSE, xscale=365.25,
        xlab='Years', ylab='Survival')
lines(fit[1], lwd=2)    #darken the first curve and add marks


# Add expected survival curves for the two groups,
#   based on the US census data
# The data set does not have entry date, use the midpoint of the study
efit <- survexp(~ ratetable(sex=sex,age=age*365.35,year=as.Date('1979/1/1')) +
            sex, data=pbc,  times=(0:24)*182)
temp <- lines(efit, lty=2, lwd=2:1)
text(temp, c("Male", "Female"), adj= -.1) #labels just past the ends
title(main="Primary Biliary Cirrhosis, Observed and Expected")

[Package survival version 2.41-3 Index]