R: Predicting restricted mean time

predictRestrictedMeanTime {pec} | R Documentation

## Predicting restricted mean time

### Description

Function to extract predicted mean times from various modeling approaches.

### Usage

    ## S3 method for class 'aalen'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'riskRegression'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'cox.aalen'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'cph'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'coxph'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'matrix'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'selectCox'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'prodlim'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'psm'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'survfit'
    predictRestrictedMeanTime(object,newdata,times,...)
    ## S3 method for class 'pecRpart'
    predictRestrictedMeanTime(object,newdata,times,...)
    #' \method{predictRestrictedMeanTime}{pecCtree}(object,newdata,times,...)

### Arguments

`object` | A fitted model from which to extract predicted survival probabilities
`newdata` | A data frame containing predictor variable combinations for which to compute predicted survival probabilities.
`times` | A vector of times in the range of the response variable, e.g. times when the response is a survival object, at which to return the survival probabilities.
`...` | Additional arguments that are passed on to the current method.

### Details

The function predictRestrictedMeanTime is a generic function, meaning that it invokes a different function dependent on the 'class' of the first argument.

See also `predictSurvProb`.

### Value

A matrix with as many rows as `NROW(newdata)` and as many columns as `length(times)`. Each entry should be a probability and in rows the values should be decreasing.

### Note

In order to assess the predictive performance of a new survival model a specific `predictRestrictedMeanTime` S3 method has to be written. For examples, see the bodies of the existing methods.

The performance of the assessment procedure, in particular for resampling where the model is repeatedly evaluated, will be improved by supressing in the call to the model all the computations that are not needed for probability prediction. For example, `se.fit=FALSE` can be set in the call to `cph`.

### Author(s)

Thomas A. Gerds tag@biostat.ku.dk

### References

Ulla B. Mogensen, Hemant Ishwaran, Thomas A. Gerds (2012). Evaluating Random Forests for Survival Analysis Using Prediction Error Curves. Journal of Statistical Software, 50(11), 1-23. URL http://www.jstatsoft.org/v50/i11/.

### See Also

`predict`,`survfit`

### Examples

    # generate some survival data
    library(prodlim)
    set.seed(100)
    d <- SimSurv(100)
    # then fit a Cox model
    library(rms)
    coxmodel <- cph(Surv(time,status)~X1+X2,data=d,surv=TRUE)

    # predicted survival probabilities can be extracted
    # at selected time-points:
    ttt <- quantile(d$time)
    # for selected predictor values:
    ndat <- data.frame(X1=c(0.25,0.25,-0.05,0.05),X2=c(0,1,0,1))
    # as follows
    predictRestrictedMeanTime(coxmodel,newdata=ndat,times=ttt)

    # stratified cox model
    sfit <- coxph(Surv(time,status)~strata(X1)+X2,data=d,x=TRUE,y=TRUE)
    predictRestrictedMeanTime(sfit,newdata=d[1:3,],times=c(1,3,5,10))

    ## simulate some learning and some validation data
    learndat <- SimSurv(100)
    valdat <- SimSurv(100)
    ## use the learning data to fit a Cox model
    library(survival)
    fitCox <- coxph(Surv(time,status)~X1+X2,data=learndat,x=TRUE,y=TRUE)
    ## suppose we want to predict the survival probabilities for all patients
    ## in the validation data at the following time points:
    ## 0, 12, 24, 36, 48, 60
    psurv <- predictRestrictedMeanTime(fitCox,newdata=valdat,times=seq(0,60,12))
    ## This is a matrix with survival probabilities
    ## one column for each of the 5 time points
    ## one row for each validation set individual

    # the same can be done e.g. for a randomSurvivalForest model
    library(randomForestSRC)
    rsfmodel <- rfsrc(Surv(time,status)~X1+X2,data=d)
    predictRestrictedMeanTime(rsfmodel,newdata=ndat,times=ttt)

[Package pec version 2019.11.03 Index]