CFC (version 1.2.0)

cfc: Cause-specific competing-risk survival analysis

Description

Using adaptive generalized Newton-Cotes for calculating cumulative incidence functions.

Usage

cfc(f.list, args.list, n, tout, Nmax = 100L, rel.tol = 1e-05, ncores = 1)

Value

An object of class cfc, which is a list with the following elements:

ci

Array of dimensions (length(tout), length(f.list), n), cumulative incidence functions for all causes and all values of the iterator, evaluated at all time points indicated by tout.

s

Array of same dimensions as ci, containing the (unadjusted) survival functions for all causes and all values of the iterator, evaluated at all time points indicated by tout.

is.maxiter

Binary Array of length n, where 1 indicates that subdivision process for quadrature problem applied to survival functions at iteration n reached maximum set by Nmax before converging, and 0 otherwise.

n.maxiter

Number of iterations that did not converge, i.e., sum(is.maxiter).

Arguments

f.list

In R mode, this is a list of survival functions, one per cause. Each survival function must have the prototype f(t, args, n), where t is a vector of time-from-index values, args is a list of all arguments needed by the function, and n is the iterator that allows the function to produce a different output for each observation and/or Bayesian sample. The output is a vector of survival probabilities at times t for that particular observation/sample combination with iterator value n. In C++ mode, this is a list of lists, one per cause. Each list must contain pointers to three C++ functions, in order: 1) survival function of type func with prototype defined as typedef arma::vec (*func)(arma::vec x, void* arg, int n) (using RcppArmadillo's vec class) and a similar interpetation as its R counterpart, 2) initializer function of type initfunc, with prototype defined as typedef void* (*initfunc)(List arg), where List is the Rcpp wrapper class for R lists, and 3) resource de-allocator function of type freefunc with this prototype: typedef void (*freefunc)(void *arg). See vignette for C++ example.

args.list

List of arguments (each one a list), one per cause, to be supplied to the survival functions in f.list.

n

Range of iterator (starting at 1) for survival functions. This can be the product of number of observations, and number of MCMC samplers in a Bayesian survival function.

tout

Vector of time points for which cumulative incidence functions are requested.

Nmax

Maximum number of subdivisions in the interval [0, max(tout)] to be created in the adaptive quadrature algorithm.

rel.tol

Threshold for relative integration error, used as stoppage criterion. It is calculated as the maximum relative error at time point max(tout) across all causes. Each relative error number is the difference between the Simpson-based and trapezoidal-based numbers, divided by the Simpson-based number.

ncores

Number of parallel threads to use. This is currrently only implemented in C++ mode.

Author

Mansour T.A. Sharabiani, Alireza S. Mahani

References

Haller, B., Schmidt, G., & Ulm, K. (2013). Applying competing risks regression models: an overview. Lifetime data analysis, 1-26.

Mahani A.S. and Sharabiani M.T.A. (2019). Bayesian, and Non-Bayesian, Cause-Specific Competing-Risk Analysis for Parametric and Nonparametric Survival Functions: The R Package CFC. Journal of Statistical Software, 89(9), 1-29. doi:10.18637/jss.v089.i09

Prentice et al (1978). The analysis of failure times in the presence of competing risks. Biometrics, 541-554.

See Also

cfc.survreg

Examples

if (FALSE) {

library("survival") # used for constructing survival formulas
library("BSGW") # used for Bayesian survival regression

data("bmt")
# splitting data into training and prediction sets
idx.train <- sample(1:nrow(bmt), size = 0.7 * nrow(bmt))
idx.pred <- setdiff(1:nrow(bmt), idx.train)
nobs.train <- length(idx.train)
nobs.pred <- length(idx.pred)

# prepare data and formula for Bayesian cause-specific survival regression
# using R package BSGW
out.prep <- cfc.prepdata(Surv(time, cause) ~ platelet + age + tcell, bmt)
f1 <- out.prep$formula.list[[1]]
f2 <- out.prep$formula.list[[2]]
dat <- out.prep$dat
tmax <- out.prep$tmax

# estimating cause-specific models
# set nsmp to larger number in real-world applications
nsmp <- 10
reg1 <- bsgw(f1, dat[idx.train, ], control = bsgw.control(iter = nsmp)
  , ordweib = T, print.level = 0)
reg2 <- bsgw(f2, dat[idx.train, ], control = bsgw.control(iter = nsmp)
  , ordweib = T, print.level = 0)

# defining survival function for this model
survfunc <- function(t, args, n) {
  nobs <- args$nobs; natt <- args$natt; nsmp <- args$nsmp
  alpha <- args$alpha; beta <- args$beta; X <- args$X
  idx.smp <- floor((n - 1) / nobs) + 1
  idx.obs <- n - (idx.smp - 1) * nobs
  return (exp(- t ^ alpha[idx.smp] * 
                exp(sum(X[idx.obs, ] * beta[idx.smp, ]))));
}

# preparing function and argument lists
X.pred <- as.matrix(cbind(1, bmt[idx.pred, c("platelet", "age", "tcell")]))
arg.1 <- list(nobs = nobs.pred, natt = 4, nsmp = nsmp
  , alpha = exp(reg1$smp$betas), beta = reg1$smp$beta, X = X.pred)
arg.2 <- list(nobs = nobs.pred, natt = 4, nsmp = nsmp
  , alpha = exp(reg2$smp$betas), beta = reg2$smp$beta, X = X.pred)
arg.list <- list(arg.1, arg.2)
f.list <- list(survfunc, survfunc)

# cause-specific competing-risk
# set rel.tol to smaller number in real-world applications
tout <- seq(from = 0.0, to = tmax, length.out = 10)
out.cfc <- cfc(f.list, arg.list, nobs.pred * nsmp, tout, rel.tol = 1e-2)

}