# 3-State Semi-Markov Model The 3-state SM model includes an initial state (X=1), a transient state (X=2) and an absorbing state (X=3). Usually, X=1 corresponds to disease-free or remission, X=2 to relapse, and X=3 to death. In this illness-death model, the possible transitions are: 1->2, 1->3 and 2->3. ```r semi.markov.3states(times1, times2, sequences, weights=NULL, dist, cuts.12=NULL, cuts.13=NULL, cuts.23=NULL, ini.dist.12=NULL, ini.dist.13=NULL, ini.dist.23=NULL, cov.12=NULL, init.cov.12=NULL, names.12=NULL, cov.13=NULL, init.cov.13=NULL, names.13=NULL, cov.23=NULL, init.cov.23=NULL, names.23=NULL, conf.int=TRUE, silent=TRUE, precision=10^(-6)) ``` ## Arguments - `times1`: A numeric vector with the observed times in days from baseline to the first transition (X=2 or X=3) or to the right-censoring (in X=1 at the last follow-up). - `times2`: A numeric vector with the observed times in days from baseline to the second transition or to the right censoring (in X=2 at the last follow-up). `NA` for individuals right-censored in X=1 or individuals who directly transited from X=1 to X=3. - `sequences`: A numeric vector with the sequences of observed states. Four possible values are allowed: 1 (individual right-censored in X=1), 12 (individual right-censored in X=2), 13 (individual who directly transited from X=1 to X=3), 123 (individual who transited from X=1 to X=3 through X=2). - `weights`: A numeric vector with the weights for correcting the contribution of each individual. When the vector is completed, the IPW estimator is implemented. Default is `NULL` which means that no weighting is applied. - `dist`: A character vector with three arguments describing respectively the distributions of duration time for transitions 1->2, 1->3 and 2->3. Arguments allowed are `"E"` for Exponential distribution, `"PE"` for the piecewise exponential distribution, `"W"` for Weibull distribution or `"WG"` for Generalized Weibull distribution. When the user choose `"PE"`, the arguments `"cut.XX"` have also to be defined. - `cuts.12`: A numeric vector indicating the timepoints in days for the piecewise exponential distribution related to the time from X=1 to X=2. Only internal timepoints are allowed: timepoints cannot be `0` or `Inf`. Default is `NULL` which means that the distribution is not piecewise. Piecewise model is only allowed for exponential distribution. - `cuts.13`: A numeric vector indicating the timepoints in days for the piecewise exponential distribution related to the time from X=1 to X=3. Only internal timepoints are allowed: timepoints cannot be `0` or `Inf`. Default is `NULL` which means that the distribution is not piecewise. Piecewise model is only allowed for exponential distribution. - `cuts.23`: A numeric vector indicating the timepoints in days for the piecewise exponential distribution related to the time from X=2 to X=3. Only internal timepoints are allowed: timepoints cannot be `0` or `Inf`. Default is `NULL` which means that the distribution is not piecewise. Piecewise model is only allowed for exponential distribution. - `ini.dist.12`: A numeric vector of initial values for the distribution from X=1 to X=2. The logarithm of the parameters have to be declared. Default value is 1. - `ini.dist.13`: A numeric vector of initial values for the distribution from X=1 to X=3. The logarithm of the parameters have to be declared. Default value is 1. - `ini.dist.23`: A numeric vector of initial values for the distribution from X=2 to X=3. The logarithm of the parameters have to be declared. Default value is 1. - `cov.12`: A matrix (or data frame) with the explicative time-fixed variable(s) related to the time from X=1 to X=2. - `init.cov.12`: A numeric vector of initial values for regression coefficients (logarithm of the cause-specific hazards ratios) associated to `cov.12`. Default initial value is 0. - `names.12`: An optional character vector with name of explicative variables associated to `cov.12`. - `cov.13`: A numeric matrix (or data frame) with the explicative time-fixed variable(s) related to the time from X=1 to X=3. - `init.cov.13`: A numeric vector of initial values for regression coefficients (logarithm of the cause-specific hazards ratios) associated to `cov.13`. Default initial value is 0. - `names.13`: An optional character vector with name of explicative variables associated to `cov.13`. - `cov.23`: A numeric matrix (or data frame) with the explicative time-fixed variable(s) related to the time from X=2 to X=3. - `init.cov.23`: A numeric vector of initial values for regression coefficients (logarithm of the cause-specific hazards ratios) associated to `cov.23`. Default initial value is 0. - `names.23`: An optional character vector with name of explicative variables associated to `cov.23`. - `conf.int`: A logical value specifying if the pointwise confidence intervals for parameters and the variance-covariance matrix should be returned. Default is `TRUE`. - `silent`: A logical value specifying if the log-likelihood value should be returned at each iteration. Default is `TRUE`, which corresponds to silent mode (no display). - `precision`: A numeric positive value indicating the required precision for the log-likelihood maximization between each iteration. Default is $10^{-6}$. ## Details Hazard functions available are: ||| |--:|:--| |Exponential distribution|$\lambda(t)=1/\sigma$| |Weibull distribution|$\lambda(t)=\nu(\frac{1}{\sigma})^{\nu}t^{\nu-1}$| |Generalized Weibull distribution|$\lambda(t)=\frac{1}{\theta}\left(1+\left(\frac{t}{\sigma}\right)^{\nu}\right)^{\frac{1}{\theta}-1} \nu\left(\frac{1}{\sigma}\right)^{\nu} t^{\nu-1}$| with $\sigma$, $\nu$,and $\theta>0$. The parameter $\sigma$ varies for each interval when the distribution is piecewise Exponential. We advise to initialize the logarithm of these parameters in `ini.dist.12`, `ini.dist.13` and `ini.dist.23`. To estimate the marginal effect of a binary exposure, the `weights` may be equal to `1/p`, where `p` is the estimated probability that the individual belongs to his or her own observed group of exposure. The probabilities `p` are often estimated by a logistic regression in which the dependent binary variable is the exposure. The possible confounding factors are the explanatory variables of this logistic model. ## Returns - **object**: The character string indicating the estimated model: "semi.markov.3states (3-state semi-markov model)". - **dist**: A character vector with two arguments describing respectively the distributions of duration time for transitions 1->2, 1->3 and 2->3. - **cuts.12**: A numeric vector indicating the timepoints in days for the piecewise exponential distribution related to the time from X=1 to X=2. - **cuts.13**: A numeric vector indicating the timepoints in days for the piecewise exponential distribution related to the time from X=1 to X=3. - **cuts.23**: A numeric vector indicating the timepoints in days for the piecewise exponential distribution related to the time from X=2 to X=3. - **covariates**: A numeric vector indicating the numbers of covariates respectively related to the transition 1->2, 1->3 and 2->3. - **table**: A data frame containing the estimated parameters of the model (`Estimate`). When the option `conf.int=TRUE` is specified, this data frame includes three additional columns: the Standard Errors of parameters (`Std.Error`), the value of the Wald statistic (`t.value`), and the related p-value for the Wald test (`Pr(>|t|)`). - **cov.matrix**: A data frame corresponding to variance-covariance matrix of the parameters. - **LogLik**: A numeric value corresponding to the (weighted) log-likelihood of the model. - **AIC**: A numeric value corresponding to the Akaike Information Criterion of the model. ## References Gillaizeau et al. Inverse Probability Weighting to control confounding in an illness-death model for interval-censored data. Stat Med. 37(8):1245-1258, 2018. . Gillaizeau et al. A multistate additive relative survival semi-Markov model. Statistical methods in medical research. 26(4):1700-1711, 2017. . ## Author(s) Yohann Foucher Florence Gillaizeau ## Examples ```r # import the observed data # (X=1 corresponds to initial state with a functioning graft, X=2 to acute rejection episode, # X=3 to return to dialysis, X=4 to death with a functioning graft) data(dataDIVAT1) # A subgroup analysis to reduce the time needed for this example dataDIVAT1$id<-c(1:nrow(dataDIVAT1)) set.seed(2) d3<-dataDIVAT1[dataDIVAT1$id %in% sample(dataDIVAT1$id, 250, replace = FALSE),] # To illustrate the use of a 3-state model, individuals with trajectory 13 and 123 are # censored at the time of transition into state X=3 d3$trajectory[d3$trajectory==13]<-1 d3$trajectory[d3$trajectory==123]<-12 d3$trajectory[d3$trajectory==14]<-13 d3$trajectory[d3$trajectory==124]<-123 # 3-state parametric semi-Markov model including one explicative variable # on the transition 1->2 (z is 1 if delayed graft function and 0 otherwise). # We only reduced the precision and the number of iteration to save time in this example, # prefer the default values. semi.markov.3states(times1=d3$time1, times2=d3$time2, sequences=d3$trajectory, dist=c("E","E","E"), ini.dist.12=c(9.93), ini.dist.13=c(11.54), ini.dist.23=c(10.21), cov.12=d3$z, init.cov.12=c(-0.13), names.12=c("beta12_z"), conf.int=TRUE, silent=FALSE, precision=0.001)$table ```

semi.markov.3states function