Package 'survCurve'

Title: Plots Survival Curves Element by Element
Description: Plots survival models from the 'survival' package. Additionally, it plots curves of multistate models from the 'mstate' package. Typically, a plot is drawn by the sequence survplot(), confIntArea(), survCurve() and nrAtRisk(). The separation of the plot in this 4 functions allows for great flexibility to make a custom plot for publication.
Authors: Melchior Burri [aut, cre]
Maintainer: Melchior Burri <[email protected]>
License: MIT + file LICENSE
Version: 1.0
Built: 2024-12-07 06:40:06 UTC
Source: CRAN

Help Index

Adds a confident interval area of a survival model to a plot.

Description

This function adds the confident interval area of one group (strata) of a survfit object to an existing plot. For competitive risk models, it draws the confidence interval of one group and one event; the event-number needs to be specified. If two overlapping confidence intervals are drawn (by two function calls) in one plot, the use of transparent color is recommended, for example "adjustcolor("red",0.1).

Usage

confIntArea(x, group, event, col = "grey", invert = FALSE)

Arguments

x

A survfit (survival-package) or a Cuminc (mstate-package) object.
group

Number of the group (=strata) of which the confidence interval should be plotted. If the survfit-object has only one strata, this parameter can be omitted.
event

If the model-object is a multistate-model, the number of the event-type needs to be specified.
col

Color of the confident interval area. Default is "grey". A transparent value is recommended, for example "adjustcolor("red",0.1).
invert

Inverts the area if TRUE, default is FALSE.

Value

Draws an area for the confidence interval.

Examples

require(survival)
  aml_model <- with(aml, survfit(Surv(time, status)~x))
  col1 <- adjustcolor("red",0.2); col2 <- adjustcolor("blue",0.2)
  survPlot(xmax=50, space.nrAtRisk=0.32)
  confIntArea(aml_model, col=col1, group=1)
  confIntArea(aml_model, col=col2, group=2)
  survCurve(aml_model, group=1)
  survCurve(aml_model, group=2, lty=2)
  nrAtRisk(aml_model, group=1, y=-0.17, bgcol.flag=col1, label="maintain")
  nrAtRisk(aml_model, group=2, y=-0.24, bgcol.flag=col2, lty.flag=2, label="non-maint.")

Extracts one group and one event of a survfit model as a data frame.

Description

This function is a helper function for the package and is not exported.

Usage

extractOneGroupOneEvent(model, group = NA, event = NA, firstRow = TRUE)

Arguments

model

A survfit object.
group

Number of the chosen group. If the model-object has only one Strata (Group), this parameter can be NA.
event

If the model-object is a multistate-model, the event-type needs to be specified, otherwise it can be NA.
firstRow

Typically, a survfit-model does not include data of time=0, if true this function tries to add a column time=0 as a first row.

Value

Returns a data frame with the times, estimate, upper and lower CI and the n.Risk of one group and one event of a Kaplan Meier estimator or a competitive risk analysis

Adds number at risk of a survival model to a plot.

Description

This function adds the number at risk of one group (strata) of a survfit object to an existing plot. If label is specified, it draws a label for the group right to the number at risks. If any elements of the "flag" is specified, it also draws a small identifier, with which the corresponding curves / confidence intervals of the plot can be identified near to the label.

Usage

nrAtRisk(
  x,
  group,
  ypos = 0.08,
  times,
  interval.times,
  zero.adjust = TRUE,
  zero.value,
  font.text = 1,
  cex.text = 1,
  col.text = "black",
  cex.nr,
  col.nr,
  font.nr,
  label,
  xpos.lab,
  cex.lab,
  col.lab,
  font.lab,
  lty.flag,
  lwd.flag,
  bgcol.flag,
  lncol.flag,
  xlim.flag
)

Arguments

x

A survfit (survival-package) or a Cuminc (mstate-package) object.
group

The number of the group (=strata) of which the confidence interval should be plotted. If the survfit-object has only one strata, this argument can be omitted.
ypos

A numeric value for the position at the y-axis.
times

An optional vector of numeric values specifying at which times (x-axis) the number at risk are calculated and plotted. If not specified, the defaults depends on "interval.times" value if available, or the size of the plot.
interval.times

An optional numeric value which specifies the interval at which the number at risk values are plotted. Is overwritten by times. If not specified, the value depends on the size of the plot.
zero.adjust

A logical value. If true, the number at risk at time 0 is not plotted at the precise position, but slightly adjusted to the left to prevent the value to be cut-off by the plot margins. Also, the value at x=0 is plotted if true. Default is TRUE.
zero.value

A numeric value or string that overwrites the nr at risk value at x=0 if specified (only if zero.adjust is TRUE).
font.text

Font of the text (nr at risk and label). Default is 1.
cex.text

