

   RReeppeeaatteedd MMeeaassuurreemmeennttss MMooddeellss ffoorr CCoonnttiinnuuoouuss VVaarriiaabblleess iinn tthhee
   PPrreesseennccee ooff TTiimmee--vvaarryyiinngg CCoovvaarriiaatteess aanndd wwiitthh FFrraaiillttyy oorr
   SSeerriiaall DDeeppeennddeenncce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Arrgguummeenntts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'.

   DDeessccrriippttiioon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.

   VVaalluuee::

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

   AAuutthhoorr((ss))::

        J.K. Lindsey

   SSeeee AAllssoo::

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

   EExxaammppllees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)

