R: Add covariates (typically clinical measurements) taken at...

addCov.Lexis {Epi}

R Documentation

Add covariates (typically clinical measurements) taken at known times to a Lexis object.

Description

When follow-up in a multistate model is represented in a Lexis object we may want to add information on covariates, for example clinical measurements, obtained at different times. This function cuts the follow-up time (see cutLexis) at the times of measurement and carries the measurements forward in time to the next measurement occasion.

Usage

## S3 method for class 'Lexis'
addCov( Lx,
                      clin,
                 timescale = 1,
                     exnam,
                       tfc = "tfc",
                 addScales = FALSE )

Arguments

`Lx`	A Lexis object with follow-up of a cohort.
`clin`	A data frame with covariates to add (typically clinical measurements). Must contain a variable `lex.id` identifying the persons represented in `Lx`, as well as a variable with the same name as one of the `timeScales` in `Lx`, identifying the time at which covariates are measured. The times must be unique within each person; if not records with duplicate times are discarded, and a warning issued. This is done using `duplicated`, so not very well-defined, it is advisable that you do this by yourself.
`timescale`	Numerical or character. Number or name of a timescale in `Lx`. The `clin` data frame must have a variable of this name indicating the time at which the covariate measurements were taken.
`exnam`	Character. Name of the variable in `clin` with the examination names (such as `wave1`, `wave2` etc.). Values may not be repeated within person. Will be carried over to the resulting `Lexis` object. If there is no such variable in `clin` it will be constructed; if the argument is omitted, a variable called `exnam` with values `ex1`, `ex2` etc. will be constructed.
`tfc`	Character (`t`ime `f`rom `c`ovariate). Name of the variable in the result which will contain the time since the most recent covariate date. If the argument is omitted a variable called `tfc` will be constructed. If `addScales` is `TRUE` this is included among the time scales.
`addScales`	Logical. Should timescales representing time since each examination time time be added? They will be named `paste("tf",exnam)`.

Details

The implementation is clumpy, the function is slow.

Value

A Lexis object representing the same follow-up as Lx, with cuts added at the times of examination, and covariate measurements added for all records representing follow-up after the most recent time of measurement.

Author(s)

Bendix Carstensen, b@bxc.dk, http://BendixCarstensen.com

Examples

# A small bogus cohort
xcoh <- structure( list( id = c("A", "B", "C"),
                      birth = c("1952-07-14", "1954-04-01", "1987-06-10"),
                      entry = c("1965-08-04", "1972-09-08", "1991-12-23"),
                       exit = c("1997-06-27", "1995-05-23", "1998-07-24"),
                       fail = c(1, 0, 1) ),
                     .Names = c("id", "birth", "entry", "exit", "fail"),
                  row.names = c("1", "2", "3"),
                      class = "data.frame" )

# Convert the character dates into numerical variables (fractional years)
xcoh$bt <- cal.yr( xcoh$birth )
xcoh$en <- cal.yr( xcoh$entry )
xcoh$ex <- cal.yr( xcoh$exit  )

# Define as Lexis object with timescales calendar time and age
Lcoh <- Lexis( entry = list( per=en ),
                exit = list( per=ex, age=ex-bt ),
         exit.status = factor( fail, 0:1, c("Alive","Dead") ),
                data = xcoh )
str( Lcoh )
Lx <- Lcoh[,1:7]

# Data frame with clinical examination data, date of examination in per
clin <- data.frame( lex.id = c(1,1,3,2),
                       per = c(1977.3,1971.7,1996.2,1990.6),
                        bp = c(120,140,160,157),
                      chol = c(5,7,8,9),
                      xnam = c("X2","X1","X1","X2") )
Lx
clin 

# Different behavours using exnam and addScales
addCov.Lexis( Lx, clin )
addCov.Lexis( Lx, clin, exnam="xnam" )
addCov.Lexis( Lx, clin, addScales=TRUE )
addCov.Lexis( Lx, clin, addScales=TRUE, exnam="xnam" )

# Works with time split BEFORE
Lb <- addCov.Lexis( splitLexis( Lx,
                                time.scale="age",
                                breaks=seq(0,80,5) ),
                    clin,
                    exnam="clX" )
Lb
# ...or AFTER, but only if addScales is given
La <- splitLexis( addCov.Lexis( Lx,
                              clin,
                             exnam = "xnam" ),
                  breaks=seq(0,80,5),
                  time.scale="age" )
La
La <- splitLexis( addCov.Lexis( Lx,
                              clin,
                             exnam = "xnam",
                         addScales = TRUE ),
                  breaks=seq(0,80,5),
                  time.scale="age" )
La

[Package Epi version 2.37 Index]