coxdual: Cox model for a Markov illness-death process under dual censoring

Description

Fit a Cox model to a progressive Markov illness-death process observed under right-censored survival times and interval- or right-censored progression times.

Usage

coxdual(formula, data = parent.frame(), subset, init = NULL, formula.coxph = NULL, init.coxph = FALSE, control, ...)

Arguments

formula

an expression of the form response ~ terms, where response is anobject returned by the Surv function and terms contain clustering and state-transition variables identified by the cluster and trans functions, respectively.

data

an optional data frame in which to interpret the variables named in the arguments formula and formula.coxph.

subset

expression specifying which rows of data should be used in the fit. All observations are included by default.

init

a named list of the vector coef, specifying the initial coefficient values, and matrix or data frame basehaz, used to the initialize the cumulative baseline transition intensities. The basehaz element should contain columns representing the cumulative transition intensity, time and transition type. If the columns do not appear in this order, they should be indicated by the column names "hazard", "time" and "trans", respectively. The sorted values used to represent the transition types should respectively denote the initial to intermediate, initial to terminal, and intermediate to terminal state transitions. The NULL value for init or its components enables default values. For coef the default is zero. For basehaz the default corresponds to linear functions of time with an upper bound of one. Under any alternatives arising from this or the init.coxph arguments, basehaz is interpreted as a step function of time and the initial value is its piecewise linear approximation.

formula.coxph

an optional formula specifying a model to fit with coxph using singly right-censored observations. The shorthand ~ . indicates the same terms given in formula, with the function strata in place by trans. Under dual right censoring and init.coxph = TRUE, formula.coxph defaults to same model in formula, which is fit to observations singly-right--censored at the earlier censoring time. Multiple formula objects can be provided as a list.

init.coxph

a logical value indicating that init should be overrided by estimates based on the coxph fit to the (first) model specified in formula.coxph.

control

a named list of parameters controlling the model fit, returned by the function coxdual.control. This defaults to coxdual.control().

...

additional arguments to be passed to coxdual.control.

Value

call: the matched call to coxdual.
censor: a string indicating the dual censoring type. The value "right" corresponds to strictly dual-right--censored data. All other cases return "interval".
n: size of the sample used in the model fit.
m: number of at-risk intervals used in the model fit.
p: number of regression coefficients.
coef: a named p vector of regression coefficients.
var: a named p by p covariance matrix of the regression coefficients.
basehaz: a data frame giving the cumulative baseline transition intensities evaluated over the sieve partition.
init: list of initial values used in the model fit.
loglik: a vector giving the log-likelihood at initiation and each iteration.
iter: number of iterations needed to reach the stopping criteria.
gradnorm: the maximum norm of the score scaled by the parameter value at the final iteration.
maxnorm: the maximum norm of the difference between the penultimate and final parameter values.
cputime: the processing time used for parameter and variance estimation.
fit.coxph: the coxph fit to any models specified by the formula.coxph argument. If formula.coxph is a list of formula objects, fit.coxph is an unnamed list following the same order.
na.action: the "na.action" attribute of the model frame. Here this corresponds to the result from the custom NA action na.coxdual.
censor.rate: a named vector of censoring rates.
control: a list of arguments passed to coxdual.control.
data: a list containing the data relevant to the model fit, if the coxdual.control argument data is true.

Details

A valid formula argument can be expressed as

Surv(, , )
    ~ cluster() + trans(, ) +

where (, ] is largest known time interval over which individual is at risk for a transition between the states and . The variable indicates whether or not a transition is observed to occur at .

Under dual censoring (Boruvka and Cook, 2014), both the originating state and the left endpoint of an at-risk interval may be unknown. This case is handled with = NA, = NA, equal to the index of the terminal state, and any transition-type--specific covariates taking on the values assumed when is equal to the intermediate state index. Under discrete observation of non-terminal events, the right-endpoint of some at-risk intervals may be unknown. For these is the initial observation time (zero, unless left-truncated), = NA and is equal to the initial state index. Missing values are retained by the NA action na.coxdual. The default NA action is used to handle any missing values passed to coxph via the arguments formula.coxph or init.coxph.

Dual censoring typically arises in two scenarios: (1) dual right-censoring, where intermediate events are right-censored before terminal events, and (2) interval-censored intermediate events. For examples of these refer to dualrc and dualic, respectively.

A consequence of dual censoring is that any discrete maximum likelihood estimator has ambiguous support at any failure times associated with these NA values. To resolve this, the cumulative baseline transition intensities are restricted to piecewise linear functions on a sieve partition with size controlled by arguments passed to coxdual.control. This approach requires that both types of transitions to the terminal state are, at least for some subjects, observed exactly.

References

Boruvka, A. and Cook, R. J. (2014) Sieve estimation in a Markov illness-death process under dual censoring.

Examples

Run this code

# Fit Cox model to dual-right--censored data
fit <- coxdual(Surv(start, stop, status) ~ cluster(id) + trans(from, to)
               + I(z * (to == 1)) + I(z * (from %in% 0 & to == 2))
               + I(z * (from %in% c(NA, 1) & to == 2)), data = dualrc,
               sieve.rate = 2/5)
fit
par(mfrow = c(1, 3))
by(fit$basehaz, fit$basehaz$trans, function(x) plot(x[, 2:1],
   type = "l", main = paste(x[1, 3]), xlim = c(0, 2), ylim = c(0, 4)))

# Fit Cox model to data with interval-censored progression times
fit <- coxdual(Surv(start, stop, status) ~ cluster(id) + trans(from, to)
               + I(z * (to == 1)) + I(z * (from %in% 0 & to == 2))
               + I(z * (from %in% c(NA, 1) & to == 2)), data = dualic)
fit
par(mfrow=c(1, 3))
by(fit$basehaz, fit$basehaz$trans, function(x) plot(x[, 2:1],
   type = "l", main = paste(x[1, 3]), xlim = c(0, 2), ylim = c(0, 4)))

Run the code above in your browser using DataLab