msmtools (version 1.0)

survplot: Plot and get survival data from a multi-state model.

Description

Plot a Kaplan-Meier curve and compare it with the fitted survival probability computed from a msm model. Fast build and return the associated datasets.

Usage

survplot(x, from = 1, to = NULL, range = NULL, covariates = "mean",
  exacttimes = TRUE, times, grid = 100L, km = FALSE, return.km = FALSE,
  return.p = FALSE, add = FALSE, ci = c("none", "normal", "bootstrap"),
  interp = c("start", "midpoint"), B = 100L, legend.pos = "topright",
  xlab = "Time", ylab = "Survival Probability", lty.fit = 1,
  lwd.fit = 1, col.fit = "red", lty.ci.fit = 3, lwd.ci.fit = 1,
  col.ci.fit = col.fit, mark.time = FALSE, lty.km = 5, lwd.km = 1,
  col.km = "darkblue", do.plot = TRUE, plot.width = 7, plot.height = 7,
  devnew = TRUE, verbose = TRUE)

Arguments

x

A msm object.

from

State from which to compute the estimated survival. Default to state 1.

to

The absorbing state to which compute the estimated survival. Default to the highest state found by absorbing.msm.

range

A numeric vector of two elements which gives the time range of the plot.

covariates

Covariate values for which to evaluate the expected probabilities. This can either be: the string "mean", denoting the means of the covariates in the data (this is the default), the number 0, indicating that all the covariates should be set t

exacttimes

If TRUE (default) then transition times are known and exact. This is inherited from msm and should be set the same way.

times

An optional numeric vector giving the times at which to compute the fitted survival.

grid

An integer which tells at how many points to compute the fitted survival. If times is passed, grid is ignored. It has a default of 100 points.

km

If TRUE, then the Kaplan-Meier curve is shown. Default is FALSE.

return.km

If TRUE, then a data.table is returned. Default is FALSE. survplot must be assigned to an object in order to get the data in the environment (see 'Value').

return.p

If TRUE, then a data.table is returned. Default is FALSE. survplot must be assigned to an object in order to get the data in the environment (see 'Value').

add

If TRUE, then a new layer is added to the current plot. Default is FALSE.

ci

If "none" (the default), then no confidence intervals are plotted. If "normal" or "bootstrap", confidence intervals are plotted based on the respective method in pmatrix.m

interp

If "start" (the default), then the entry time into the absorbing state is assumed to be the time it is first observed in the data. If "midpoint", then the entry time into the absorbing state is assumed to be halfway between the t

B

Number of bootstrap or normal replicates for the confidence interval. The default is 100 rather than the usual 1000, since these plots are for rough diagnostic purposes.

legend.pos

Where to position the legend. Default is "topright", but x and y coordinate can be passed. If NULL, then legend is not shown.

xlab

x axis label.

ylab

y axis label.

lty.fit

Line type for the fitted curve. See par.

lwd.fit

Line width for the fitted curve. See par.

col.fit

Line color for the fitted curve. See par.

lty.ci.fit

Line type for the fitted curve confidence limits. See par.

lwd.ci.fit

Line width for the fitted curve confidence limits. See par.

col.ci.fit

Line color for the fitted curve confidence limits. See par.

mark.time

Mark the empirical survival curve at each censoring point. See lines.survfit.

lty.km

Line type for the Kaplan-Meier passed to lines.survfit. See par.

lwd.km

Line width for the Kaplan-Meier passed to lines.survfit. See par.

col.km

Line color for the Kaplan-Meier passed to lines.survfit. See par.

do.plot

If FALSE, then no plot is shown at all. Default is TRUE.

plot.width

Width of new graphical device. Default is 7. See par.

plot.height

Height of new graphical device. Default is 7. See par.

devnew

Set the graphical device where to plot. By default, survplot plots on a new device by setting dev.new. If FALSE, then a plot is drawn onto the current device as specified by dev.cur. If FALSE

verbose

If FALSE, all information produced by print, cat and message are suppressed. All is done internally so that no global options are changed. verbose can be set to FALSE on all com

Value

• If both return.km and return.p are set to TRUE, then survplot returns a named list with $km and $fitted as data.table. To save them in the current environment assign survplot to an object (see 'Examples') ------ $km contains up to 4 columns: subject: the ordered subject ID as passed in the msm function. mintime: the time at which to compute the fitted survival. mintime_exact: if exacttimes is TRUE, then the relative timing is reported. anystate: state of transition to compute the Kaplan-Meier. ------ $fitted contains 2 columns: time: time at which to compute the fitted survival. probs: the corresponding value of the fitted survival.

Details

The function is a wrapper of plot.survfit.msm and does more things. survplot manages correctly the plot of a fitted survival in an exact times framework (when exacttimes = TRUE) by just resetting the time scale and looking at the follow-up time. It can fastly compute, build and return to the user the dataset on which the Kaplan-Meier has been computed. Similarly, it can return to the user the dataset on which the fitted survival has been computed, both with user defined times (through times) and self set times (through grid). For more details about how survplot returns objects, please refer to the vignette with vignette("msmtools").

References

Titman, A. and Sharples, L.D. (2010). Model diagnostics for multi-state models, Statistical Methods in Medical Research, 19, 621-651. Titman, A. and Sharples, L.D. (2008). A general goodness-of-fit test for Markov and hidden Markov models, Statistics in Medicine, 27, 2177-2195. Jackson, C.H. (2011). Multi-State Models for Panel Data: The msm Package for R. Journal of Statistical Software, 38(8), 1-29. URL http://www.jstatsoft.org/v38/i08/.

See Also

plot.survfit.msm, msm, pmatrix.msm

Examples

data( hosp )

# augmenting the data
hosp_augmented = augment( data = hosp, data_key = subj, n_events = adm_number, pattern = label_3,
                          t_start = dateIN, t_end = dateOUT, t_cens = dateCENS )

# let's define the initial transition matrix for our model
Qmat = matrix( data = 0, nrow = 3, ncol = 3, byrow = TRUE )
Qmat[ 1, 1:3 ] = 1
Qmat[ 2, 1:3 ] = 1
colnames( Qmat ) = c( 'IN', 'OUT', 'DEAD' )
rownames( Qmat ) = c( 'IN', 'OUT', 'DEAD' )

# attaching the msm package and running the model using
# gender and age as covariates
library( msm )
msm_model = msm( status_num ~ augmented_int,
                 subject = subj, data = hosp_augmented, covariates = ~ gender + age,
                 exacttimes = TRUE, gen.inits = TRUE, qmatrix = Qmat, method = 'BFGS',
                 control = list( fnscale = 6e+05, trace = 0,
                 REPORT = 1, maxit = 10000 ) )

# plotting the fitted and empirical survival
survplot( msm_model, km = TRUE, ci = 'none', verbose = FALSE, devnew = FALSE )

# returning fitted and empirical data
all_data = survplot( msm_model, ci = 'none',
                     return.km = TRUE, return.p = TRUE,
                     verbose = FALSE, do.plot = FALSE )