Lexis                  package:Epi                  R Documentation

_C_r_e_a_t_e _a _L_e_x_i_s _o_b_j_e_c_t

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

     Create an object of class 'Lexis' to represent follow-up on
     multiple time scales.

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

     Lexis(entry, exit, duration, entry.status = 0, exit.status = 0, id, data,
           merge=TRUE, states )

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

   entry: a named list of entry times. Each element of the list is a
          numeric variable representing the entry time on the named
          time scale. All time scales must have the same units (e.g.
          years).

    exit: a named list of exit times.

duration: a numeric vector giving the duration of follow-up.

entry.status: a vector or a factor giving the status at entry

exit.status: a vector or factor giving status at exit. Any change in
          status during follow-up is assumed to take place exactly at
          the exit time.

      id: a vector giving a unique identity value for each row of the
          Lexis object.

    data: an optional data frame, list, or environment containing the
          variables. If  not found in 'data', the variables are taken
          from the environment from which 'Lexis' was called.

   merge: a logical flag. If 'TRUE' then the 'data'  argument will be
          coerced to a data frame and then merged with the resulting
          'Lexis' object.

  states: A vector of labels for the states. If given, the state
          variables 'lex.Cst' and 'lex.Xst' are returned as factors
          with identical levels attributes.

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

     The analysis of long-term population-based follow-up studies
     typically requires multiple time scales to be taken into account,
     such as age, calender time, or time since an event. A 'Lexis'
     object is a data frame with additional attributes that allows
     these multiple time dimensions of follow-up to be managed.

     Separate variables for current end exit state allows
     representation of multistate data.

     Lexis objects are named after the German demographer Wilhelm Lexis
     (1837-1914), who is credited with the invention of the "Lexis
     diagram" for representing population dynamics simultaneously by
     age, period and cohort.

     The 'Lexis' function creates a minimal 'Lexis' object with only
     those variables required to define the follow-up history in each
     row. Additional variables can be merged into the 'Lexis' object
     using the 'merge' method for 'Lexis' objects. This is the default.

     There are also 'merge', 'subset' and 'transform' methods for
     'Lexis' objects. They work as the corresponding methods for
     data-frames but ensures that the result is a 'Lexis' object.

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

     An object of class 'Lexis'. This is represented as a data frame
     with a column for each time scale, and additional columns with the
     following names: 

  lex.id: Identification of the inidvidual

 lex.dur: Duration of follow-up

 lex.Cst: Entry status (Current state), i.e. the state in which the
          follow up takes place.

 lex.Xst: Exit status (eXit state), i.e. that state taken up after
          'dur' in 'lex.Cst'.

     If 'merge=TRUE' then the 'Lexis' object will also contain all
     variables from the 'data' argument.

_N_o_t_e:

     Only two of the three arguments 'entry', 'exit' and 'duration'
     need to be given.  If the third parameter is missing, it is
     imputed. If duration is given, it must be the same on all time
     scales.

     'entry', 'exit' must be numeric, using  'Date' variables will
     cause some of the utilites to crash. Transformation by 'cal.yr' is
     recommended.

     If only either 'exit' or 'duration' are supplied it is assumed
     that 'entry' is 0. This is only meaningful (and therefore checked)
     if there is only one timescale.

     If any of 'entry.status' or 'exit.status' are of mode character,
     they will both be converted to factors.

     If 'entry.status' is not given, then its class is automatically
     set to that of 'exit.status'. If 'exit.status' is factor, the
     value of 'entry.status' is set to the first level. This may be
     highly undesirable, and therefore noted. For example, if
     'exit.status' is character the first level will be the first in
     the alphabetical ordering; slightly unfortunate if values are
     'c("Well","Diseased")'. If 'exit.status' is logical, the value of
     'entry.status' set to 'FALSE'.

     If 'entry.status' or 'exit.status' are factors or character, the
     corresponding state variables in the returned 'Lexis' object,
     'lex.Cst' and 'lex.Xst' will be (unordered) factors with identical
     levels, namely the union of the levels of 'entry.status' and
     'exit.status'.

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

     Martyn Plummer

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

     'plot.Lexis', 'splitLexis', 'cutLexis', 'merge.Lexis',
     'subset.Lexis', 'transform.Lexis', 'summary.Lexis', 'timeScales',
     'timeBand', 'entry', 'exit', 'dur'

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

     # A small bogus cohort
     xcoh <- structure( list( id = c("A", "B", "C"),
                           birth = c("14/07/1952", "01/04/1954", "10/06/1987"),
                           entry = c("04/08/1965", "08/09/1972", "23/12/1991"),
                            exit = c("27/06/1997", "23/05/1995", "24/07/1998"),
                            fail = c(1, 0, 1) ),
                          .Names = c("id", "birth", "entry", "exit", "fail"),
                       row.names = c("1", "2", "3"),
                           class = "data.frame" )

     # Convert the character dates into numerical variables (fractional years)
     xcoh$bt <- cal.yr( xcoh$birth, format="%d/%m/%Y" )
     xcoh$en <- cal.yr( xcoh$entry, format="%d/%m/%Y" )
     xcoh$ex <- cal.yr( xcoh$exit , format="%d/%m/%Y" )

     # See how it looks
     xcoh

     # Define as Lexis object with timescales calendar time and age
     Lcoh <- Lexis( entry = list( per=en ),
                     exit = list( per=ex, age=ex-bt ),
              exit.status = fail,
                     data = xcoh )
     Lcoh

     # Using character states may have undesired effects:
     xcoh$Fail <- c("Dead","Well","Dead")
     Lexis( entry = list( per=en ),
             exit = list( per=ex, age=ex-bt ),
      exit.status = Fail,
             data = xcoh )

     # unless you order the levels correctly
     ( xcoh$Fail <- factor( xcoh$Fail, levels=c("Well","Dead") ) )
     Lexis( entry = list( per=en ),
             exit = list( per=ex, age=ex-bt ),
      exit.status = Fail,
             data = xcoh )

