

   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ouunntts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n--
   ddeennccee

        kalcount(response, times=NULL, origin=0, intensity="exponential",
             depend="independence", update="Markov", mu=NULL, shape=NULL,
             density=F, ccov=NULL, tvcov=NULL, preg=NULL, ptvc=NULL,
             pbirth=NULL, pintercept=NULL, pshape=1, pinitial=1, pdepend=NULL,
             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 counts and cor-
             responding times for each individual, one matrix
             or dataframe of counts, or an object of class,
             `response' (created by `restovec') or repeated
             (created by `rmna').  The time origin is taken to
             be zero and the given times to be the ends of
             periods (since the previous time given) in which
             the counts occurred.

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

     origin: If the time origin is to be before the start of
             observations, a positive constant to be added to
             all times.

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

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

     update: Type of for serial dependence. Choices are Markov,
             serial, event, cumulated, count, and kalman. With
             frailty dependence, weighting by length of obser-
             vation 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 (a log link is assumed) or a gen-
             eral function with named unknown parameters. If
             there are only time-constant 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 in the time periods in
             `response', for each individual (one column per
             variable), one matrix or dataframe of such covari-
             ate values, or an object of class, `tvcov' (cre-
             ated 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 a location function (mu) is supplied
             that contains time-varying covariates, all initial
             estimates must be given in ptvc. If `mu' 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.

       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.

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

      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::

        `kalcount' 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.

        Here, the variance, with exponential intensity, is a
        quadratic function of the mean, whereas, for `nbkal',
        it is proportional to the mean function.

        If the counts on a unit are clustered, not longitudi-
        nal, use the failty dependence with the default expo-
        nential intensity.

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

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

        A list of classes `kalcount' 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', `kalseries', `kalsurv',
        `nbkal', `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)
             matrix(c(9,13,16,7,12,6,9,10,11,9,10,10,7,9,9,9,8,10,15,4),
                  ncol=5,byrow=T)
        dd <- tvctomat(dose)
        y <- # matrix(rpois(20,1+3*rep(treat,5)),ncol=5)
             restovec(matrix(c(1,1,1,1,0,1,0,1,0,5,3,3,4,1,4,4,2,3,2,5),
                  ncol=5,byrow=T))
        reps <- rmna(y, ccov=tr, tvcov=dd)
        #
        # log normal intensity, independence model
        kalcount(y, intensity="log normal", dep="independence", preg=1,
             pshape=0.1)
        # random effects
        kalcount(y, intensity="log normal", dep="frailty", pdep=0.1, preg=1,
             psh=0.1)
        # serial dependence
        kalcount(y, intensity="log normal", dep="serial", pinitial=0.1,
             preg=1, pdep=0.01, psh=0.1)
        # add time-constant variable
        kalcount(y, intensity="log normal", pinitial=0.1, psh=0.1,
             preg=c(1,0), ccov=treat)
        # or equivalently
        kalcount(y, intensity="log normal", mu=~treat, pinitial=0.1,
             psh=0.1, preg=c(1,0))
        # or
        kalcount(y, intensity="log normal", mu=~b0+b1*treat,
             pinitial=0.1, psh=0.1, preg=c(1,0), envir=reps)
        # add time-varying variable
        kalcount(y, intensity="log normal", pinitial=0.1, psh=0.1,
             preg=c(1,0), ccov=treat, ptvc=0, tvc=dose)
        # or equivalently, from the environment
        kalcount(y, intensity="log normal",
             mu=~b0+b1*rep(treat,rep(5,4))+b2*as.vector(t(dose)),
             pinitial=0.1, psh=0.1, ptvc=c(1,0,0))
        # or from the reps data object
        kalcount(y, intensity="log normal", mu=~b0+b1*treat+b2*dose,
             pinitial=0.1, psh=0.1, ptvc=c(1,0,0), envir=reps)

