sim.MTL: Simulate mean total lifetime
In OptimalTiming: Optimal Timing Identification

Description Usage Arguments Details Value See Also Examples

This function is used to simulate mean total lifetime for a given initial state according to the estimated transition probabilities.

1	sim.MTL(obj, state = NULL, nsim = 1000, L = 120)

`obj`	An object returned by `optim.fit`, which contains the transition probabilities and other information used to simulate mean total lifetime.
`state`	A numeric vector indicating from which state the mean total lifetime is simulated. Default is NULL, where no mean total life for a specific state is output. If obj is returned by optim.fit with treatment=NULL, there is no need to set this argument.
`nsim`	The times of simulation. The default is 1000.
`L`	The prespecified threshold for blocking the increase of residual lifetime. The default is 120. See Details.

This part describes the algorithm used to simulate mean total lifetime in detail. For an initial state, we first extract the transition probability data frame for this state, and cumulate probabilities in row direction. In the transformed data frame, the first column of which impels the time points where transition probabilities are measured, and the last column is accumulated to be 1, indicating the addition of the chance to depart from a state and the chance to remain at the state equals 1. Then, we generate a random value from uniform distribution Unif(0,1) to determine the next state by comparing this value to cumulative probabilities. The state, whose cumulative transition probability from initial state firstly surpasses the uniform value, is defined as the next state. The time interval, from the initiation of the study to where the transition take place, is defined as the interim residual life. These two variables (next state and interim residual life) are recorded for late use. Subsequently, we regard the next state as the initial state, and repeat this searching process until the absorbing state is reached or the interim residual lifetime surpasses the prespecified threshold (L). Finally, the mean total life is either the last interim residual lifetime from the initiation of study to the occurrence of absorbing state, or the prespecified threshold (L) if the absorbing has not reached yet.

If a state is given in this function, we set this state as initial state and perform the algorithm mentioned above for nsim times, and average the output to obtain mean total lifetime.

According to different type of input object, this function return different results. If the object comes from optim.fit with treatment=NULL, this function is used to simulate mean total lifetime for a given state. If the object comes from optim.fit with treatment not equals NULL, this function is used to compare mean total lifetimes of subjects who receive the new treatment to those who do not receive the new treatment.

If the input object comes from optim.fit with treatment=NULL, a list object with elements:

`state.MTL`	A data frame containing states and corresponding mean total lifetime. If state=NULL, this element does not exist.
`state.table`	The correspondence of state number and state label.

If the input object comes from optim.fit with treatment not equals NULL, a list object with elements:

strategies

Mean total lifetime for different strategies.

optim.fit

## Not run: 
library(OptimalTiming)

##################################
## Example 1: This example shows how to use this package to find
## the optimal timing of new treatment initiation

## read data
data(SimCml)

## fit multistate model with treatment not equals NULL
fit=optim.fit(data=SimCml,
         transM=matrix(c(0,1,0,0,0,1,0,0,0,1,0,1,1,1,0,0,0,1,1,1,1,0,0
         ,0,0,1,1,1,0,0,0,0,0,1,1,0,0,0,0,0,0,1,0,0,0,0,0,0,0),7,byrow=TRUE),
         nstate=7,state_label=c("diagnose","cp1","ap","cp2","bc","sct","death"),
         event_label=c("cp1.s","ap.s","cp2.s","bc.s","sct.s","death.s"),
         treatment=c("sct","sct.s"),absorb=c("death","death.s"),
         cov=c("age"),cov_value=c(0))

## compare different treatment strategies
sim.MTL(obj=fit,nsim=1000,L=120)

##################################
## Example 2: This example shows how to obtain mean total lifetime
## for a given state

## read data
data(SimCml)

## delete the information of transplant time
data=SimCml[SimCml$sct.s==0,]
del=which(names(SimCml)%in%c("sct","sct.s"))
data=data[,-del]

## fit multistate model with treatment equals NULL
fit=optim.fit(data=data,
        transM=matrix(c(0,1,0,0,0,0,0,0,1,0,1,1,0,0,0,1,
        1,1,0,0,0,0,1,1,0,0,0,0,0,1,0,0,0,0,0,0),6,byrow=TRUE),
        nstate=6,state_label=c("diagnose","cp1","ap","cp2","bc","death"),
        absorb=c("death","death.s"),
        event_label=c("cp1.s","ap.s","cp2.s","bc.s","death.s"),
        cov=c("age"),cov_value=c(0))

## calculate mean total lifetime when the initiate state is cp1 or ap
sim.MTL(obj=fit,state=c(2,3),nsim=1000,L=120)
## End(Not run)