cutLexis {Epi}R Documentation

Cut follow-up at a specified date for each person.

Description

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.

Usage

  cutLexis(data, cut, timescale = 1, new.state, progressive=FALSE,
           precursor.states=NULL, count=FALSE)
  countLexis(data, cut, timescale = 1)

Arguments

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.

Details

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.

Value

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.

Note

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.

Author(s)

Bendix Carstensen, Steno Diabetes Center, bxc@steno.dk, Martyn Plummer, IARC, plummer@iarc.fr.

See Also

splitLexis, Lexis, summary.Lexis

Examples

# 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

[Package Epi version 1.0.12 Index]