Lexis {Epi}

Create a Lexis object of follow-up

Description

Create an object of class Lexis to represent follow-up in multiple states on multiple time scales.

Usage

Lexis( entry,
        exit,
    duration,
entry.status = 0,
 exit.status = 0,
          id,
        data,
       merge = TRUE,
      states,
       notes = TRUE,
         tol = .Machine$double.eps^0.5,
keep.dropped = FALSE)
## S3 method for class 'Lexis'
print(x, ...,
                      td = 2,
                      nd = 3,
                    rnam = FALSE,
                     org = FALSE)

Arguments

entry

a named list of entry times. Each element of the list is a numeric variable representing the entry time on the named time scale. The name of the elements of the list will appear as names of variables designated as timescales in the resulting object. All time scales must have the same units (e.g. years). The names of the timescales must be different from any column name in data.

exit

a named list of exit times.

duration

a numeric vector giving the duration of follow-up.

entry.status

a vector or a factor giving the status at entry

exit.status

a vector or factor giving status at exit. Any change in status during follow-up is assumed to take place exactly at the exit time.

id

a vector giving a unique identity value for each person represented in the Lexis object. Defaults to 1:nrow(data)

data

an optional data frame, list, or environment containing the variables. If not found in data, the variables are taken from the environment from which Lexis was called.

merge

a logical flag. If TRUE then the data argument will be coerced to a data frame and then merged with the resulting Lexis object.

states

A vector of labels for the states. If given, the state variables lex.Cst and lex.Xst are returned as factors with identical levels attributes equal to states.

notes

Logical. Should notes on entry states and time be given.

tol

Numerical tolerance for follow-up time. Rows with duration less than this value are automatically dropped.

keep.dropped

Logical. Should dropped rows from data be saved as an attribute with the object for inspection?

x

A Lexis object.

td

Number of digits after the decimal separator used for timescales and lex.dur when printing

nd

Number of digits after the decimal separator used for other numerical variables in the Lexis object.

rnam

Logical, should row names be printed?

org

Logical, should columns be printed in the original order?

...

Other parameters passed on to print.data.frame.

Details

The analysis of long-term population-based follow-up studies typically requires multiple time scales to be taken into account, such as age, calendar time, or time since an event. A Lexis object is a data frame with additional attributes that allows these multiple time dimensions of follow-up to be managed.

Separate variables for current end exit state allows representation of multistate data.

Lexis objects are named after the German demographer Wilhelm Lexis (1837-1914), who is credited with the invention of the "Lexis diagram" for representing population dynamics simultaneously by several timescales in the book "Einleitung in die Theorie der Bevolkerungsstatistik" from 1875.

The Lexis function can create a minimal Lexis object with only those variables required to define the follow-up history in each row. Additional variables can be merged into the Lexis object using the merge method for Lexis objects. The latter is the default.

The print method prints the time-scale variables and other numerical variables rounded, possibly differently. Reorders columns so the Lexis-specific variables comes first. Returns (invisibly) a character vector with the (re)ordering of the columns in the object, even if org = TRUE is set.

There are also merge, subset, transform and many other methods for Lexis objects. They work as the corresponding methods for data-frames but ensures that the result is a Lexis object.

Value

An object of class Lexis. This is represented as a data frame with a column for each time scale (with names equal to the union of the names of entry and exit), and additional columns with the following names:

lex.id

Identification of the persons.

lex.dur

Duration of follow-up.

lex.Cst

Entry status (Current state), i.e. the state in which the follow up takes place.

lex.Xst

Exit status (eXit state), i.e. that state taken up after dur in lex.Cst.

If merge=TRUE (the default) then the Lexis object will also contain all variables from the data argument.

Note

Only two of the three arguments entry, exit and duration need to be given. If the third parameter is missing, it is imputed.

entry, exit must be numeric, using Date variables will cause some of the utilities to crash. Transformation by cal.yr is recommended.

If only either exit or duration are supplied it is assumed that entry is 0. This is only meaningful (and therefore checked) if there is only one timescale.

If any of entry.status or exit.status are of mode character, they will both be converted to factors.

If entry.status is not given, then its class is automatically set to that of exit.status. If exit.status is a character or factor, the value of entry.status is set to the first level. This may be highly undesirable, and therefore noted. For example, if exit.status is character the first level will be the first in the alphabetical ordering; slightly unfortunate if values are c("Well","Diseased"). If exit.status is logical, the value of entry.status set to FALSE. If exit.status is numeric, the value of entry.status set to 0.

If entry.status or exit.status are factors or character, the corresponding state variables in the returned Lexis object, lex.Cst and lex.Xst will be (unordered) factors with identical set of levels, namely the union of the levels of entry.status and exit.status.

Author(s)

Martyn Plummer with contributions from Bendix Carstensen

See Also

plot.Lexis, splitLexis, cutLexis, mcutLexis, rcutLexis, addCov.Lexis, merge.Lexis, subset.Lexis, cbind.Lexis, rbind.Lexis, transform.Lexis, summary.Lexis, unLexis, timeScales, timeBand, entry, exit, transient, absorbing, dur

Examples

# A small bogus cohort
xcoh <- structure(list( id = c("A", "B", "C"),
                     birth = c("14/07/1952", "01/04/1954", "10/06/1987"),
                     entry = c("04/08/1965", "08/09/1972", "23/12/1991"),
                      exit = c("27/06/1997", "23/05/1995", "24/07/1998"),
                      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 <- cal.yr(xcoh, format="%d/%m/%Y", wh=2:4)
# xcoh <- cal.yr(xcoh, format="%d/%m/%Y", wh=2:4)

# See how it looks
xcoh
str( xcoh )

# Define a Lexis object with timescales calendar time and age
Lcoh <- Lexis(entry = list(per = entry ),
               exit = list(per = exit,
                           age = exit - birth),
        exit.status = fail,
               data = xcoh)

# Using character states may have undesired effects:
xcoh$Fail <- c("Dead","Well","Dead")
xcoh
L1 <- Lexis(entry = list(per = entry),
             exit = list(per = exit,
                         age = exit - birth),
      exit.status = Fail,
             data = xcoh)
L1
# people start being dead!

# ...unless you order the levels sensibly
xcoh$Fail <- factor(xcoh$Fail, levels = c("Well", "Dead"))
L2 <- Lexis(entry = list(per = entry),
             exit = list(per = exit,
                         age = exit - birth),
      exit.status = Fail,
             data = xcoh)
L2
# behaviour of print method:
L2[,1:6]
L2[,6:1]
print(L2[,6:1], org=TRUE)
(print(L2[,-3]))