gcmrec            package:gcmrec            R Documentation(latin1)

_G_e_n_e_r_a_l _C_l_a_s_s _o_f _M_o_d_e_l_s _f_o_r _r_e_c_u_r_r_e_n_t _e_v_e_n_t _d_a_t_a

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

     Fits the parameters for the general semiparametric model for
     recurrent events proposed by Pea and Hollander (2004). This class
     of models incorporates an effective age function which encodes the
     changes that occur after each event occurrence such as the impact
     of an intervention, it allows for the modeling of the impact of
     accumulating event occurrences on the unit, it admits a link
     function in which the effect of possibly time-dependent covariates
     are incorporated, and it allows the incorporation of unobservable
     frailty components which induce dependencies among the inter-event
     times for each unit.

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

     gcmrec(formula, data, effageData = NULL, s, Frailty = FALSE, 
         alphaSeed, betaSeed, xiSeed, tol = 10^(-6), maxit = 100, 
         rhoFunc = "alpha to k", typeEffage = "perfect", 
         maxXi = "Newton-Raphson", se = "Information matrix", 
         cancer = NULL)

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

 formula: A formula object. If a formula object is supplied it must
          have a Survr object as the response on the left of the '~'
          operator and a term on the right. Covariates are needed.

    data: A data frame in which to interpret the variables named  in
          the formula. This data frame must contain the variables
          called "id","time" and "event" for subject identification,
          time of interocurrence, and censored status (coded 1: event,
          0:censored), respectively. Furthermore, we can have some
          covariates. 

          Alternatively, it can also be a list containing the elements
          "n" and "subjects". Number of  subjects must be recorded in
          "n". The element "subject" must have the  following elements:
          subj, k, tau, caltimes, gaptimes,  intercepts, slopes,
          lastperrep, perrepind, effage, effagebegin,  and covariate
          including this information:


          _s_u_b_j: Subject number or identificator. 

          _k: Number of recurrences (time 0 must be included). 

          _t_a_u: Administrative time, time of study termination. 

          _c_a_l_t_i_m_e_s: Calendar times at each recurrence (time 0 must be
               included).  

          _g_a_p_t_i_m_e_s: Gap times at each recurrence (time 0 must be
               included). 

          _i_n_t_e_r_c_e_p_t_s: Intercept value for the effect after each
               recurrence. 

          _s_l_o_p_e_s: Slope value for the effect after each each
               recurrence.             

          _l_a_s_t_p_e_r_r_e_p: Element from Brown and Proschan minimal repair
               model. 

          _p_e_r_r_e_p_i_n_d: Element from Brown and Proschan minimal repair
               model. 

          _e_f_f_a_g_e_b_e_g_i_n: Initial value for effective age. 

          _e_f_f_a_g_e: Effective age after each recurrence. 

          _c_o_v_a_r_i_a_t_e: covariate value at each recurrence.

          See either GeneratedData or hydraulic data sets as an
          example.   

effageData: List containing the information about effective age. The
          list must have  the elements described in the option 2 of
          data argument. If NULL we  generate these elements under
          perfect repair model or minimal repair one depending on the 
          'typeEffage' argument (see below).    

       s: A selected calendar time. 

 Frailty: Logical value. Is model with frailties fitted? If so
          parameters for General  Class of Models with frailty
          component are estimated.  

alphaSeed: Seed value for alpha. 

betaSeed: Seed value for beta. 

  xiSeed: Seed value for xi. 

     tol: Tolerance for maximization procedures. 

   maxit: Maximum number of iterations in maximization procedures.

 rhoFunc: A character string specifying the effects attributable to the
           accumulating event occurrences, rho(k;alpha). Possible
          values are "Identity" for rho(k;alpha)=1 or "alpha to k" for
          rho(k;alpha)=alpha^k. The default is "alpha to k". Only the
          first words  are required, e.g "Id","a". Future versions will
          include other functions such as Markovian model for tumor
          occurrences, rho(k;alpha)=alpha-k+1 proposed by Gail et al.
          (1980).

typeEffage: Effective age function. Possible value are "perfect" or
          "minimal" for perfect repair model or minimal repair model,
          respectively. The default is "perfect". Only the first words
          are required, e.g "p","m"

   maxXi: Maximization method for marginal likelihood with respect to
          xi. Possible values are "Newton-Raphson" for Newton-Raphson
          maximization  procedure or "Brent" for Brent's method
          maximization in one dimension.  The default value is
          "Newton-Raphson". Only the first words are required, e.g.
          "N","B"

      se: Standard errors of parameters. Possible values are
          'Information matrix' or 'Jacknife' for inverse of the partial
           likelihood information matrix or jacnife estimates,
          respectively.

  cancer: Effective age for fitting a cancer model proposed by Gonzalez
          et al (2005). This variable contains the information of the
          effect of treatments administred after cancer relapses coded
          as "CR", "PR" or "SD" depending on if complete, partial, or
          null response (stable disease) is achieved. See lymphoma data
          set as an example. 

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

     Estimation with frailties are implemented using
     expectation-maximization (EM) algorithm. In this procedure, we
     need to maximize the marginal likelihood with respect to xi. This
     maximization is a one-dimensional maximization without
     derivarives. First we bracket the  maximizing value, and the we
     obtain it using Brent's method in one dimension. When we implement
      this algorithm, we re-parameterize xi using xi*=log(xi) to
     alleviate the problem of getting negative estimates for xi.
     Iteration is terminated when successive values of xi/(1+xi) differ
     by no more than the "tol" parameter. Maybe estimation under
     frailty  model can be not too fast.

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

     a gcmrec object. Methods defined for gcmrec objects are provided
     for print and plot.

