Encoding: UTF-8
Type: Package
Version: 1.3.2
Date: 2023-01-19
Title: Analyzing Survival Data from an Illness-Death Model
Depends: R (≥ 2.8.1),survival,base
Description: Contains functions for data preparation, prediction of transition probabilities, estimating semi-parametric regression models and for implementing nonparametric estimators for other quantities. See Meira-Machado and Roca-Pardiñas (2011) <doi:10.18637/jss.v038.i03>.
License: GPL-3
LazyLoad: yes
LazyData: yes
NeedsCompilation: no
Packaged: 2023-01-19 20:29:21 UTC; User
Author: Luis Meira-Machado ORCID iD [aut, cre], Javier Roca-Pardinas ORCID iD [aut], Artur Araujo ORCID iD [ctb]
Maintainer: Luis Meira-Machado <lmachado@math.uminho.pt>
Repository: CRAN
Date/Publication: 2023-01-20 16:00:09 UTC

Analyzing survival data from an illness-death model

Description

p3state.msm provides functions for estimating semi-parametric regression models but also to implement nonparametric estimators for the transition probabilities. The methods can also be used in progressive three-state models. In progressive three-state models, estimators for other quantities such as the bivariate distribution function (for the sequentially ordered events) are also given.

Details

Package: p3state.msm
Type: Package
Version: 1.3.2
Date: 2023-01-19
License: GPL-3
LazyLoad: yes
LazyData: yes

Author(s)

Luis Meira-Machado, Javier Roca Pardinas roca@uvigo.es
and Artur Araújo artur.stat@gmail.com
Maintainer: Luis Meira-Machado lmachado@math.uminho.pt

References

Crowley J., Hu M. (1977). Covariance analysis of heart transplant survival data. Journal of the American Statistical Association, 72(357), 27-36. doi:10.2307/2286902

Meira-Machado L., De Una-Alvarez J., Cadarso-Suarez C. (2006). Nonparametric estimation of transition probabilities in a non-Markov illness-death model. Lifetime Data Analysis, 12(3), 325-344. doi:10.1007/s10985-006-9009-x

de Una-Alvarez J., Meira-Machado L. (2008). A simple estimator of the bivariate distribution function for censored gap times. Statistics & Probability Letters, 78(15), 2440-2445. doi:10.1016/j.spl.2008.02.031

Meira-Machado L., Roca-Pardinas J. (2011). p3state.msm: Analyzing Survival Data from an Illness-Death Model. Journal of Statistical Software, 38(3), 1-18. doi:10.18637/jss.v038.i03

Bivariate distribution function

Description

Computation of the bivariate distribution function.

Usage

Biv(object, time1, time2)

Arguments

object

Component datafr of an object of class p3state.

time1

The first time for obtaining estimates for the transition probabilities, bivariate distribution function. NULL is equivalent to 0.

time2

The second time for obtaining estimates for the bivariate distribution function.

Value

Returns a single value.

Author(s)

Luis Meira-Machado, Javier Roca-Pardinas and Artur Araújo

References

Meira-Machado L., Roca-Pardinas J. (2011). p3state.msm: Analyzing Survival Data from an Illness-Death Model. Journal of Statistical Software, 38(3), 1-18. doi:10.18637/jss.v038.i03

See Also

p3state

Examples

data(heart2)
res.p3state<-p3state(heart2)
Biv(res.p3state,time1=30,time2=300)

Regression dataset

Description

Returns the input data in a different format. Provides the adequate dataset for implementing regression models.

Usage

data.creation.reg(data)

Arguments

data

A data.frame with at least 5 variables: times1 (time of the intermediate event/censoring time), delta (indicator of transition to the intermediate event), times2 (time to the final event/censoring time), time (times1 + times2) and status (censoring indicator: "dead"=1,"alive"=0). The remaining variables in the data.frame are left for the covariates.

Value

A data.frame in a counting process format.

Author(s)

Luis Meira-Machado, Javier Roca-Pardinas and Artur Araújo

References

Meira-Machado L., Roca-Pardinas J. (2011). p3state.msm: Analyzing Survival Data from an Illness-Death Model. Journal of Statistical Software, 38(3), 1-18. doi:10.18637/jss.v038.i03

More Stanford heart transplant data

Description

This contains the Stanford heart transplant data in a different format. The main data set is in (heart). Survival of patients on the waiting list for the Stanford heart transplant program.

Usage

data(heart2)

Format

A data frame with 103 observations on the following 8 variables.

times1

Time of transplant/censoring time.

delta

Transplant indicator.

times2

Time to death since the transplant/censoring time.

time

times1 + times2

