Epi: addCov.Lexis – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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 class 'Lexis'
addCov(Lx,
                     clin,
                timescale = 1,
                    exnam,
                      tfc = "tfc")

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 and cannot be equal to any of `levels(Lx)`. 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`linical visit). 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, even it is not formally a time scale.

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" )

# Works with time split BEFORE
Lb <- addCov.Lexis(splitLexis(Lx,
                              time.scale="age",
                              breaks=seq(0,80,5) ),
                   clin,
                   exnam="clX" )
Lb
# and also AFTER
La <- splitLexis(addCov.Lexis( Lx,
                             clin,
                            exnam = "xnam" ),
                 breaks=seq(0,80,5),
                 time.scale="age" )
La
La$tfc == Lb$tfc
La$age == Lb$age
str(La)
str(Lb)

Epi

Statistical Analysis in Epidemiology

v2.44

GPL-2

Authors

Bendix Carstensen [aut, cre], Martyn Plummer [aut], Esa Laara [ctb], Michael Hills [ctb]

Initial release

2021-02-28