idm: Fit an illness-death model In SmoothHazard: Estimation of Smooth Hazard Models for Interval-Censored Data with Applications to Survival and Illness-Death Models

Description

Fit an illness-death model using either a semi-parametric approach (penalized likelihood with an approximation of the transition intensity functions by linear combination of M-splines) or a parametric approach (specifying Weibull distributions on the transition intensities). Left-truncated, right-censored, and interval-censored data are allowed. State 0 corresponds to the initial state, state 1 to the transient one, state 2 to the absorbant one. The allowed transitions are: 0 –> 1, 0 –> 2 and 1 –> 2.

Usage

 ```1 2 3 4``` ```idm(formula01, formula02, formula12, data, maxiter = 200, eps = c(5, 5, 3), n.knots = c(7, 7, 7), knots = "equidistant", CV = FALSE, kappa = c(1000000, 500000, 20000), method = "Weib", conf.int = 0.95, print.iter = FALSE, subset = NULL, na.action = na.fail) ```

Arguments

 `formula01` A formula specifying a regression model for the `0 --> 1` transition from the initial state to the transient state of the illness-death model. The right hand side of the formula specifies the covariate terms, and the left hand side must be an event history object as returned by the function `Hist`. `formula02` A formula specifying a regression model for the `0 --> 2` transition from the initial state to the absorbing state. The left hand side must be equal to the left hand side of `formula01`. If missing it is set to `formula01`. `formula12` A formula specifying a regression model for the `1 --> 2` transition from the transient state to the absorbing state. operator is not required. If missing it is set to `formula01`. `data` A data frame in which to interpret the variables of `formula01`, `formula02` and `formula12`. `maxiter` Maximum number of iterations. The default is 200. `eps` A vector of 3 integers >0 used to define the power of three convergence criteria: 1. for the regression parameters, 2. for the likelihood, 3. for the second derivatives. The default is `c(5,5,3)` which is translated into convergence if the respective values change less then 10^{-5} (for regression parameters and likelihood) and 10^{-3} for the second derivatives between two iterations. `n.knots` For `method="Splines"` only, a vector of length 3 specifing the number of knots, one for each transition, for the M-splines estimate of the baseline intensities in the order ```0 --> 1```, `0 --> 2`, `1 --> 2`. The default is c(7,7,7). When `knots` are specified as a list this argument is ignored. The algorithm needs least 5 knots and at most 20 knots. `knots` Argument only active for the penalized likelihood approach `method="Splines"`. There are three ways to control the placement of the knots between the smallest and the largest of all time points: `knots="equidistant"`Knots are placed with same distance on the time scale. `knots="quantiles"`Knots are placed such that the number of observations is roughly the same between knots. knots=list()List of 1 or 2 or three vectors. The list elements are the actual placements (timepoints) of the knots for the M-spline. The list may contain one vector of placements for each transition in the order `0 --> 1`, `0 --> 2`, `1 --> 2`. If only vector is specifified the knots are used for all transitions. If only 2 vectors are specifified, the knots for the `0 --> 1` transition are also used for the `1 --> 2` transition. The algorithm needs at least 5 knots and allows no more than 20 knots. `CV` Binary variable equals to 1 when search (by approximated cross validation) of the smoothing parameters `kappa` and 0 otherwise. Argument for the penalized likelihood approach. The default is 0. `kappa` Argument only active for the penalized likelihood approach `method="Splines"`. A vector with 3 positive values (smoothing parameters), one for each transition, in the order 0 –> 1, 0 –> 2 and 1 –> 2.. If CV=1 these are used as starting values for a cross validation search to optimize kappa. `method` type of estimation method: "Splines" for a penalized likelihood approach with approximation of the transition intensities by M-splines, "Weib" for a parametric approach with a Weibull distribution on the transition intensities. Default is "Weib". `conf.int` Level of confidence pointwise confidence intervals of the transition intensities, i.e., a value between 0 and 1, the default is `0.95`. The default is also used when `conf.int=TRUE`. To avoid computation of confidence intervals, set `conf.int` to FALSE or NULL. `print.iter` boolean parameter. Equals to `TRUE` to print the likelihood during the iteration process, `FALSE` otherwise. Default is `FALSE`. This option is not running on Windows. `subset` expression indicating the subset of the rows of data to be used in the fit. All observations are included by default. `na.action` how NAs are treated. The default is first, any na.action attribute of data, second a na.action setting of options, and third 'na.fail' if that is unset. The 'factory-fresh' default is na.omit. Another possible value is NULL.

Details

The estimated parameters are obtained using the robust Marquardt algorithm (Marquardt, 1963) which is a combination between a Newton-Raphson algorithm and a steepest descent algorithm.