status

Censoring indicator: dead=1, alive=0.

age

Age-48 years.

year

Year of acceptance; in years after 1 Nov 1967.

surgery

Prior bypass surgery; 1=yes.

References

Crowley J., Hu M. (1977). Covariance analysis of heart transplant survival data. Journal of the American Statistical Association, 72(357), 27-36. doi:10.2307/2286902

Inference in progressive multi-state models with three states

Description

This function provides nonparametric estimates in progressive multi-state models with three states (illness-death model and three-state model). Also fits semi-parametric Cox models in a multi-state framework (one for each transition).

Usage

p3state(data, coxdata=NULL, formula=NULL, regression=NULL)

Arguments

data

A data.frame in which to interpret the variables named in the covariates. A data frame with at least 5 variables: times1 (time of the intermediate event/censoring time), delta (indicator of transition to the intermediate event), times2 (time to the final event/censoring time), time (times1 + times2) and status (censoring indicator: "dead"=1, "alive"=0). The remaining variables in the data.frame are left for the covariates.

coxdata

Data set in a counting process data-structure. This data set can be obtained using data.creation.reg. If NULL the main function p3state will automatically create this dataset every time it is called.

formula

A formula giving the vector of covariates. For example formula=~age+sex

.

regression

A logical variable indicating whether you want the regression model.

Details

Multi-state models may be considered a generalization of survival analysis where survival is the ultimate outcome of interest but where intermediate (transient) states are identified. The influence of the intermediate events on survival may be investigated through the effect of the time-dependent covariate (using the Cox regression model with time-dependent covariates; TDCM). However, these covariates can also be re-expressed as a multi-state model with states based on the values of the covariate (typically coded as 1=yes; 0=no). If all subjects observe the intermediate event then the time-dependent covariate makes it possible to use the progressive three-state model. Otherwise makes it feasible to use an illness-death model. In these models, issues of interest include the estimation of transition probabilities and assessing the effects of individual risk factors.

Value

Returns a list of the following items:

descriptives

Vector with observed transitions between states.

datafr

data.frame to be used for obtaining the nonparametric estimates and for plotting purposes.

tdcm

Object of class ‘coxph’ with the fit of the Cox model with time-dependent covariates.

msm12

Object of class ‘coxph’ with the fit of the Cox model for transition from state 1 to state 2.

msm13

Object of class ‘coxph’ with the fit of the Cox model for transition from state 1 to state 3 (only for the progressive three-state model).

cmm23

Object of class ‘coxph’ with the fit of the Cox Markov model for transition from state 2 to state 3.

tma

Object of class ‘coxph’ with the fit of a Cox model for testing the Markov assumption.

Author(s)

Luis Meira-Machado, Javier Roca-Pardinas and Artur Araújo

References

Meira-Machado L., De Una-Alvarez J., Cadarso-Suarez C. (2006). Nonparametric estimation of transition probabilities in a non-Markov illness-death model. Lifetime Data Analysis, 12(3), 325-344. doi:10.1007/s10985-006-9009-x

de Una-Alvarez J., Meira-Machado L. (2008). A simple estimator of the bivariate distribution function for censored gap times. Statistics & Probability Letters, 78(15), 2440-2445. doi:10.1016/j.spl.2008.02.031

Meira-Machado L., Roca-Pardinas J. (2011). p3state.msm: Analyzing Survival Data from an Illness-Death Model. Journal of Statistical Software, 38(3), 1-18. doi:10.18637/jss.v038.i03

Examples

data(heart2)
res.p3state <- p3state(heart2, formula=~age+year+surgery)
summary(res.p3state)

##Only regression
summary(res.p3state, model="TDCM")
summary(res.p3state, model="CMM")

##without regression
summary(res.p3state, time1=20, time2=200)

##Both
summary(res.p3state, estimate=TRUE, time1=20, time2=200, model="CMM")

##Just for illustration purposes we create a new subset by restricting 
##the original data set from those subjects experiencing the transplant
## (progressive three-state model)
p <- which((heart2$delta==0 & heart2$status==0) | heart2$delta==1)
exampledata <- heart2[p,]
res2.p3state <- p3state(exampledata)
summary(res2.p3state)

Transition probabilities

Description

Computation of the transition probabilities.

Usage

pLIDA(object, time1, time2,tp=NULL)

Arguments

object

Component datafr of an object of class p3state.

time1

The first time for obtaining estimates for the transition probabilities, bivariate distribution function. NULL is equivalent to 0.

time2

The second time for obtaining estimates for the bivariate distribution function.

tp