_R_e_f_e_r_e_n_c_e_s:

     Pe\~na, E. and M. Hollander (2004). Mathematical Reliability: An
     Expository Perspective, Chapter 6. Models for Recurrent Events in
     Reliability and Survival Analysis, pp. 105-123. Kluwer Academic
     Publishers.

     M. Gail, T Santner, and C Brown (1980). An analysis of comparative
     carfinogenesis  experiments based on multiple times to tumor.
     _Biometrics_ *36*, 255-266.          

     JR Gonzalez, E Pea, E Slate (2005). Modelling treatment effect
     after cancer relapses, with application to recurrences in indolent
     non-Hodgkin's lymphomas. _Stat Med_, submitted.

     R. Brent. _Algorithms for Minimization Without Derivatives_.
     Prentice-Hall, New York, 1973.

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

     ###################################
     ## Models using different data formats
     ###################################

     #
     #    Data input as a data frame
     #

     #   We use the well-known bladder cancer data set from survival package

     library(survival)
     data(bladder)

     # we compute the interocurrence time
     bladder2$time<-bladder2$stop-bladder2$start

     # If we execute:
     #     gcmrec(Survr(id,time,event)~rx+size+number,data=bladder2,s=2060)

     # We will obtain the following error message:
     #   Error in Survr(id, time, event) : Data doesn't match...

     # This means that we have some patients without right-censoring time. So,
     # we understand that the last event coincides with the end of study. 
     # Consequently,we need to add a line with time 0 and status value equal 
     # to 0, too. To do so, we can use the function "addCenTime" as follows:

     bladderOK<-addCenTime(bladder2) 

     # Now, we can fit the model using this new data set:

     gcmrec(Survr(id,time,event)~rx+size+number,data=bladderOK,s=2060)


     #
     #    Data as a list. See either GeneratedData or hydraulic data 
     #                    sets as an example.
     #

     #
     # We can fit the model by transforming our data in a data frame 
     # using "List.to.Dataframe" function:
     #

     data(hydraulic)
     hydraulicOK<-List.to.Dataframe(hydraulic)
     gcmrec(Survr(id,time,event)~covar.1+covar.2,data=hydraulicOK,s=4753)


     #
     # Our model allows us to incorporate effective age information
     #
     # To illustrate this example, we will use a simulated data set generated 
     # under the minimal repair model with probability of perfect repair equal to 0.6
     #
     # As we have the data in a list, first we need to obtain a data frame containing
     # the time, event, and covariates information:
     #

     data(GeneratedData)
     temp<-List.to.Dataframe(GeneratedData)

     # then, we can fit the model incorporating the information about the effective 
     #        age in the effageData argument:

     gcmrec(Survr(id,time,event)~covar.1+covar.2, data=temp, 
                         effageData=GeneratedData, s=100)



     #####################################################################
     ##  How to fit minimal or perfect repair models, with and without frailties
     #####################################################################

     # Model with frailties 

     mod.Fra<-gcmrec(Survr(id,time,event)~rx+size+number,data=bladderOK,s=2060,Frailty=TRUE)
     print(mod.Fra)

     # effective age function: perfect repair and minimal repair models 
     # (models without frailties)

     data(readmission)

     # perfect
     mod.per<-gcmrec(Survr(id,time,event)~as.factor(dukes),data=readmission,
         s=3000,typeEffage="per")
     print(mod.per)

     # minimal
     mod.min<-gcmrec(Survr(id,time,event)~as.factor(dukes),data=readmission,
        s=3000,typeEffage="min")
     print(mod.min)

     #####################################################################
     ##  How to fit models with \rho function equal to identity 
     #####################################################################

     data(lymphoma)

     gcmrec(Survr(id, time, event) ~ as.factor(distrib), 
         data = lymphoma, s = 1000, Frailty = TRUE, rhoFunc = "Ident")

     #####################################################################
     ##  How to fit cancer model
     #####################################################################

     mod.can<-gcmrec(Survr(id,time,event)~as.factor(distrib), data=lymphoma,
          s=1000, Frailty=TRUE,  cancer=lymphoma$effage)

     #  standard errors can be obtained by adding se="Jacknife".
     # This procedure can be very time consuming

      

