SmoothHazard (version 2024.04.10)

idm: Fit an illness-death model

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

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
)

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.

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.

Author

R: Celia Touraine <[e-mail]> Fortran: Pierre Joly <[e-mail]>

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.

References

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

See Also

print.idm summary.idm predict.idm

Examples

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

# \donttest{
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")
# }
# 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

# \donttest{

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