kalseries              package: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 _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 gamma or
     power variance family frailties (a type of random effect), with or
     without autoregression, or one of two types of serial dependence
     over time.

     By default, a gamma mixture of the distribution specified in
     'intensity' is used, as the conditional distribution in the
     'Markov' and '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:

     kalseries(response=NULL, times=NULL, intensity="exponential",
             depend="independence", mu=NULL, shape=NULL, density=FALSE, ccov=NULL,
             tvcov=NULL, torder=0, interaction=NULL, preg=NULL, ptvc=NULL,
             pintercept=NULL, pshape=NULL, pinitial=1, pdepend=NULL,
             pfamily=NULL, delta=NULL, transform="identity", link="identity",
             envir=parent.frame(), print.level=0, ndigit=10, gradtol=0.00001,
             steptol=0.00001, fscale=1, iterlim=100, 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' 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.

   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 necessary if equally spaced. Ignored if
          response has class, 'response' or 'repeated'.

intensity: The form of function to be put in the Pareto distribution.
          Choices are exponential, Weibull, gamma, normal, logistic,
          Cauchy, log normal, log logistic, log Cauchy, log Student,
          inverse Gauss, and gen(eralized) logistic. (For definitions
          of distributions, see the corresponding [dpqr]distribution
          help.)

  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. 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.

 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 baseline
          covariates with one row 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 a time-varying covariate is
          observed at arbitrary time, 'gettvc' can be used to find the
          most recent values for each response and create 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 interactions 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 '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.

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 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. With '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'.

   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 jacobian is calculated automatically for the
          transform option. Ignored if response has class, 'response'
          or 'repeated'.

transform: Transformation of the response variable: 'identity', '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'; 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 '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', 'mprofile', '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), name="y")
     reps <- rmna(y, ccov=tr, tvcov=dd)
     #
     # normal intensity, independence model
     kalseries(y, intensity="normal", dep="independence", preg=1, pshape=5)
     # random effect
     kalseries(y, intensity="normal", dep="frailty", preg=1, pinitial=1, psh=5)
     # serial dependence
     kalseries(y, intensity="normal", dep="serial", preg=1, pinitial=1,
             pdep=0.1, psh=5)
     # random effect and autoregression
     kalseries(y, intensity="normal", dep="frailty", 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
     dosev <- as.vector(t(dose))
     kalseries(y, intensity="normal",
             mu=~b0+b1*rep(treat,rep(5,4))+b2*dosev,
             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)
     # try power variance family instead of gamma distribution for mixture
     kalseries(y, intensity="normal", mu=~b0+b1*treat+b2*dose,
             dep="serial", pinitial=1, pdep=0.1, psh=5, ptvc=c(1,0,0),
             pfamily=0.1, 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=TRUE)
     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))),
             scale=mu(log(c(1,0.3,0.2))))/shape(log(c(0.1,0.4))),ncol=20,byrow=TRUE)
     conc[,2:20] <- conc[,2:20]+0.5*(conc[,1:19]-matrix(mu(log(c(1,0.3,0.2))),
             ncol=20,byrow=TRUE)[,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)
     # 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)
     # 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=0.2)
     # time dependent shape parameter
     kalseries(reps, intensity="gamma", dep="independence", mu=mu,
             shape=shape, ptvc=c(-1,-1.1,-1), pshape=c(-3,0))
     # 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))
     # 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))

