mlefrailty.fit            package:survrec            R Documentation

_S_u_r_v_i_v_a_l _f_u_n_c_t_i_o_n _e_s_t_i_m_a_t_o_r _f_o_r _c_o_r_r_e_l_a_t_e_d _r_e_c_u_r_r_e_n_c_e _t_i_m_e _d_a_t_a 
_u_n_d_e_r _a _G_a_m_m_a _F_r_a_i_l_t_y _M_o_d_e_l

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

     Estimation of survival function for correlated recurrence time
     data under a Gamma Frailty model using the maximum likelihood
     criterion.  The resulting object of class "survfitr" is plotted by
     `plot.survfitr', before it is returned.

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

     mlefrailty.fit(x,tvals, lambda=NULL, alpha=NULL, alpha.min, alpha.max, 
     tol=1e-07, maxiter=500,alpha.console=TRUE)

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

       x: a survival recurrent event object.

   tvals: vector of times where the survival function can be estimated. 

  lambda: optional vector  of baseline hazard probabilities at t (see
          details). Default is numdeaths/apply(AtRisk,2,sum).

   alpha: optional parameter of shape and scale for the frailty
          distribution. If this  parameter is unknown is estimate via
          EM algorithm. In order to obtain the  convergence of this
          algorithm a seed is calculated (see details).

alpha.min: optional left bound of the alpha parameter in order to
          obtain a seed to  estimate alpha parameter. Default value is
          0.5.

alpha.max: optional rigth bound of the alpha parameter in order to
          obtain a seed to  estimate alpha  parameter. Default value is
          the maximum of distinct times  of events.

     tol: 

 maxiter: optional maximum number of iterations of the EM algorithm
          used to estimate  the alpha parameter. Default is 500. 

alpha.console: if TRUE prints in the console the estimates initial
          value for alpha and the alpha estimate via the EM algorithm,
          if FALSE not.

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

     The product limit estimator developed by Pea, Strawderman and
     Hollander (2001) are valid when the interoccurrence times are
     assumed to represent an IID sample from  some underlying
     distribution F. This assumption is clearly restrictive in
     biomedical applications, and one obvious generalization that
     allows association between interocurrence times is a frailty
     model. 

     A common and convenient choice of frailty distribution is a gamma
     distribution with shape and scale parameters set equal to an
     unknown parameter alpha. The common marginal survival function can
     be written as following


               1-F(t)=(alpha/(alpha+Lambda_0(t))^alpha


     The parameter alpha controls the degree of association between
     interoccurrence  times within a unit. Pea, Strawderman and
     Hollander (2001) showed that the estimation of  alpha and Lambda_0
     can be obtained via the maximisation of the marginal likelihood
     function  and the expectation-maximisation (EM) algorithm. For
     details and the theory behind this estimator, please refer to
     Pea, Strawderman and Hollander (2001, JASA). 

     In order to obtain a good convergence, alpha is estimated
     previously. This  estimation is used as a initial value in the EM
     procedure and it's carried out by the  maximisation of the profile
     likelihood for alpha. In this case the arguments  of
     *mlefrailty.fit* function called alpha.min and alpha.max are the
     boundaries  of this maximisation. The maximum is obtained using
     the golden section search method.

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

     If the convergence of EM algorithm is not obtained, the initial
     value of alpha can be used as a alpha.min argument and
     recalculate.

       n: number of unit or subjects observed.

       m: vector of number of recurrences in each subject (length n).

  failed: vector of number of recurrences in each subject (length n*m).
           Vector ordered (e.g. times of first unit, times of second
          unit , ..., times of n-unit).

censored: vector of times of censorship for each subject (length n).

numdistinct: number of distinct failures times.

distinct: vector of distinct failures times.

  status: 0 if the estimation is can be provided and 1 if not depending
           if alpha could be estimate or not. 

   alpha: parameter of Gamma Frailty Model.

  lambda: Estimates of the hazard probabilities at distinct failures
          times.

survfunc: vector of survival estimated in distinct times.

   tvals: copy of argument.

MLEAttvals: vector of survival estimated in tvals times.

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

     Pea, E.A., Strawderman, R. and Hollander, M. (2001).
     Nonparametric  Estimation with Recurrent Event Data. _J. Amer.
     Statist. Assoc_  *96*, 1299-1315.

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

     'survfitr' 'Survr'

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

     data(MMC)
     fit<-mlefrailty.fit(Survr(MMC$id,MMC$time,MMC$event))
     fit
     plot(fit)

     # compare with pena-straderman-hollander

     fit<-psh.fit(Survr(MMC$id,MMC$time,MMC$event))
     fit
     lines(fit,lty=2)

     # and with wang-chang

     fit<-wc.fit(Survr(MMC$id,MMC$time,MMC$event))
     fit
     lines(fit,lty=3)