Value

 `call` the call that produced the result. `coef` regression parameters. `loglik` vector containing the log-likelihood without and with covariate. `cv` vector containing the convergence criteria. `niter` number of iterations. `converged` integer equal to 1 when the model converged, 2, 3 or 4 otherwise. `modelPar` Weibull parameters. `N` number of subjects. `events1` number of events 0 –> 1. `events2` number of events 0 –> 2 or 0 –> 1 –> 2. `NC` vector containing the number of covariates on transitions 0 –> 1, 0 –> 2, 1 –> 2. `responseTrans` model response for the 0 –> 1 transition. `Hist` or `Surv` object. `responseAbs` model response for the 0 –> 2 transition. `Hist` or `Surv` object. `time` times for which transition intensities have been evaluated for plotting. Vector in the Weibull approach. Matrix in the penalized likelihhod approach for which the colums corresponds to the transitions 0 –> 1, 1 –> 2, 0 –> 2. `intensity01` matched values of the intensities for transition 0 –> 1. `lowerIntensity01` lower confidence intervals for the values of the intensities for transition 0 –> 1. `upperIntensity01` upper confidence intervals for the values of the intensities for transition 0 –> 1. `intensity02` matched values of the intensities for transition 0 –> 2. `lowerIntensity02` lower confidence intervals for the values of the intensities for transition 0 –> 2. `upperIntensity02` upper confidence intervals for the values of the intensities for transition 0 –> 2. `intensity12` matched values of the intensities for transition 1 –> 2. `lowerIntensity12` lower confidence intervals for the values of the intensities for transition 1 –> 2. `upperIntensity12` upper confidence intervals for the values of the intensities for transition 1 –> 2. `RR` vector of relative risks. `V` variance-covariance matrix derived from the Hessian of the log-likelihood if using method="Weib" or, from the Hessian of the penalized log-likelihood if using method="Splines". `se` standart errors of the regression parameters. `Xnames01` names of covariates on 0 –> 1. `Xnames02` names of covariates on 0 –> 2. `Xnames12` names of covariates on 1 –> 2. `knots01` knots to approximate by M-splines the intensity of the 0 –> 1 transition. `knots02` knots to approximate by M-splines the intensity of the 0 –> 2 transition. `knots12` knots to approximate by M-splines the intensity of the 1 –> 2 transition. `nknots01` number of knots on transition 0 –> 1. `nknots02` number of knots on transition 0 –> 2. `nknots12` number of knots on transition 1 –> 2. `theta01` square root of splines coefficients for transition 0 –> 1. `theta02` square root of splines coefficients for transition 0 –> 2. `theta12` square root of splines coefficients for transition 1 –> 2. `CV` a binary variable equals to 1 when search of the smoothing parameters kappa by approximated cross-validation, 1 otherwise. The default is 0. `kappa` vector containing the smoothing parameters for transition 0 –> 1, 0 –> 2, 1 –> 2 used to estimate the model by the penalized likelihood approach. `CVcrit` cross validation criteria. `DoF` degrees of freedom of the model. `na.action` observations deleted if missing values.

Author(s)

R: Celia Touraine <Celia.Touraine@isped.u-bordeaux2.fr> Fortran: Pierre Joly <Pierre.Joly@isped.u-bordeaux2.fr>

References

D. Marquardt (1963). An algorithm for least-squares estimation of nonlinear parameters. SIAM Journal of Applied Mathematics, 431-441.

`print.idm` `summary.idm` `predict.idm`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49``` ```library(lava) library(prodlim) set.seed(17) d <- simulateIDM(100) # right censored data fitRC <- idm(formula01=Hist(time=observed.illtime,event=seen.ill)~X1+X2, formula02=Hist(time=observed.lifetime,event=seen.exit)~X1+X2, formula12=Hist(time=observed.lifetime,event=seen.exit)~X1+X2,data=d, conf.int=FALSE) fitRC ## Not run: set.seed(17) d <- simulateIDM(300) fitRC.splines <- idm(formula01=Hist(time=observed.illtime,event=seen.ill)~X1+X2, formula02=Hist(time=observed.lifetime,event=seen.exit)~X1+X2, formula12=Hist(time=observed.lifetime,event=seen.exit)~1,data=d, conf.int=FALSE,method="splines") ## End(Not run) # interval censored data fitIC <- idm(formula01=Hist(time=list(L,R),event=seen.ill)~X1+X2, formula02=Hist(time=observed.lifetime,event=seen.exit)~X1+X2, formula12=Hist(time=observed.lifetime,event=seen.exit)~X1+X2,data=d, conf.int=FALSE) fitIC ## Not run: data(Paq1000) # Illness-death model with certif on the 3 transitions # Weibull parametrization and likelihood maximization fit.weib <- idm(formula02=Hist(time=t,event=death,entry=e)~certif, formula01=Hist(time=list(l,r),event=dementia)~certif, data=Paq1000) # Illness-death model with certif on transitions 01 and 02 # Splines parametrization and penalized likelihood maximization fit.splines <- idm(formula02=Hist(time=t,event=death,entry=e)~certif, formula01=Hist(time=list(l,r),event=dementia)~certif, formula12=~1, method="Splines", data=Paq1000) fit.weib summary(fit.splines) ## End(Not run) ```