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

### See Also

`cutLexis`, `mcutLexis`, `splitLexis`, `Lexis`

### 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.40 Index]