

kalseries(repeated)                          R Documentation

_R_e_p_e_a_t_e_d _M_e_a_s_u_r_e_m_e_n_t_s _M_o_d_e_l_s _f_o_r _C_o_n_t_i_n_u_o_u_s _V_a_r_i_a_b_l_e_s _i_n _t_h_e
_P_r_e_s_e_n_c_e _o_f _T_i_m_e_-_v_a_r_y_i_n_g _C_o_v_a_r_i_a_t_e_s _a_n_d _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_:

     `kalseries' is designed to handle repeated measurements
     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 among
     observations on a unit can be through frailty (a type
     of random effect) or serial dependence over time.

     Nonlinear regression models can be supplied as formulae
     where parameters are unknowns. Factor variables cannot
     be used and parameters must be scalars. (See `fin-
     terp'.)

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

     If the responses on a unit are clustered, not longitu-
     dinal, use the failty dependence with the default expo-
     nential intensity.

_U_s_a_g_e_:

     kalseries(response, times=NULL, intensity="exponential",
             depend="independence", mu=NULL, shape=NULL, density=F, ccov=NULL,
             tvcov=NULL, torder=0, interaction=NULL, preg=NULL, ptvc=NULL,
             pintercept=NULL, pshape=1, pinitial=1, pdepend=NULL, delta=NULL,
             transform="identity", link="identity",
             envir=sys.frame(sys.parent()), 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 two column matrices with responses and
          corresponding times for each individual, one
          matrix or dataframe of response values, or an
          object of class, `response' (created by
          `restovec') or repeated (created by `rmna').

   times: When response is a matrix, a vector of possibly
          unequally spaced times when they are the same for
          all individuals or a matrix of times. Not neces-
          sary if equally spaced. Ignored if response has
          class, `response' or `repeated'.

