Epi (version 1.1.20)

Lexis: Create a Lexis object

Description

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

Usage

Lexis(entry, exit, duration, entry.status = 0, exit.status = 0, id, data,
      merge=TRUE, states )

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. All time scales must have the same units (e.g. years). The names of the timescales must be different from any colu

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 row of the Lexis object.

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.

Value

• An object of class Lexis. This is represented as a data frame with a column for each time scale, and additional columns with the following names:
• lex.id
  Identification of the inidvidual
• 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 then the Lexis object will also contain all variables from the data argument.

Details

The analysis of long-term population-based follow-up studies typically requires multiple time scales to be taken into account, such as age, calender 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. The Lexis function creates 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. This is the default.

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

See Also

plot.Lexis, splitLexis, cutLexis, merge.Lexis, subset.Lexis, transform.Lexis, summary.Lexis, timeScales, timeBand, entry, exit, 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 )
# See how it looks
xcoh

# Define as 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 )
Lcoh

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

# unless you order the levels correctly
( xcoh$Fail <- factor( xcoh$Fail, levels=c("Well","Dead") ) )
Lexis( entry = list( per=entry ),
        exit = list( per=exit, age=exit-birth ),
 exit.status = Fail,
        data = xcoh )