Optional argument: tp="all" (default value) to obtain all the transition probabilities p11, p12 and p22; tp="p11" to obtain only p11; tp="p12" to obtain only p12; tp="p22" to obtain only p22.

Value

Returns a single value if argument tp equals "p11", "p12", or "p22". Returns a list if argument tp equals "all".

Author(s)

Luis Meira-Machado, Javier Roca-Pardinas and Artur Araújo

References

Meira-Machado L., Roca-Pardinas J. (2011). p3state.msm: Analyzing Survival Data from an Illness-Death Model. Journal of Statistical Software, 38(3), 1-18. doi:10.18637/jss.v038.i03

See Also

p3state

Examples

data(heart2)
res.p3state<-p3state(heart2)
pLIDA(res.p3state,time1=30,time2=300)

Plot Method for an p3state object

Description

Plot method for an object of class ‘p3state’. Draws the estimated transition probabilities, bivariate distribution of the gap times and marginal distribution of the second gap time (the last two only available for the progressive three-state model)

Usage

## S3 method for class 'p3state'
plot(x, plot.trans = NULL, plot.marginal = NULL,
plot.bivariate = NULL, time1, time2, xlab, ylab, zlab, col, col.biv = NULL, ...)

Arguments

x

An object of class ‘p3state’.

plot.trans

Graphical output for the transition probabilities. By default, plot.trans=FALSE. Possible values are: "all", "P11", "P12", "P22" and "P23".

plot.marginal

Graphical output for the marginal distribution of the second time (only available for the progressive three-state model). By default, plot.marginal=FALSE.

plot.bivariate

Graphical output for the bivariate distribution (only available for the progressive three-state model). By default, plot.bivariate=FALSE.

time1

The first time for obtaining estimates of the transition probabilities, bivariate distribution function. NULL is equivalent to 0.

time2

The second time for obtaining estimates of the bivariate distribution function.

xlab

x-axix label.

ylab

y-axix label.

zlab

z-axix label (only for the bivariate distribution).

col

Colour for the bivariate plot.

col.biv

A logical variable indicating whether you want color to be used in the filled.contour plot. By default col.biv = FALSE.

...

Further arguments for plot.

Value

No value is returned.

Author(s)

Luis Meira-Machado, Javier Roca-Pardinas and Artur Araújo

References

Meira-Machado L., Roca-Pardinas J. (2011). p3state.msm: Analyzing Survival Data from an Illness-Death Model. Journal of Statistical Software, 38(3), 1-18. doi:10.18637/jss.v038.i03

See Also

p3state

Examples

data(heart2)
res.p3state<-p3state(heart2)

##Only transition probabilities
plot(res.p3state,plot.trans="all",time1=20,time2=100)

##Example of three-state model. All plots.
p<-which((heart2$delta==0 & heart2$status==0) | heart2$delta==1)
inputdata<-heart2[p,]
res2.p3state<-p3state(inputdata)
plot(res2.p3state,plot.trans="all",time1=20,
time2=200,plot.bivariate=TRUE,plot.marginal=TRUE)

Summary Methods for an p3state Object

Description

Provides results for an object of class ‘p3state’. It gives the estimated transition probabilities, bivariate distribution of the gap times and marginal distribution of the second gap time (the last two only available for the progressive three-state model). Also provides the results for the fit of semi-parametric Cox regression models.

Usage

## S3 method for class 'p3state'
summary(object, model = NULL, covmat = NULL,
estimate = NULL, time1 = NULL, time2 = NULL, ...)

Arguments

object

An object of class ‘p3state’.

model

A character string specifying which model(s) to fit. Possible values are "TDCM", "CMM" and "CSMM". If NULL none of the regression models will be implemented.

covmat

Return the variance-covariance matrices? By default covmat=FALSE.

estimate

If TRUE nonparametric estimates are given. These include: transition probabilities, bivariate distribution function and marginal distribution of the second time (the last two only for the progressive three-state model).

time1

The first time for obtaining estimates of the transition probabilities, bivariate distribution function. NULL is equivalent to 0.

time2

The second time for obtaining estimates of the bivariate distribution function.

...

Further arguments for summary.

Value

No value is returned.

Author(s)

Luis Meira-Machado, Javier Roca-Pardinas and Artur Araújo

References

Meira-Machado L., Roca-Pardinas J. (2011). p3state.msm: Analyzing Survival Data from an Illness-Death Model. Journal of Statistical Software, 38(3), 1-18. doi:10.18637/jss.v038.i03

See Also

p3state

Examples

data(heart2)
res.p3state<-p3state(heart2, formula=~age+year)
summary(res.p3state,model="CMM",time1=20,time2=100)