expand.covs.msdata {mstate}

Expand covariates in multi-state dataset in long format

Description

Given a multi-state dataset in long format, and one or more covariates, this function adds transition-specific covariates, expanding the original covariate(s), to the dataset. The original dataset with the transition-specific covariates appended is returned.

Usage

## S3 method for class 'msdata'
expand.covs(data, covs, append = TRUE, longnames = TRUE, ...)

Arguments

data

An object of class "msdata", such as output by msprep

covs

A character vector containing the names of the covariates in data to be expanded

append

Logical value indicating whether or not the design matrix for the expanded covariates should be appended to the data (default=TRUE)

longnames

Logical value indicating whether or not the labels are to be used for the names of the expanded covariates that are categorical (default=TRUE); in case of FALSE numbers from 1 up to the number of contrasts are used

...

Further arguments to be passed to or from other methods. They are ignored in this function.

Details

For a given basic covariate Z, the transition-specific covariate for transition s is called Z.s. The concept of transition-specific covariates in the context of multi-state models was introduced by Andersen, Hansen & Keiding (1991), see also Putter, Fiocco & Geskus (2007). It is only unambiguously defined for numeric covariates or for explicit codings. Then it will take the value 0 for all rows in the long format dataframe for which trans does not equal s. For the rows for which trans equals s, the original value of Z is copied. In expand.covs, when a given covariate is a factor, it will be expanded on the design matrix given by model.matrix. Missing values in the basic covariates are allowed and result in missing values in the expanded covariates.

Value

An object of class 'msdata', containing the design matrix for the transition- specific covariates, either on its own (append=FALSE) or appended to the data (append=TRUE).

Author(s)

Hein Putter [e-mail]

References

Andersen PK, Hansen LS, Keiding N (1991). Non- and semi-parametric estimation of transition probabilities from censored observation of a non-homogeneous Markov process. Scandinavian Journal of Statistics 18, 153–167.

Putter H, Fiocco M, Geskus RB (2007). Tutorial in biostatistics: Competing risks and multi-state models. Statistics in Medicine 26, 2389–2430.

Examples

# transition matrix for illness-death model
tmat <- trans.illdeath()
# small data set in wide format
tg <- data.frame(illt=c(1,1,6,6,8,9),ills=c(1,0,1,1,0,1),
        dt=c(5,1,9,7,8,12),ds=c(1,1,1,1,1,1),
        x1=c(1,1,1,2,2,2),x2=c(6:1))
tg$x1 <- factor(tg$x1,labels=c("male","female"))
# data in long format using msprep
tglong <- msprep(time=c(NA,"illt","dt"),
        status=c(NA,"ills","ds"),data=tg,
        keep=c("x1","x2"),trans=tmat)
# expanded covariates
expand.covs(tglong,c("x1","x2"),append=FALSE)
expand.covs(tglong,"x1")
expand.covs(tglong,"x1",longnames=FALSE)