addCov.Lexis: Add covariates (typically clinical measurements) taken at...

Description Usage Arguments Value Author(s) See Also Examples

View source: R/addCov.Lexis.R

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

1
2
3
4
5
6
## 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 (time from clinical 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

See Also

cutLexis, mcutLexis, splitLexis, Lexis

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
# 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)

Example output

NOTE: entry.status has been set to "Alive" for all.
ClassesLexisand 'data.frame':	3 obs. of  14 variables:
 $ per    : 'cal.yr' num  1966 1973 1992
 $ age    : 'cal.yr' num  13.06 18.44 4.54
 $ lex.dur: 'cal.yr' num  31.9 22.7 6.58
 $ lex.Cst: Factor w/ 2 levels "Alive","Dead": 1 1 1
 $ lex.Xst: Factor w/ 2 levels "Alive","Dead": 2 1 2
 $ lex.id : int  1 2 3
 $ id     : chr  "A" "B" "C"
 $ birth  : chr  "1952-07-14" "1954-04-01" "1987-06-10"
 $ entry  : chr  "1965-08-04" "1972-09-08" "1991-12-23"
 $ exit   : chr  "1997-06-27" "1995-05-23" "1998-07-24"
 $ fail   : num  1 0 1
 $ bt     : 'cal.yr' num  1953 1954 1987
 $ en     : 'cal.yr' num  1966 1973 1992
 $ ex     : 'cal.yr' num  1997 1995 1999
 - attr(*, "time.scales")= chr [1:2] "per" "age"
 - attr(*, "time.since")= chr [1:2] "" ""
 - attr(*, "breaks")=List of 2
  ..$ per: NULL
  ..$ age: NULL
       per       age   lex.dur lex.Cst lex.Xst lex.id id
1 1965.589 13.056810 31.895962   Alive    Dead      1  A
2 1972.686 18.439425 22.702259   Alive   Alive      2  B
3 1991.974  4.536619  6.584531   Alive    Dead      3  C
  lex.id    per  bp chol xnam
1      1 1977.3 120    5   X2
2      1 1971.7 140    7   X1
3      3 1996.2 160    8   X1
4      2 1990.6 157    9   X2
       per lex.id       age   lex.dur lex.Cst lex.Xst id bp chol xnam exnam tfc
1 1965.589      1 13.056810 31.895962   Alive    Dead  A NA   NA <NA>  <NA>  NA
2 1972.686      2 18.439425 22.702259   Alive   Alive  B NA   NA <NA>  <NA>  NA
3 1991.974      3  4.536619  6.584531   Alive    Dead  C NA   NA <NA>  <NA>  NA
       per lex.id       age   lex.dur lex.Cst lex.Xst id bp chol xnam tfc
1 1965.589      1 13.056810 31.895962   Alive    Dead  A NA   NA <NA>  NA
2 1972.686      2 18.439425 22.702259   Alive   Alive  B NA   NA <NA>  NA
3 1991.974      3  4.536619  6.584531   Alive    Dead  C NA   NA <NA>  NA
   lex.id      per       age   lex.dur lex.Cst lex.Xst id bp chol xnam  clX tfc
1       1 1965.589 13.056810 1.9431896   Alive   Alive  A NA   NA <NA> <NA>  NA
2       1 1967.533 15.000000 5.0000000   Alive   Alive  A NA   NA <NA> <NA>  NA
3       1 1972.533 20.000000 5.0000000   Alive   Alive  A NA   NA <NA> <NA>  NA
4       1 1977.533 25.000000 5.0000000   Alive   Alive  A NA   NA <NA> <NA>  NA
5       1 1982.533 30.000000 5.0000000   Alive   Alive  A NA   NA <NA> <NA>  NA
6       1 1987.533 35.000000 5.0000000   Alive   Alive  A NA   NA <NA> <NA>  NA
7       1 1992.533 40.000000 4.9527721   Alive    Dead  A NA   NA <NA> <NA>  NA
8       2 1972.686 18.439425 1.5605749   Alive   Alive  B NA   NA <NA> <NA>  NA
9       2 1974.246 20.000000 5.0000000   Alive   Alive  B NA   NA <NA> <NA>  NA
10      2 1979.246 25.000000 5.0000000   Alive   Alive  B NA   NA <NA> <NA>  NA
11      2 1984.246 30.000000 5.0000000   Alive   Alive  B NA   NA <NA> <NA>  NA
12      2 1989.246 35.000000 5.0000000   Alive   Alive  B NA   NA <NA> <NA>  NA
13      2 1994.246 40.000000 1.1416838   Alive   Alive  B NA   NA <NA> <NA>  NA
14      3 1991.974  4.536619 0.4633812   Alive   Alive  C NA   NA <NA> <NA>  NA
15      3 1992.437  5.000000 5.0000000   Alive   Alive  C NA   NA <NA> <NA>  NA
16      3 1997.437 10.000000 1.1211499   Alive    Dead  C NA   NA <NA> <NA>  NA
   lex.id      per       age   lex.dur lex.Cst lex.Xst id bp chol xnam tfc
