coxdual: Cox model for a Markov illness-death process under dual...
In coxinterval: Cox-Type Models for Interval-Censored Data

Description Usage Arguments Details Value References See Also Examples

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

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

`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`.

A valid formula argument can be expressed as

1 2	Surv(<start>, <stop>, <status>) ~ cluster(<id>) + trans(<from>, <to>) + <covariate terms>

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

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 <start> = NA, <from> = NA, <to> equal to the index of the terminal state, and any transition-type–specific covariates taking on the values assumed when <from> 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 <start> is the initial observation time (zero, unless left-truncated), <stop> = NA and <from> 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.

An object of the classes "coxinterval" and "coxdual", which is a list with the following components.

`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.

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

cluster, dualic, dualrc, Surv, trans

# 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)))