Font-size of the text (nr at risk and label). Default is 1.
col.text

Colour of the text (nr at risk and label). Default is "black".
cex.nr

Overwrites cex.text for the number-part.
col.nr

Overwrites col.text for the number-part.
font.nr

Overwrites font.text for the number-part.
label

String for the group name.
xpos.lab

x-position of the label, default is near the right border of the plot.
cex.lab

Overwrites cex.text for the label-part.
col.lab

Overwrites col.text for the label-part.
font.lab

Overwrites font.text for the label-part.
lty.flag

Line-type of the flag. Value is 1 if not specified.
lwd.flag

Line-wide of the flag. Value is 1 if not specified.
bgcol.flag

Background-color of the flag (corresponding to the color of the confidence interval in the plot). No color if not value is specified.
lncol.flag

color of the line of the flag. Default is "black".
xlim.flag

Vector with two values, defining the beginning and end of the flag on the x-axis. Default depends on the size of the plot.

Value

Draws the number at risk to an existing plot.

Examples

require(survival)
  aml_model <- with(aml, survfit(Surv(time, status)~x))
  col1 <- adjustcolor("red",0.2); col2 <- adjustcolor("blue",0.2)
  survPlot(xmax=50, space.nrAtRisk=0.32)
  confIntArea(aml_model, col=col1, group=1)
  confIntArea(aml_model, col=col2, group=2)
  survCurve(aml_model, group=1)
  survCurve(aml_model, group=2, lty=2)
  nrAtRisk(aml_model, group=1, y=-0.17, bgcol.flag=col1, label="maintain")
  nrAtRisk(aml_model, group=2, y=-0.24, bgcol.flag=col2, lty.flag=2, label="non-maint.")

Draws a survival curve for one group and one event.

Description

This function draws the confident interval area of one group of a survfit object. For Competitive risk analysis, the event number needs to be specified.

Usage

survCurve(
  x,
  group,
  event,
  conf.int = FALSE,
  mark.time = FALSE,
  col = "black",
  lty = 1,
  lwd = 1,
  cex.markTime = 1,
  pch.markTime = 3,
  col.confInt = 1,
  lty.confInt = 2,
  lwd.confInt = 1,
  invert = FALSE
)

Arguments

x

A survfit or a Cuminc object.
group

Number of the chosen group. If the model-object has only one Strata (Group), this parameter can be omitted.
event

If the model-object is a multistate-model, the event-type needs to be specified.
conf.int

The confidence-interval is plotted as lines if TRUE. Default is FALSE
mark.time

The times of censoring are marked if TRUE. Default is FALSE
col

Color of the line. Default is "black".
lty

Line-type of the line. Default is 1.
lwd

Line-wide of the line. Default is 1.
cex.markTime

Size of the marks for censoring. Default is 1.
pch.markTime

Character of the marks for censoring. Default is 1 (stroke).
col.confInt

Color of the line for the confidence interval. Default is "black".
lty.confInt

Line-type of the line for the confidence interval. Default is 2.
lwd.confInt

Line-wide of the line for the confidence interval. Default is 1.
invert

Inverts the curve if TRUE. Default is FALSE.

Value

Draws the survival curve for one group / one event.

Examples

require(survival)
  aml_model <- with(aml, survfit(Surv(time, status)~x))
  col1 <- adjustcolor("red",0.2); col2 <- adjustcolor("blue",0.2)
  survPlot(xmax=50, space.nrAtRisk=0.32)
  confIntArea(aml_model, col=col1, group=1)
  confIntArea(aml_model, col=col2, group=2)
  survCurve(aml_model, group=1)
  survCurve(aml_model, group=2, lty=2)
  nrAtRisk(aml_model, group=1, y=-0.17, bgcol.flag=col1, label="maintain")
  nrAtRisk(aml_model, group=2, y=-0.24, bgcol.flag=col2, lty.flag=2, label="non-maint.")

Adds number at risk of a survival model to a plot. Adds label to plot.

Description

This function adds a text label to the plot, which is preceded by a small identifier, similar to the function nrAtRisk.

Usage

survLable(
  text,
  x,
  y,
  font = 1,
  cex = 1,
  col.text = "black",
  len.flag,
  lty.flag = 1,
  lwd.flag = 1,
  bgcol.flag,
  lncol.flag = "black"
)

Arguments

text

String, content of the label.
x

A numeric value for the position at the x-axis.
y

A numeric value for the position at the y-axis.
font

Font of the label.
cex

Font size of the label
col.text

Color of the label.
len.flag

Length of the flag.
lty.flag

Line-typ of the flag. Value is 1 if not spezified.
lwd.flag

Line-wide of the flag. Value is 1 if not spezified.
bgcol.flag

