Skip to contents

Compute deviance residuals

Source: R/computeDR.R
computeDR.Rd

This function computes deviance residuals from a null Cox model. By default it delegates to survival::coxph(), but a high-performance C++ engine is also available for large in-memory or bigmemory::big.matrix design matrices.

Usage

computeDR(
  time,
  time2,
  event,
  type,
  origin,
  typeres = "deviance",
  collapse,
  weighted,
  scaleY = TRUE,
  plot = FALSE,
  engine = c("survival", "cpp", "qcpp"),
  method = c("efron", "breslow"),
  X = NULL,
  coef = NULL,
  eta = NULL,
  center = NULL,
  scale = NULL
)

Arguments

time

for right censored data, this is the follow up time. For interval data, the first argument is the starting time for the interval.

time2

The status indicator, normally 0=alive, 1=dead. Other choices are TRUE/FALSE (TRUE = death) or 1/2 (2=death). For interval censored data, the status indicator is 0=right censored, 1=event at time, 2=left censored, 3=interval censored. Although unusual, the event indicator can be omitted, in which case all subjects are assumed to have an event.

event

ending time of the interval for interval censored or counting process data only. Intervals are assumed to be open on the left and closed on the right, (start, end]. For counting process data, event indicates whether an event occurred at the end of the interval.

type

character string specifying the type of censoring. Possible values are "right", "left", "counting", "interval", or "interval2". The default is "right" or "counting" depending on whether the time2 argument is absent or present, respectively.

origin

for counting process data, the hazard function origin. This option was intended to be used in conjunction with a model containing time dependent strata in order to align the subjects properly when they cross over from one strata to another, but it has rarely proven useful.

typeres

character string indicating the type of residual desired. Possible values are "martingale", "deviance", "score", "schoenfeld", "dfbeta", "dfbetas", and "scaledsch". Only enough of the string to determine a unique match is required.

collapse

vector indicating which rows to collapse (sum) over. In time-dependent models more than one row data can pertain to a single individual. If there were 4 individuals represented by 3, 1, 2 and 4 rows of data respectively, then collapse=c(1,1,1,2,3,3,4,4,4,4) could be used to obtain per subject rather than per observation residuals.

weighted

if TRUE and the model was fit with case weights, then the weighted residuals are returned.

scaleY

Should the time values be standardized ?

plot

Should the survival function be plotted ?

engine

Either "survival" (default) to call survival::coxph() or "cpp" to use the C++ implementation.

method

Tie handling to use with engine = "cpp": either "efron" (default) or "breslow".

X

Optional design matrix used to compute the linear predictor when engine = "cpp". Supports base matrices, data frames, and bigmemory::big.matrix objects.

coef

Optional coefficient vector associated with X when engine = "cpp".

eta

Optional precomputed linear predictor passed directly to the C++ engine.

center, scale

Optional centring and scaling vectors applied to X before computing the linear predictor with the C++ engine.

Value

Residuals from a null model fit. When engine = "cpp", the returned vector has attributes "martingale", "cumhaz", and "linear_predictor".

References

Bastien, P., Bertrand, F., Meyer, N., and Maumy-Bertrand, M. (2015). Deviance residuals-based sparse PLS and sparse kernel PLS for binary classification and survival analysis. BMC Bioinformatics, 16, 211.

Therneau, T.M., Grambsch, P.M. (2000). Modeling Survival Data: Extending the Cox Model. Springer.

See also

coxph

Author

Frédéric Bertrand
frederic.bertrand@lecnam.net
https://fbertran.github.io/homepage/

Examples


data(micro.censure, package = "bigPLScox")

Y_train_micro <- micro.censure$survyear[1:80]
C_train_micro <- micro.censure$DC[1:80]

Y_DR <- computeDR(Y_train_micro,C_train_micro)
Y_DR <- computeDR(Y_train_micro,C_train_micro,plot=TRUE)


Y_cpp <- computeDR(
  Y_train_micro,
  C_train_micro,
  engine = "cpp",
  eta = rep(0, length(Y_train_micro))
)

Y_qcpp <- computeDR(
  Y_train_micro,
  C_train_micro,
  engine = "qcpp"
)