mm2: Horizontal Mixture Model for Two Competing Events
In multistate: Fitting Multistate Models

Description Usage Arguments Details Value Author(s) References Examples

The 2-state mixture model which includes an initial state (X=1) and two absorbing states in competition (X=2 and X=3). Parameters are estimated by (weighted) Likelihood maximization.

mm2(t, sequence, weights=NULL, dist, cuts.12=NULL, cuts.13=NULL,
 ini.dist.12=NULL, ini.dist.13=NULL, cov.12=NULL, init.cov.12=NULL,
 names.12=NULL, cov.13=NULL, init.cov.13=NULL, names.13=NULL,
 cov.p=NULL, init.cov.p=NULL, names.p=NULL, init.intercept.p=NULL,
 conf.int=TRUE, silent=TRUE, precision=10^(-6))

`t`	A numeric vector with the observed times in days from baseline to the last observation.
`sequence`	A numeric vector with the sequence of observed states. Three possible values are allowed: 1 (the individual is right-censored in X=1), 12 (the individual transits to X=2) and 13 (the individual transits to X=3).
`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 two arguments describing respectively the distributions of duration time for transitions 1->2 and 1->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.
`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.
`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.p`	A matrix (or data frame) with the explicative time-fixed variable(s) related to the probability P(X=2), which is regressing according to a logistic function.
`init.cov.p`	A numeric vector of initial values for regression coefficients (logarithm of the cause-specific hazards ratios) associated to `cov.p`. Default initial value is 0.
`names.p`	An optional character vector with name of explicative variables associated to `cov.p`.
`init.intercept.p`	A numeric value to iniate the intercept of the logit of P(X=2). Default value is 0.
`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}.

Hazard functions available are:

`Exponential` distribution	λ(t)=1/σ
`Weibull` distribution	λ(t)=ν(\frac{1}{σ})^{ν}t^{ν-1}
`Generalized Weibull` distribution	λ(t)=\frac{1}{θ}≤ft(1+≤ft(\frac{t}{σ}\right)^{ν}\right)^{\frac{1}{θ}-1} ν≤ft(\frac{1}{σ}\right)^{ν} t^{ν-1}

with σ, ν,and θ>0. The parameter σ 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.

`object`	The character string indicating the estimated model: "mm2 (mixture model with two competing events)".
`dist`	A character vector with two arguments describing respectively the distributions of duration time for transitions 1->2 and 1->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.
`covariates`	A numeric vector indicating the numbers of covariates respectively related to the time to the event X=2, the time to the event X=3, the long-term probability P(X=2).
`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.

Yohann Foucher <Yohann.Foucher@univ-nantes.fr>

Trebern-Launay K, KesslerM, Bayat-Makoei S, Querard AH, Briancon S, Giral M, Foucher Y. Horizontal mixture model for competing risks: a method to obtain easily interpretable results by both physicians and patients-illustration for waitlisted renal transplant candidates in a perspective of patient-centered decision making. Manuscript submitted. 2017.

Austin PC. An Introduction to Propensity Score Methods for Reducing the Effects of Confounding in Observational Studies. Multivariate Behav Res May 2011; 46(3): 399-424. <DOI: 10.1080/ 00273171.2011.568786>

# import the observed data
# X=1 corresponds to initial state with a functioning graft,
# X=2 to acute rejection episode (transient state), 
# X=3 to return to dialysis, X=4 to death with a functioning graft

data(dataDIVAT)

dim(dataDIVAT)

# A subgroup analysis to reduce the time needed for this example

dataDIVAT$id<-c(1:nrow(dataDIVAT))
set.seed(2)
d2<-dataDIVAT[dataDIVAT$id %in% sample(dataDIVAT$id, 300, replace = FALSE),]

# Data-management: two competing events
# the patient death is now X=2
# the return in dialysis is now X=3

d2$time<-NA
d2$time[d2$trajectory==1]<-d2$time1[d2$trajectory==1]

d2$time[d2$trajectory==12]<-d2$time2[d2$trajectory==12]
d2$trajectory[d2$trajectory==12]<-1

d2$time[d2$trajectory==13]<-d2$time1[d2$trajectory==13]

d2$time[d2$trajectory==123]<-d2$time2[d2$trajectory==123]
d2$trajectory[d2$trajectory==123]<-13

d2$time[d2$trajectory==14]<-d2$time1[d2$trajectory==14]

d2$time[d2$trajectory==124]<-d2$time2[d2$trajectory==124]
d2$trajectory[d2$trajectory==124]<-14

d2$trajectory[d2$trajectory==14]<-12

table(d2$trajectory)

# Univariable horizontal mixture model one binary explicative variable
# z is 1 if delayed graft function and 0 otherwise

mm2.test <- mm2(t=d2$time, sequence=d2$trajectory, weights=NULL,
  dist=c("E","W"), cuts.12=NULL, cuts.13=NULL, 
  ini.dist.12=c(9.28), ini.dist.13=c(9.92, -0.23), 
  cov.12=d2$z, init.cov.12=0.84, names.12="beta_12",
  cov.13=d2$z, init.cov.13=0.76, names.13="beta_13",
  cov.p=NULL, init.cov.p=NULL, names.p=NULL, init.intercept.p=-0.75,
  conf.int=TRUE, silent=FALSE)
  
mm2.test$table