frailty               package:survival               R Documentation

_R_a_n_d_o_m _e_f_f_e_c_t_s _t_e_r_m_s

_D_e_s_c_r_i_p_t_i_o_n:

     The frailty function allows one to add a simple random effects
     term to a Cox or survreg model.

_U_s_a_g_e:

     frailty(x, distribution="gamma", ...)
     frailty.gamma(x, sparse = (nclass > 5), theta, df, eps = 1e-05, method = c("em","aic", "df", "fixed"), ...) 
     frailty.gaussian(x, sparse = (nclass > 5), theta, df, method =c("reml","aic", "df", "fixed"), ...)
     frailty.t(x, sparse = (nclass > 5), theta, df, eps = 1e-05, tdf = 5,method = c("aic", "df", "fixed"), ...)

_A_r_g_u_m_e_n_t_s:

       x: the variable to be entered as a random effect.   It is always
          treated as a factor. 

distribution: either the 'gamma',  'gaussian' or 't' distribution may
          be specified. The routines 'frailty.gamma',
          'frailty.gaussian' and  'frailty.t' do the actual work. 

     ...: Arguments for specific distribution, including (but not
          limited to) 

  sparse: cutoff for using a sparse coding of the data matrix.   If the
          total number of levels of 'x' is larger than this value, then
          a sparse matrix approximation is used. The correct cutoff is
          still a matter of exploration: if the number of levels is
          very large (thousands) then the non-sparse calculation may
          not be feasable in terms of both memory and compute time.  
          Likewise, the accuracy of the sparse approximation appears to
          be related to the maximum proportion of subjects in any one
          class, being best when no one class has a large membership. 

   theta: if specified, this fixes the variance of the random effect.
          If not, the variance is a parameter, and a best solution is
          sought. Specifying this implies 'method='fixed''. 

      df: if specified, this fixes the degrees of freedom for the
          random effect. Specifying this implies 'method='df''. Only
          one of 'theta' or  'df' should be specified. 

  method: the method used to select a solution for theta, the variance
          of the random effect.   The 'fixed' corresponds to a
          user-specified value, and no iteration is done. The 'df'
          selects the variance such that the degrees of freedom for the
          random effect matches a user specified value. The 'aic'
          method seeks to  maximize Akiake's information criteria 
          2*(partial likelihood - df). The 'ml' and 'reml' methods are
          specific to Cox models with gamma and gaussian random
          effects, respectively. Please see further discussion below. 

     tdf: the degrees of freedom for the t-distribution. 

     eps: convergence critera for the iteration on theta. 

_D_e_t_a_i_l_s:

     The 'frailty' plugs into the general penalized modeling framework
     provided by the 'coxph'  and 'survreg' routines.   This framework
     deals with likelihood, penalties, and degrees of freedom; these
     aspects work well with either parent routine.

     Therneau, Grambsch, and Pankratz show how maximum likelihood
     estimation for the Cox model with a gamma frailty can be
     accomplished using a general penalized routine, and Ripatti and
     Palmgren work through a similar argument for the Cox model with a
     gaussian frailty.  Both of these are specific to the Cox model.  
     Use of gamma/ml or gaussian/reml with  'survreg' does not lead to
     valid results. 

     The extensible structure of the penalized methods is such that the
     penalty function, such as 'frailty' or 'pspine', is completely
     separate from the modeling routine.  The strength of this is that
     a user can plug in any penalization routine they choose.  A
     weakness is that it is very difficult for the modeling routine to
     know whether a sensible penalty routine has been supplied.

_V_a_l_u_e:

     this function is used in the model statment of either 'coxph' or
     'survreg'. It's results are used internally.

_R_e_f_e_r_e_n_c_e_s:

     S Ripatti and J Palmgren, Estimation of multivariate frailty 
     models using penalized partial likelihood, Biometrics,
     56:1016-1022, 2000.

     T Therneau, P Grambsch and VS Pankratz, Penalized survival models
     and frailty, J Computational and Graphical Statistics, 12:156-175,
     2003.

_S_e_e _A_l_s_o:

     coxph, survreg, coxme

_E_x_a_m_p_l_e_s:

     # Random institutional effect
     coxph(Surv(time, status) ~ age + frailty(inst, df=4), lung)

     # Litter effects for the rats data
     rfit2a <- survreg(Surv(time, status) ~ rx +
                       frailty.gaussian(litter, df=13, sparse=FALSE), rats )
     rfit2b <- survreg(Surv(time, status) ~ rx +
                       frailty.gaussian(litter, df=13, sparse=TRUE), rats )