kalsurv                package:event                R Documentation

_R_e_p_e_a_t_e_d _E_v_e_n_t_s _M_o_d_e_l_s _w_i_t_h _F_r_a_i_l_t_y _o_r _S_e_r_i_a_l _D_e_p_e_n_d_e_n_c_e

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

     'kalsurv' is designed to handle event history models with
     time-varying covariates. The distributions have two extra
     parameters as compared to the functions specified by 'intensity'
     and are generally longer tailed than those distributions.
     Dependence of inter-event times can be through gamma frailties (a
     type of random effect), with or without autoregression, or several
     kinds of serial dependence by updating, as in Kalman filtering.

     By default, a gamma mixture of the distribution specified in
     'intensity' is used, as the conditional distribution in the
     'serial' dependence models, and as a symmetric multivariate
     (random effect) model for 'frailty' dependence. For example, with
     a Weibull 'intensity' and 'frailty' dependence, this yields a
     multivariate Burr distribution and with 'Markov' or 'serial'
     dependence, univariate Burr conditional distributions.

     If a value for 'pfamily' is used, the gamma mixture is replaced by
     a power variance family mixture.

     Nonlinear regression models can be supplied as formulae where
     parameters are unknowns in which case factor variables cannot be
     used and parameters must be scalars. (See 'finterp'.)

     Marginal and individual profiles can be plotted using 'mprofile'
     and 'iprofile' and residuals with 'plot.residuals'.

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

     kalsurv(response, intensity="exponential", distribution="Pareto",
             depend="independence", update="Markov", mu=NULL, shape=NULL,
             renewal=TRUE, density=FALSE, censor=NULL, delta=NULL, ccov=NULL,
             tvcov=NULL, preg=1, ptvc=NULL, pbirth=NULL,
             pintercept=NULL, pshape=NULL, pinitial=1, pdepend=NULL,
             pfamily=NULL, envir=parent.frame(), print.level=0,
             ndigit=10, gradtol=0.00001, steptol=0.00001, iterlim=100,
             fscale=1, typsiz=abs(p), stepmax=10*sqrt(p%*%p))

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

response: A list of vectors with times between events for each
          individual, one matrix or dataframe of such times if all
          individuals have the same number of events, or an object of
          class, 'response' (created by 'restovec') or 'repeated'
          (created by 'rmna' or 'lvna'). If the 'repeated' data object
          contains more than one response variable, give that object in
          'envir' and give the name of the response variable to be used
          here.

intensity: The form of intensity function to be put in the distribution
          given by dist. Choices are exponential, Weibull, gamma, log
          normal, log logistic, log Cauchy, log Student, and
          gen(eralized) logistic.

distribution: The outer distribution. Choices are Pareto, gamma, and
          Weibull.

  depend: Type of dependence. Choices are 'independence', 'frailty',
          and 'serial'.

  update: Type of update for serial dependence. Choices are 'Markov',
          'elapsed Markov', 'serial', 'event', 'cumulated', 'count',
          and 'kalman'. With 'frailty' dependence, weighting by length
          of observation time may be specified by setting update to
          'time'.

      mu: A regression function for the location parameter or a formula
          beginning with ~, specifying either a linear regression
          function in the Wilkinson and Rogers notation or a general
          function with named unknown parameters. Give the initial
          estimates in 'preg' if there are no time-varying covariates
          and in 'ptvc' if there are.

   shape: A regression function for the shape parameter or a formula
          beginning with ~, specifying either a linear regression
          function in the Wilkinson and Rogers notation or a general
          function with named unknown parameters. It must yield one
          value per observation.

 renewal: IF TRUE, a renewal process is modelled, with time
          reinitialized after each event. Otherwise, time is cumulated
          from the origin of observations.

 density: If TRUE, the density of the function specified in 'intensity'
          is used instead of the intensity.

  censor: A vector of the same length as the number of individuals
          containing a binary indicator, with a one indicating that the
          last time period in the series terminated with an event and
          zero that it was censored. For independence and frailty
          models, where response is matrix, censor may also be a matrix
          of the same size. Ignored if response has class, 'response'
          or 'repeated'.

   delta: Scalar or vector giving the unit of measurement for each
          response value, set to unity by default. For example, if a
          response is measured to two decimals, delta=0.01. If the
          response has been pretransformed, this must be multiplied by
          the Jacobian. This transformation cannot contain unknown
          parameters. For example, with a log transformation,
          'delta=1/y'. (The delta values for the censored response are
          ignored.) Ignored if response has class, 'response' or
          'repeated'.

    ccov: A vector or matrix containing time-constant baseline
          covariates with one entry per individual, a model formula
          using vectors of the same size, or an object of class,
          'tccov' (created by 'tcctomat'). If response has class,
          'repeated', the covariates must be supplied as a Wilkinson
          and Rogers formula unless none are to be used or 'mu' is
          given.

   tvcov: A list of matrices with time-varying covariate values,
          observed at the event times in 'response', for each
          individual (one column per variable), one matrix or dataframe
          of such covariate values, or an object of class, 'tvcov'
          (created by 'tvctomat'). If response has class, 'repeated',
          the covariates must be supplied as a Wilkinson and Rogers
          formula unless none are to be used or 'mu' is given.

    preg: Initial parameter estimates for the regression model:
          intercept plus one for each covariate in 'ccov'. If 'mu' is a
          formula or function, the parameter estimates must be given
          here only if there are no time-varying covariates. If 'mu' is
          a formula with unknown parameters, their estimates must be
          supplied either in their order of appearance in the
          expression or in a named list.

    ptvc: Initial parameter estimates for the coefficients of the
          time-varying covariates, as many as in 'tvcov'. If 'mu' is a
          formula or function, the parameter estimates must be given
          here if there are time-varying covariates present.

  pbirth: If supplied, this is the initial estimate for the coefficient
          of the birth model.

