# 3-state Relative Survival Markov Model with Additive Risks The 3-state Markov relative survival model includes an initial state (X=1), a transient state (X=2), and the death (X=3). The possible transitions are: 1->2, 1->3 and 2->3. Assuming additive risks, the observed mortality hazard is the sum of two components: the expected population mortality (X=P) and the excess mortality related to the disease under study (X=E). The expected population mortality hazard (X=P) can be obtained from the death rates provided by life tables of statistical national institutes. These tables indicate the proportion of people dead in a calendar year stratified by birthdate and gender. ```r markov.3states.rsadd(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, p.age, p.sex, p.year, p.rate.table, 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. 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`. - `p.age`: A numeric vector with the patient ages in days at baseline (X=1). - `p.sex`: A character vector with the genders: `male` or `female`. - `p.year`: A numeric vector with the entry dates in the study respecting the date format, i.e. in number of days since 01.01.1960. - `p.rate.table`: A list containing the information related to the expected rates of mortality. This list is organized as a `ratetable` object. - `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: "markov.3states.rsadd (3-state time-inhomogeneous 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 (`Pr(>|t|)`). - **cov.matrix**: A data frame corresponding to variance-covariance matrix of the parameters. - **LogLik**: A numeric value corresponding to the log-likelihood of the estimated model. - **AIC**: A numeric value corresponding to the Akaike Information Criterion of the estimated model. ## References Huszti et al. Relative survival multistate Markov model. Stat Med. 10;31(3):269-86, 2012. Gillaizeau et al. A multistate additive relative survival semi-Markov model. Stat Methods Med Res. 26(4):1700-1711, 2017. . 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. . ## 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, 200, replace = FALSE),] # 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 # import the expected mortality rates data(fr.ratetable) # 3-state Markov model with additive risks including one explicative variable # (z is the delayed graft function) on all transitions. We only reduced # the precision and the number of iteration to save time in this example, # prefer the default values. markov.3states.rsadd(times1=d3$time1, times2=d3$time2, sequences=d3$trajectory, dist=c("E","E","E"), ini.dist.12=c(8.34), ini.dist.13=c(10.70), ini.dist.23=c(11.10), cov.12=d3$z, init.cov.12=c(0.04), names.12=c("beta12_z"), cov.13=d3$z, init.cov.13=c(1.04), names.13=c("beta1E_z"), cov.23=d3$z, init.cov.23=c(0.29), names.23=c("beta2E_z"), p.age=d3$ageR*365.24, p.sex=d3$sexR, p.year=date::as.date(paste("01","01",d3$year.tx), order = "mdy"), p.rate.table=fr.ratetable, conf.int=TRUE, silent=FALSE, precision=0.001) ```

markov.3states.rsadd function