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.

### See Also

`lines`, `par`, `plot.survfit`, `survfit`, `survexp`.

### 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]