R: Create a Lexis object

Lexis {Epi} | R Documentation

## Create a Lexis object

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

### 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 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?

### 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 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.

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.

### 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 (`C`urrent `st`ate), i.e. the state in which the follow up takes place.
`lex.Xst` | Exit status (e`X`it `st`ate), 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`, `addCov.Lexis`, `merge.Lexis`, `subset.Lexis`, `cbind.Lexis`, `rbind.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
    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 )
    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 )

[Package Epi version 2.37 Index]