

   GGeenneerraalliizzeedd aauuttoorreeggrreessssiioonn

        gar(response, distribution="normal", times=NULL, totals=NULL, censor=NULL,
             delta=NULL, mu=NULL, shape=NULL, shfn=F, common=F, preg=NULL,
             pdepend=NULL, pshape=NULL, transform="identity", link="identity",
             autocorr="exponential", order=1, envir=sys.frame(sys.parent()),
             print.level=0, ndigit=10, gradtol=0.00001,steptol=0.00001,
             fscale=1, iterlim=100, typsiz=abs(p), stepmax=10*sqrt(p%*%p))

   AArrgguummeennttss::

   response: A list of two or three column matrices with
             responses, corresponding times, and possibly a
             censor indicator, for each individual, one matrix
             or dataframe of responses, or an object of class,
             response (created by `restovec') or repeated (cre-
             ated by `rmna').

   distribution: The distribution to be fitted: Bernoulli,
             Poisson, exponential, negative binomial, mult
             Poisson, double Poisson, beta binomial, mult bino-
             mial, double binomial, normal, inverse Gauss,
             logistic, gamma, Weibull, Cauchy, Laplace, Levy,
             Pareto, gen(eralized) gamma, gen(eralized) logis-
             tic, Hjorth, Burr, gen(eralized) Weibull,
             gen(eralized) extreme value, gen(eralized) inverse
             Gauss, or power exponential.

      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.

     totals: An appropriate scalar, vector, or matrix of bino-
             mial totals (only applicable for binomial, beta
             binomial, mult binomial, double binomial). Ignored
             if response has class, response or repeated.

     censor: If response is a matrix, a matrix of the same size
             containing the censor indicator: 1=uncensored,
             0=right-censored, -1=left-censored. 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 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 delta values for the cen-
             sored response are ignored.) The jacobian is cal-
             culated automatically for the transform option.
             Ignored if response has class, response or
             repeated.

         mu: A user-specified function of `pmu' giving the
             regression equation for the location. It may also
             be a formula beginning with ~, specifying either a
             linear regression function for the location param-
             eter in the Wilkinson and Rogers notation or a
             general function with named unknown parameters. It
             must yield a  value for each observation on each
             individual.

      shape: An optional user-specified shape regression func-
             tion; this may depend on the location (function)
             through its second argument, in which case, `shfn'
             must be set to TRUE. It may also be a formula
             beginning with ~, specifying either a linear
             regression function for the shape parameter in the
             Wilkinson and Rogers notation or a general func-
             tion with named unknown parameters.

       shfn: If TRUE, the supplied shape function depends on
             the location function. The name of this location
             function must be the last argument of the shape
             function.

     common: If TRUE, `mu' and `shape' must both be functions
             with, as argument, a vector of parameters having
             some or all elements in common between them so
             that indexing is in common between them; all
             parameter estimates must be supplied in `preg'.
             If FALSE, parameters are distinct between the two
             functions and indexing starts at one in each func-
             tion.

       preg: The initial parameter estimates for the location
             regression function. 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.

    pdepend: One or two estimates of the dependence parameters
             for the Kalman update. With one, it is Markovian
             and, with two, it is nonstationary. For the lat-
             ter, the `order' must be one.

     pshape: Zero to two estimates for the shape parameters of
             the distribution if `shape' is not a function;
             otherwise, estimates for the parameters in this
             function, with one extra at the end for three-
             parameter distributions. 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.

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

       link: Link function for the mean: `identity', `exp',
             `square', `sqrt', `log', `logit', or `cloglog'
             (last two only for binary data).

   autocorr: The form of the (second if two) dependence func-
             tion: `exponential' is the usual rho^|t_i-t_j|;
             `gaussian' is rho^((t_i-t_j)^2); `cauchy' is
             1/(1+rho(t_i-t_j)^2); `spherical' is ((|t_i-
             t_j|rho)^3-3|t_i-t_j|rho+2)/2 for |t_i-t_j|<=1/rho
             and zero otherwise; `IOU' is the integrated Orn-
             stein-Uhlenbeck process, (2rho
             min(t_i,t_j)+exp(-rho t_i) +exp(-rho t_j)-1
             -exp(rho|ti-t_j|))/2rho^3.

      order: First- or second-order stationary autoregression.

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

        `gar' fits a first- or second-order generalized autore-
        gression, possibly with Kalman update over time (first-
        order only).

        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 `gar' and `recursive' is returned.

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

        J.K. Lindsey

   RReeffeerreenncceess::

        Lindsey, J.K. (1997) Applying Generalized Linear Mod-
        els. Springer, pp. 93-101

        Lambert, P. (1996) Statistics in Medicine 15, 1695-1708

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

        `carma', `elliptic', `finterp', `gnlmm', `gnlr', `ipro-
        file', `kalcount', `kalseries', `kalsurv', `plot.resid-
        uals', `profile', `read.list', `restovec', `rmna',
        `tcctomat', `tvctomat'.

   EExxaammpplleess::

        # 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.1,0.4))),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
        gar(conc, dist="gamma", times=1:20, mu=mu,
             preg=log(c(1,0.4,0.1)), pdepend=0.5, pshape=1)
        # or
        gar(conc, dist="gamma", times=1:20, mu=~exp(absorption-volume)*
             dose/(exp(absorption)-exp(elimination))*
             (exp(-exp(elimination)*times)-exp(-exp(absorption)*times)),
             preg=list(absorption=0,elimination=log(0.4),volume=log(0.1)),
             pdepend=0.5, pshape=1, envir=reps)
        # (if the covariates contained NAs, reps would have to be used as
        # response instead of conc)
        #
        # time dependent shape parameter
        gar(conc, dist="gamma", times=1:20, mu=mu, shape=shape,
             preg=log(c(1,0.4,0.1)), pdepend=0.5, pshape=log(c(1,0.2)))
        # or
        gar(conc, dist="gamma", times=1:20, mu=~exp(absorption-volume)*
             dose/(exp(absorption)-exp(elimination))*
             (exp(-exp(elimination)*times)-exp(-exp(absorption)*times)),
             shape=~exp(b1-b2)*times*dose*exp(-exp(b1)*times),
             preg=list(absorption=0,elimination=log(0.4),volume=log(0.1)),
             pdepend=0.5, pshape=list(b1=0,b2=log(0.2)), envir=reps)