Background-color of the flag (corresponding to the color of the confidence interval in the plot). No color if not value is specified.
lncol.flag

Color of the line of the flag. Default is "black".

Value

Draws the number at risk to an existing plot.

Examples

require(survival)
  aml_model <- with(aml, survfit(Surv(time, status)~x))
  col1 <- adjustcolor("red",0.2); col2 <- adjustcolor("blue",0.2)
  survPlot(xmax=50)
  confIntArea(aml_model, col=col1, group=1)
  confIntArea(aml_model, col=col2, group=2)
  survCurve(aml_model, group=1)
  survCurve(aml_model, group=2, lty=2)
  survLable("maintain", 1, 0.2, bgcol.flag=col1)
  survLable("non-maint.", 1, 0.1, bgcol.flag=col2, lty.flag=2)

Setup for a plot for survival data without the curves.

Description

This function draws the confident interval area of one group of a survfit object. For Competitive risk analysis, the event number needs to be specified. To get a nice graph, the function should be runned after one made an empty plot, and before drawing the actual curves (Thus the area is underlining to the curves). If two curves are drawn which confident intervals overlap transparency should be added to the colors.

Usage

survPlot(
  main = "",
  title.xaxis = "",
  title.yaxis = "",
  xmin = 0,
  xmax,
  ymin = -0.02,
  ymax = 1.02,
  ypercent = TRUE,
  title.nrAtRisk = "number at risk",
  space.nrAtRisk = 0,
  interval.xaxis,
  interval.yaxis,
  las.xaxis = 1,
  las.yaxis = 1,
  font.xaxis = 1,
  font.yaxis = 1,
  cex.xaxis = 1,
  cex.yaxis = 1,
  points.xaxis,
  points.yaxis,
  labels.xaxis,
  labels.yaxis,
  font.nrAtRiskTitle = 1,
  cex.nrAtRiskTitle = 1
)

Arguments

main

Title of the plot, Default is "".
title.xaxis

Title of the x-axis. Default is "".
title.yaxis

Title of the y-axis. Default is "".
xmin

Minimum for the x (Time) - axis. Default is 0.
xmax

Maximum of the x (time) axis. No default, must be specified.
ymin

Minimum of the y-axis. Default is -0.02
ymax

Maximum of the y-axis. Default is 1.02
ypercent

Specifies if the Unit of the y-axis is ratio (usually 0-1) or percentage (0-100), Default is TRUE (0-100). Equals yscale=100.
title.nrAtRisk

Label for the number at risk region. Default is "number at risk", other meaningful value is "patients at risk", or translations in any language for example. Not plotted if space.nrAtRisk is 0
space.nrAtRisk

Space (usually around 0.2-0.5) below the plot to draw the values of number at risk. Default is 0.
interval.xaxis

Interval at which the ticks of the x-axis are drawn. Default depends on the size of the plot.
interval.yaxis

Interval at which the ticks of the y-axis are drawn. Default depends on the size of the plot.
las.xaxis

Orientation of the labels of the x-axis. Default is 1 (horizontal).
las.yaxis

Orientation of the labels of the y-axis. Default is 1 (horizontal).
font.xaxis

Font-type for the labels of the x-axis. Default is 1.
font.yaxis

Font-type for the labels of the y-axis. Default is 1.
cex.xaxis

Font-size for the labels of the x-axis. Default is 1.
cex.yaxis

Font-size for the labels of the y-axis. Default is 1.
points.xaxis

Exact position of the ticks of the x-axis. Overwrites the values of interval.xaxis. Usually not required.
points.yaxis

Exact position of the ticks of the y-axis. Overwrites the values of interval.yaxis. Usually not required.
labels.xaxis

Label for the ticks of the x-axis. Only valid if points are specified. Must be same length like points.
labels.yaxis

Label for the ticks of the y-axis. Only valid if points are specified. Must be same length like points.
font.nrAtRiskTitle

Font type of the title of the nr-at-Risk Space Default is 1.
cex.nrAtRiskTitle

Font size of the title of the nr-at-Risk Space Default is 1.

Value

Draws an empty plot optimized for survival-curves.

Examples

require(survival)
  aml_model <- with(aml, survfit(Surv(time, status)~x))
  col1 <- adjustcolor("red",0.2); col2 <- adjustcolor("blue",0.2)
  survPlot(xmax=50, space.nrAtRisk=0.32)
  confIntArea(aml_model, col=col1, group=1)
  confIntArea(aml_model, col=col2, group=2)
  survCurve(aml_model, group=1)
  survCurve(aml_model, group=2, lty=2)
  nrAtRisk(aml_model, group=1, y=-0.17, bgcol.flag=col1, label="maintain")
  nrAtRisk(aml_model, group=2, y=-0.24, bgcol.flag=col2, lty.flag=2, label="non-maint.")