pintercept: The initial estimate of the intercept for the generalized
          logistic intensity.

  pshape: An initial estimate for the shape parameter of the intensity
          (except exponential intensity). If 'shape' is a function or
          formula, the corresponding initial estimates. If 'shape' is a
          formula with unknown parameters, their estimates must be
          supplied either in their order of appearance in the
          expression or in a named list.

pinitial: An initial estimate for the initial parameter. In 'frailty'
          dependence, this is the frailty parameter.

 pdepend: An initial estimate for the serial dependence parameter. For
          'frailty' dependence, if a value is given here, an
          autoregression is fitted as well as the frailty.

 pfamily: An optional initial estimate for the second parameter of a
          two-parameter power variance family mixture instead of the
          default gamma mixture. This yields a gamma mixture as 'family
          -> 0', an inverse Gauss mixture for 'family = 0.5', and a
          compound distribution of a Poisson-distributed number of
          gamma distributions for '-1 < family < 0'.

   envir: Environment in which model formulae are to be interpreted or
          a data object of class, 'repeated', 'tccov', or 'tvcov'; the
          name of the response variable should be given in 'response'.
          If 'response' has class 'repeated', it is used as the
          environment.

  others: Arguments controlling 'nlm'.

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

     A list of classes 'kalsurv' and 'recursive' is returned.

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

     J.K. Lindsey

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

     'coxre', 'finterp', 'gettvc', 'gnlmm', 'gnlr', 'iprofile',
     'kalcount', 'kalseries', 'mprofile', 'nbkal', 'read.list',
     'restovec', 'rmna', 'tcctomat', 'tvctomat'.

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

     treat <- c(0,0,1,1)
     tr <- tcctomat(treat)
     cens <- matrix(rbinom(20,1,0.9),ncol=5)
     times <- # matrix(rweibull(20,2,1+3*rep(treat,5)),ncol=5)
             matrix(c(1.36,0.18,0.84,0.65,1.44,1.79,1.04,0.43,1.35,1.63,2.15,1.15,
                     1.21,5.46,1.58,3.44,4.40,2.75,4.78,2.44),ncol=5,byrow=TRUE)
     times <- restovec(times, censor=cens)
     reps <- rmna(times, ccov=tr)
     # exponential intensity model with independence
     kalsurv(times, pinitial=0.5, preg=1, dep="independence",
             intensity="exponential")
     # Weibull intensity model with independence
     kalsurv(times, pinitial=0.5, preg=1, pshape=1, dep="independence",
             intensity="Weibull")
     # same model with serial update
     kalsurv(times, pinitial=0.5, pdep=0.1, preg=1, pshape=1, dep="serial",
             intensity="Weibull")
     # try power variance family instead of gamma distribution for mixture
     kalsurv(times, pinitial=0.5, pdep=0.1, preg=1, pshape=1, dep="serial",
             intensity="Weibull", pfamily=0.1)
     # treatment effect with log link
     kalsurv(times, pinitial=0.5, preg=c(1,0), pshape=1, intensity="Weibull",
             ccov=treat)
     # or equivalently
     kalsurv(times, mu=~exp(a+b*treat), pinitial=0.1, preg=c(1,0), pshape=1,
             intensity="Weibull", envir=reps)
     # with identity link instead
     kalsurv(times, mu=~treat, pinitial=0.5, preg=c(1,0), pshape=1,
             intensity="Weibull")
     # or equivalently
     kalsurv(times, mu=~a+b*treat, pinitial=0.5, preg=c(1,0), pshape=1,
             intensity="Weibull", envir=reps)
     # add the birth model
     kalsurv(times, pinitial=0.5, preg=c(1,0), pshape=1,
             intensity="Weibull", ccov=treat, pbirth=0)
     # try frailty dependence
     kalsurv(times, pinitial=0.5, preg=c(1,0), pshape=1, dep="frailty",
             intensity="Weibull", ccov=treat)
     # add autoregression
     kalsurv(times, pinitial=0.5, preg=c(1,0), pshape=1, dep="frailty",
             pdep=0.1, intensity="Weibull", ccov=treat)
     # switch to gamma intensity model
     kalsurv(times, pinitial=0.5, preg=c(1,0), pshape=1, intensity="gamma",
             ccov=treat)

