Epi (version 2.19)

addCov.Lexis: 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 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 the 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 variable of this name in clin it will be constructed; if argument omitted, a variable called exnam with values ex.1, ex.2 etc. will be constructed.

tfc

Character (time from covariate). Name of the variable in the result which will contain the time since the most recent covariate date. This is not a time scale as it is reset to 0 at each new covariate time. Also note that by this very token, this variable will be meaningless if you splitLexis after using addCov.Lexis.

addScales

Logical. Should timescales representing time since each covariate time be added? They will be named paste("tf",exnam). Not implemented, argument currently ignored.

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.

Details

The implementation is clumpy, the function is slow.

See Also

cutLexis, mcutLexis, splitLexis, Lexis

Examples

# NOT RUN {
# 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) )
Lx
clin 

# Works with time split BEFORE adding clinical data:
Lb <- addCov.Lexis( splitLexis( Lx,
                                time.scale="age",
                                breaks=seq(0,80,5) ),
                    clin,
                    exnam="clX" )
Lb
# With time split AFTER adding clinincal data, variable tfc is largely meaningless:
La <- splitLexis( addCov.Lexis( Lx,
                                clin,
                                exnam="clX" ),
                  breaks=seq(0,80,5),
                  time.scale="age" )
La
# }