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

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 = nlevels(data$lex.Cst)+1,
                         new.scale = FALSE,
                      split.states = FALSE,
                       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. Numeric or character.
`new.state` | The state to which a transition occur at time `cut`. It may be a single value, which is then applied to all rows of `data`, or a vector with a separate value for each row
`new.scale` | Name of the timescale defined as "time since entry to new.state". If `TRUE` a name for the new scale is constructed. See details.
`split.states` | Should states that are not precursor states be split according to whether the intermediate event has occurred.
`progressive` | a logical flag that determines the changes to exit status. See details.
`precursor.states` | an optional vector of states to be considered as "less severe" than `new.state`. See Details below
`count` | logical indicating whether the `countLexis` options should be used. Specifying `count=TRUE` amounts to calling `countLexis`, in which case 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 in the argument `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 a `new.state` argument is supplied, 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. This assumes that the state variables `lex.Cst` and `lex.Xst` are either numeric or ordered factors. In this case, if `new.state=X`, then any exit status with a value less than `X` is replaced with `X`. 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` increases the status variable by 1. If the current status is `X` and the exit status is `Y` before cutting, then after cutting the entry status is `X`, `X+1` for the first and second intervals, respectively, and the exit status is `X+1`, `Y+1` respectively. Moreover the values of the status is increased by 1 for all intervals for all intervals after the cut for the person in question. Hence, a call to `countLexis` is needed for as many times as the person with most events. But also it is immaterial in what order the cutpoints are entered.

### Value

A `Lexis` object, for which each follow-up interval containing the cutpoint is split in two: one before and one after the cutpoint. An extra time-scale is added; the time since the event at `cut`. This is `NA` for any follow-up prior to the intermediate event.

The function `tsNA20` will replace all missing values in timescales with 0. This is commonly meeded when timescales defined as time since entry into an inermediate state are used in modeling.

### 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, modifies the status variables, adds a new timescale and updates the attribute "time.since". This attribute is a character vector of the same length as the "time.scales" attribute, whose value is '""' if the corresponding timescale is defined for any piece of follow-up, and if the corresponding time scale is defined by say `cutLexis(obj,new.state="A",new.scale=TRUE)`, it has the value "A".

### Author(s)

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

### See Also

`mcutLexis`, `addCov.Lexis`, `splitLexis`, `Lexis`, `summary.Lexis`, `timeSince`, `boxes.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
    str(xCs)

[Package Epi version 2.37 Index]