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

Description Usage Arguments Details Value Note Author(s) See Also Examples

View source: R/cutLexis.R

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

1
2
3
4
5
6
7
8
cutLexis( data, cut, timescale = 1,
                     new.state = nlevels(data$lex.Cst)+1,
                     new.scale = FALSE,
                  split.states = FALSE,
                   progressive = FALSE,
              precursor.states = transient(data),
                         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. Any record representing follow up after the cutpoint has its value of lex.Cst updated to the new state. An extra time-scale is added; the time since the event at cut. This time scake will beNA 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 intermediate state are used in modeling. But you do not want to do that permanently in the cut data frame.

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, martyn.plummer@r-project.org

See Also

mcutLexis, rcutLexis, addCov.Lexis, splitLexis, Lexis, summary.Lexis, timeSince, boxes.Lexis

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# 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)

Example output

NOTE: entry.status has been set to 0 for all.
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920      23       0       1      1
2  24 1933      57       0       2      2
3  33 1930      12       0       1      3
4  29 1929      15       0       2      4
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920      16       0       3      1
5  33 1936       7       3       3      1
2  24 1933      23       0       3      2
6  47 1956      34       3       2      2
7  33 1930      12       3       3      3
4  29 1929      15       0       2      4
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920      16       0       3      1
5  33 1936       7       3       1      1
2  24 1933      23       0       3      2
6  47 1956      34       3       3      2
7  33 1930      12       3       1      3
4  29 1929      15       0       2      4
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920      16       0       3      1
5  33 1936       7       3       3      1
2  24 1933      23       0       3      2
6  47 1956      34       3       3      2
7  33 1930      12       3       3      3
4  29 1929      15       0       2      4
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920      16       0       3      1
5  33 1936       7       3       1      1
2  24 1933      23       0       3      2
6  47 1956      34       3       2      2
7  33 1930      12       3       1      3
4  29 1929      15       0       2      4
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920      16   alpha   gamma      1
5  33 1936       7   gamma   gamma      1
2  24 1933      23   alpha   gamma      2
6  47 1956      34   gamma    beta      2
7  33 1930      12   gamma   gamma      3
4  29 1929      15   alpha    beta      4
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920      16   alpha   aleph      1
5  33 1936       7   aleph   aleph      1
2  24 1933      23   alpha   aleph      2
6  47 1956      34   aleph   aleph      2
7  33 1930      12   aleph   aleph      3
4  29 1929      15   alpha    beta      4
  lex.id cut timescale new.state
1      1  19       age         3
2      2  53       age         3
3      3  26       age         3
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920       2       0       3      1
5  19 1922      21       3       1      1
2  24 1933      29       0       3      2
6  53 1962      28       3       2      2
7  33 1930      12       3       1      3
4  29 1929      15       0       2      4
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920       2       0       3      1
5  19 1922      21       3       3      1
2  24 1933      29       0       3      2
6  53 1962      28       3       2      2
7  33 1930      12       3       3      3
4  29 1929      15       0       2      4
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920       2       0       3      1
5  19 1922      21       3       3      1
2  24 1933      29       0       3      2
6  53 1962      28       3       3      2
7  33 1930      12       3       3      3
4  29 1929      15       0       2      4
   lex.id age  per lex.dur lex.Cst lex.Xst
1       1  17 1920       3       0       0
2       1  20 1923      10       0       0
3       1  30 1933      10       0       1
4       2  24 1933       6       0       0
5       2  30 1939      10       0       0
6       2  40 1949      10       0       0
7       2  50 1959      10       0       0
8       2  60 1969      10       0       0
9       2  70 1979      10       0       0
10      2  80 1989       1       0       2
11      3  33 1930       7       0       0
12      3  40 1937       5       0       1
13      4  29 1929       1       0       0
14      4  30 1930      10       0       0
15      4  40 1940       4       0       2
  age  per lex.dur lex.Cst lex.Xst lex.id
1  17 1920       2       0       3      1
5  19 1922      21       3       1      1
2  24 1933      29       0       3      2
6  53 1962      28       3       2      2
7  33 1930      12       3       1      3
4  29 1929      15       0       2      4
   lex.id age  per lex.dur lex.Cst lex.Xst
1       1  17 1920       2       0       3
2       1  19 1922       1       3       3
3       1  20 1923      10       3       3
4       1  30 1933      10       3       1
5       2  24 1933       6       0       0
6       2  30 1939      10       0       0
7       2  40 1949      10       0       0
8       2  50 1959       3       0       3
9       2  53 1962       7       3       3
10      2  60 1969      10       3       3
11      2  70 1979      10       3       3
12      2  80 1989       1       3       2
13      3  33 1930       7       3       3
14      3  40 1937       5       3       1
15      4  29 1929       1       0       0
16      4  30 1930      10       0       0
17      4  40 1940       4       0       2
Classes 'Lexis' and 'data.frame':	17 obs. of  6 variables:
 $ lex.id : int  1 1 1 1 2 2 2 2 2 2 ...
 $ age    : num  17 19 20 30 24 30 40 50 53 60 ...
 $ per    : num  1920 1922 1923 1933 1933 ...
 $ lex.dur: num  2 1 10 10 6 10 10 3 7 10 ...
 $ lex.Cst: num  0 3 3 3 0 0 0 0 3 3 ...
 $ lex.Xst: num  3 3 3 1 0 0 0 3 3 3 ...
 - attr(*, "breaks")=List of 2
  ..$ age: num  0 10 20 30 40 50 60 70 80 90 ...
  ..$ per: NULL
 - attr(*, "time.scales")= chr  "age" "per"
 - attr(*, "time.since")= chr  "" ""

Epi documentation built on Feb. 28, 2021, 1:06 a.m.

Related to cutLexis in Epi...