Lexis {Epi} | R Documentation |
Create an object of class Lexis
to represent follow-up on
multiple time scales.
Lexis(entry, exit, duration, entry.status = 0, exit.status = 0, id, data, merge=TRUE, states )
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). |
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. |
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 age, period and cohort.
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.
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.
Only two of the three arguments entry
, exit
and
duration
need to be given. If the third parameter is missing,
it is imputed. If duration is given, it must be the same on
all time scales.
entry
, exit
must be numeric, using Date
variables will cause some of the utilites 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 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 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 levels, namely the union of the levels
of entry.status
and exit.status
.
Martyn Plummer
plot.Lexis
,
splitLexis
,
cutLexis
,
merge.Lexis
,
subset.Lexis
,
transform.Lexis
,
summary.Lexis
,
timeScales
,
timeBand
,
entry
,
exit
,
dur
# 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$bt <- cal.yr( xcoh$birth, format="%d/%m/%Y" ) xcoh$en <- cal.yr( xcoh$entry, format="%d/%m/%Y" ) xcoh$ex <- cal.yr( xcoh$exit , format="%d/%m/%Y" ) # See how it looks xcoh # 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 = fail, data = xcoh ) Lcoh # Using character states may have undesired effects: xcoh$Fail <- c("Dead","Well","Dead") Lexis( entry = list( per=en ), exit = list( per=ex, age=ex-bt ), exit.status = Fail, data = xcoh ) # unless you order the levels correctly ( xcoh$Fail <- factor( xcoh$Fail, levels=c("Well","Dead") ) ) Lexis( entry = list( per=en ), exit = list( per=ex, age=ex-bt ), exit.status = Fail, data = xcoh )