cutLexis {Epi} | R Documentation |
Follow-up intervals in a Lexis object are divided into two sub-intervals: one before and one after an intermediate event. The intermediate event may denote a change of state, in which case the entry and exit status variables in the split Lexis object are modified.
cutLexis(data, cut, timescale = 1, new.state, progressive=FALSE, precursor.states=NULL, count=FALSE) countLexis(data, cut, timescale = 1)
data |
A Lexis object. |
cut |
A numeric vector with the times of the intermediate event.
If a time is missing (NA ) then the event is assumed to occur
at time Inf . cut can also be a dataframe, see details. |
timescale |
The timescale that cut refers to. |
new.state |
an optional vector, to be used when the cut point
denotes a change of state. This may be a single value, which is
applied to all rows of data , or a vector with a separate
value for each row |
progressive |
a logical flag that determines the changes to exit status. See Details below |
precursor.states |
an optional vector of states to be considered
as "less severe" than new.state . See Details below |
count |
logical indicating wheter the countLexis options should
be used. Specifying count=TRUE amounts to calling countLexis ,
and the arguments new.state , progressive and
precursor.states will be ignored. |
The cutLexis
function allows a number of different ways
of specifying the cutpoints and of modifying the status variable.
If the cut
argument is a dataframe it must have columns lex.id
,
cut
and new.state
. The values of lex.id
must be unique.
In this case it is assumed that each row represents a cutpoint (on the
timescale indicated innthe arument timescale
). This cutpoint will
be applied to all records in data
with the corresponding lex.id
.
This makes it possible to apply cutLexis
to a split Lexis
object.
If the new.state
argument is omitted, then the subject is
assumed to remain in the entry state. In this case, if an interval
is split, the entry status is carried forward to the cut point.
If a new.state
argument is supplied then, by default, the
status variable is only modified at the time of the cut
point. However, it is often useful to modify the status variable after
the cutpoint when an important event occurs. There are three distinct
ways of doing this.
If the progressive=TRUE
argument is given, then a "progressive"
model is assumed, in which the status can either remain the same or
increase during follow-up, but never decrease. In this case, if
new.state=X
, then any exit status with a value less than
X
is replaced with X
. This argument may only be used if
the status variable is numeric or an ordered factor. The Lexis object
must already be progressive, so that there are no rows for which the
exit status is less than the entry status. If lex.Cst
and
lex.Xst
are factors they must be ordered factors if
progressive=TRUE
is given.
As an alternative to the progressive
argument, an explicit
vector of precursor states, that are considered less severe than the
new state, may be given. If new.state=X
and
precursor.states=c(Y,Z)
then any exit status of Y
or
Z
in the second interval is replaced with X
and all
other values for the exit status are retained.
The countLexis
function is a variant of cutLexis
when
the cutpoint marks a recurrent event, and the status variable is used
to count the number of events that have occurred. Times given in cut
represent times of new events. Splitting with
countLexis
augments the status variable by 1. If the entry
status is X
and the exit status is Y
before splitting,
then after splitting the entry status is X
, X+1
for
the first and second intervals, respectively, and the exit status is
X+1
, Y+1
respectively.
A Lexis
object, for which each follow-up interval
containing the cut point is split into two rows: one before
and one after the cut point.
The cutLexis
function superficially resembles the
splitLexis
function. However, the splitLexis
function
splits on a vector of common cut-points for all rows of the Lexis
object, whereas the cutLexis
function splits on a single time
point, which may be distinct for each row, and additionally modifies
the status variables.
Bendix Carstensen, Steno Diabetes Center, bxc@steno.dk, Martyn Plummer, IARC, plummer@iarc.fr.
splitLexis
, Lexis
, summary.Lexis
# A small artificial example xx <- Lexis( entry=list(age=c(17,24,33,29),per=c(1920,1933,1930,1929)), duration=c(23,57,12,15), exit.status=c(1,2,1,2) ) xx cut <- c(33,47,29,50) cutLexis(xx, cut, new.state=3, precursor=1) cutLexis(xx, cut, new.state=3, precursor=2) cutLexis(xx, cut, new.state=3, precursor=1:2) # The same as the last example cutLexis(xx, cut, new.state=3) # The same example with a factor status variable yy <- Lexis(entry = list(age=c(17,24,33,29),per=c(1920,1933,1930,1929)), duration = c(23,57,12,15), entry.status = factor(rep("alpha",4), levels=c("alpha","beta","gamma")), exit.status = factor(c("alpha","beta","alpha","beta"), levels=c("alpha","beta","gamma"))) cutLexis(yy,c(33,47,29,50),precursor="alpha",new.state="gamma") cutLexis(yy,c(33,47,29,50),precursor=c("alpha","beta"),new.state="aleph") ## Using a dataframe as cut argument rl <- data.frame( lex.id=1:3, cut=c(19,53,26), timescale="age", new.state=3 ) rl cutLexis( xx, rl ) cutLexis( xx, rl, precursor=1 ) cutLexis( xx, rl, precursor=0:2 ) ## It is immaterial in what order splitting and cutting is done xs <- splitLexis( xx, breaks=seq(0,100,10), time.scale="age" ) xs xsC <- cutLexis(xs, rl, precursor=0 ) xC <- cutLexis( xx, rl, pre=0 ) xC xCs <- splitLexis( xC, breaks=seq(0,100,10), time.scale="age" ) xCs==xsC xCs