cutLexis                 package:Epi                 R Documentation

_C_u_t _f_o_l_l_o_w-_u_p _a_t _a _s_p_e_c_i_f_i_e_d _d_a_t_e _f_o_r _e_a_c_h _p_e_r_s_o_n.

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

    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. 

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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.

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

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

_S_e_e _A_l_s_o:

     'splitLexis', 'Lexis', 'summary.Lexis'

_E_x_a_m_p_l_e_s:

     # 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