1       1 1965.589 13.056810 1.9431896   Alive   Alive  A NA   NA <NA>  NA
2       1 1967.533 15.000000 5.0000000   Alive   Alive  A NA   NA <NA>  NA
3       1 1972.533 20.000000 5.0000000   Alive   Alive  A NA   NA <NA>  NA
4       1 1977.533 25.000000 5.0000000   Alive   Alive  A NA   NA <NA>  NA
5       1 1982.533 30.000000 5.0000000   Alive   Alive  A NA   NA <NA>  NA
6       1 1987.533 35.000000 5.0000000   Alive   Alive  A NA   NA <NA>  NA
7       1 1992.533 40.000000 4.9527721   Alive    Dead  A NA   NA <NA>  NA
8       2 1972.686 18.439425 1.5605749   Alive   Alive  B NA   NA <NA>  NA
9       2 1974.246 20.000000 5.0000000   Alive   Alive  B NA   NA <NA>  NA
10      2 1979.246 25.000000 5.0000000   Alive   Alive  B NA   NA <NA>  NA
11      2 1984.246 30.000000 5.0000000   Alive   Alive  B NA   NA <NA>  NA
12      2 1989.246 35.000000 5.0000000   Alive   Alive  B NA   NA <NA>  NA
13      2 1994.246 40.000000 1.1416838   Alive   Alive  B NA   NA <NA>  NA
14      3 1991.974  4.536619 0.4633812   Alive   Alive  C NA   NA <NA>  NA
15      3 1992.437  5.000000 5.0000000   Alive   Alive  C NA   NA <NA>  NA
16      3 1997.437 10.000000 1.1211499   Alive    Dead  C NA   NA <NA>  NA
 [1] NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA NA
 [1] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
[16] TRUE
ClassesLexisand 'data.frame':	16 obs. of  11 variables:
 $ lex.id : int  1 1 1 1 1 1 1 2 2 2 ...
 $ per    : num  1966 1968 1973 1978 1983 ...
 $ age    : num  13.1 15 20 25 30 ...
 $ lex.dur: num  1.94 5 5 5 5 ...
 $ lex.Cst: Factor w/ 2 levels "Alive","Dead": 1 1 1 1 1 1 1 1 1 1 ...
 $ lex.Xst: Factor w/ 2 levels "Alive","Dead": 1 1 1 1 1 1 2 1 1 1 ...
 $ id     : chr  "A" "A" "A" "A" ...
 $ bp     : num  NA NA NA NA NA NA NA NA NA NA ...
 $ chol   : num  NA NA NA NA NA NA NA NA NA NA ...
 $ xnam   : Factor w/ 0 levels: NA NA NA NA NA NA NA NA NA NA ...
 $ tfc    : num  NA NA NA NA NA NA NA NA NA NA ...
 - attr(*, "breaks")=List of 2
  ..$ per: NULL
  ..$ age: num [1:17] 0 5 10 15 20 25 30 35 40 45 ...
 - attr(*, "time.scales")= chr [1:2] "per" "age"
 - attr(*, "time.since")= chr [1:2] "" ""
ClassesLexisand 'data.frame':	16 obs. of  12 variables:
 $ lex.id : int  1 1 1 1 1 1 1 2 2 2 ...
 $ per    : num  1966 1968 1973 1978 1983 ...
 $ age    : num  13.1 15 20 25 30 ...
 $ lex.dur: num  1.94 5 5 5 5 ...
 $ lex.Cst: Factor w/ 2 levels "Alive","Dead": 1 1 1 1 1 1 1 1 1 1 ...
 $ lex.Xst: Factor w/ 2 levels "Alive","Dead": 1 1 1 1 1 1 2 1 1 1 ...
 $ id     : chr  "A" "A" "A" "A" ...
 $ bp     : num  NA NA NA NA NA NA NA NA NA NA ...
 $ chol   : num  NA NA NA NA NA NA NA NA NA NA ...
 $ xnam   : Factor w/ 0 levels: NA NA NA NA NA NA NA NA NA NA ...
 $ clX    : Factor w/ 0 levels: NA NA NA NA NA NA NA NA NA NA ...
 $ tfc    : num  NA NA NA NA NA NA NA NA NA NA ...
 - attr(*, "breaks")=List of 2
  ..$ per: NULL
  ..$ age: num [1:17] 0 5 10 15 20 25 30 35 40 45 ...
 - attr(*, "time.scales")= chr [1:2] "per" "age"
 - attr(*, "time.since")= chr [1:2] "" ""

Epi documentation built on Feb. 28, 2021, 1:06 a.m.

Related to addCov.Lexis in Epi...