intensity: The form of function to be put in the Pareto dis-
          tribution.  Choices are exponential, Weibull,
          gamma, normal, logistic, Cauchy, Student, log nor-
          mal, log logistic, log Cauchy, log Student, and
          gen(eralized) logistic.

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

      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. If there are only time-con-
          stant covariates, give the initial estimates in
          preg; if any covariates are time-varying, give all
          initial estimates in ptvc.

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

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

    ccov: A vector or matrix containing time-constant base-
          line covariates with one row per individual, a
          model formula using vectors of the same size, or
          an object of class, `tccov' (created by `tcc-
          tomat'). 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 `tvc-
          tomat'). If a time-varying covariate is observed
          at arbitrary time, `gettvc' can be used to find
          the most recent values for each response and cre-
          ate a suitable list. 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.

  torder: The order of the polynomial in time to be fitted.

interaction: Vector of length equal to the number of time-
          constant covariates, giving the levels of interac-
          tions between them and the polynomial in time in
          the `linear model'.

    preg: Initial parameter estimates for the regression
          model: intercept, one for each covariate in
          `ccov', and `torder' plus sum(`interaction'). If a
          location function (`mu') is supplied that contains
          time-varying covariates, all initial estimates
          must be given in ptvc. If `mu' is a formula with
          unknown parameters, their estimates must be sup-
          plied 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 a location function (mu) is supplied
          that contains time-varying covariates, all initial
          estimates must be given here.

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

  pshape: An initial estimate for the shape parameter of the
          intensity function (except exponential intensity).
          If `shape' is a function or formula, the corre-
          sponding initial estimates. If `shape' is a for-
          mula 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.
          (With frailty dependence, this is the frailty
          parameter.)

 pdepend: An initial estimate for the serial dependence
          parameter.

   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 dec-
          imals, delta=0.01. If the response has been pre-
          transformed, this must be multiplied by the Jaco-
          bian. This transformation cannot contain unknown
          parameters. For example, with a log transforma-
          tion, `delta=1/y'. The jacobian is calculated
          automatically for the transform option. Ignored if
          response has class, `response' or `repeated'.

transform: Transformation of the response variable: `iden-
          tity', `exp', `square', `sqrt', or `log'.

    link: Link function for the mean: `identity', `exp',
          `square', `sqrt', or `log'.

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

  others: Arguments controlling `nlm'.

_V_a_l_u_e_:

     A list of classes `kalseries' and `recursive' is
     returned.

_A_u_t_h_o_r_(_s_)_:

     J.K. Lindsey

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

     `carma', `elliptic', `finterp', `gar', `gettvc',
     `gnlmm', `gnlr', `iprofile', `kalcount', `kalsurv',
     `profile', `read.list', `restovec', `rmna', `tcctomat',
     `tvctomat'.

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

     treat <- c(0,0,1,1)
     tr <- tcctomat(treat)
     dose <- matrix(rpois(20,10), ncol=5)
     dd <- tvctomat(dose)
     y <- restovec(matrix(rnorm(20), ncol=5))
     reps <- rmna(y, ccov=tr, tvcov=dd)
     #
     # normal intensity, independence model
     kalseries(y, intensity="normal", dep="independence", preg=1, pshape=5)
     # random effects
     kalseries(y, intensity="normal", dep="frailty", preg=1, pdep=0.1, psh=5)
     # serial dependence
     kalseries(y, intensity="normal", dep="serial", preg=1, pinitial=1,
             pdep=0.1, psh=5)
     #
     # add time-constant variable
     kalseries(y, intensity="normal", dep="serial", pinitial=1,
             pdep=0.1, psh=5, preg=c(1,0), ccov=treat)
     # or equivalently
     kalseries(y, intensity="normal", mu=~treat, dep="serial", pinitial=1,
             pdep=0.1, psh=5, preg=c(1,0))
     # or
     kalseries(y, intensity="normal", mu=~b0+b1*treat, dep="serial",
             pinitial=1, pdep=0.1, psh=5, preg=c(1,0), envir=reps)
     #
     # add time-varying variable
     kalseries(y, intensity="normal", dep="serial", pinitial=1, pdep=0.1,
             psh=5, preg=c(1,0), ccov=treat, ptvc=0, tvc=dose)
     # or equivalently, from the environment
     kalseries(y, intensity="normal",
             mu=~b0+b1*rep(treat,rep(5,4))+b2*as.vector(t(dose)),
             dep="serial", pinitial=1, pdep=0.1, psh=5, ptvc=c(1,0,0))
     # or from the reps data object
     kalseries(y, intensity="normal", mu=~b0+b1*treat+b2*dose,
             dep="serial", pinitial=1, pdep=0.1, psh=5,
             ptvc=c(1,0,0), envir=reps)
     # first-order one-compartment model
     # data objects for formulae
     dose <- c(2,5)
     dd <- tcctomat(dose)
     times <- matrix(rep(1:20,2), nrow=2, byrow=T)
     tt <- tvctomat(times)
     # vector covariates for functions
     dose <- c(rep(2,20),rep(5,20))
     times <- rep(1:20,2)
     # functions
     mu <- function(p) exp(p[1]-p[3])*(dose/(exp(p[1])-exp(p[2]))*
             (exp(-exp(p[2])*times)-exp(-exp(p[1])*times)))
     shape <- function(p) exp(p[1]-p[2])*times*dose*exp(-exp(p[1])*times)
     # response
     conc <- matrix(rgamma(40,shape(log(c(0.01,1))),mu(log(c(1,0.3,0.2)))),
             ncol=20,byrow=T)
     conc[,2:20] <- conc[,2:20]+0.5*(conc[,1:19]-matrix(mu(log(c(1,0.3,0.2))),
             ncol=20,byrow=T)[,1:19])
     conc <- restovec(ifelse(conc>0,conc,0.01))
     reps <- rmna(conc, ccov=dd, tvcov=tt)
     #
     # constant shape parameter
     kalseries(reps, intensity="gamma", dep="independence", mu=mu,
             ptvc=c(-1,-1.1,-1), pshape=1.5, envir=reps)
     # or
     kalseries(reps, intensity="gamma", dep="independence",
             mu=~exp(absorption-volume)*
             dose/(exp(absorption)-exp(elimination))*
             (exp(-exp(elimination)*times)-exp(-exp(absorption)*times)),
             ptvc=list(absorption=-1,elimination=-1.1,volume=-1),
             pshape=1.2, envir=reps)
     # add serial dependence
     kalseries(reps, intensity="gamma", dep="serial", pdep=0.9,
             mu=~exp(absorption-volume)*
             dose/(exp(absorption)-exp(elimination))*
             (exp(-exp(elimination)*times)-exp(-exp(absorption)*times)),
             ptvc=list(absorption=-1,elimination=-1.1,volume=-1),
             pshape=1.2, envir=reps)
     # time dependent shape parameter
     kalseries(reps, intensity="gamma", dep="independence", mu=mu,
             shape=shape, ptvc=c(-1,-1.1,-1), pshape=c(-3,0),
             envir=reps)
     # or
     kalseries(reps, intensity="gamma", dep="independence",
             mu=~exp(absorption-volume)*
             dose/(exp(absorption)-exp(elimination))*
             (exp(-exp(elimination)*times)-exp(-exp(absorption)*times)),
             ptvc=list(absorption=-1,elimination=-1.1,volume=-1),
             shape=~exp(b1-b2)*times*dose*exp(-exp(b1)*times),
             pshape=list(b1=-3,b2=0), envir=reps)
     # add serial dependence
     kalseries(reps, intensity="gamma", dep="serial", pdep=0.5,
             mu=~exp(absorption-volume)*
             dose/(exp(absorption)-exp(elimination))*
             (exp(-exp(elimination)*times)-exp(-exp(absorption)*times)),
             ptvc=list(absorption=-1,elimination=-1.1,volume=-1),
             shape=~exp(b1-b2)*times*dose*exp(-exp(b1)*times),
             pshape=list(b1=-3,b2=0), envir=reps)

