gar                 package:repeated                 R Documentation

_G_e_n_e_r_a_l_i_z_e_d _A_u_t_o_r_e_g_r_e_s_s_i_o_n _M_o_d_e_l_s

_D_e_s_c_r_i_p_t_i_o_n:

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

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

     When the dispersion parameter is not constant over time,
     'volatility' extracts the square root of the dispersion parameter
     for a fitted model.

_U_s_a_g_e:

     gar(response=NULL, distribution="normal", times=NULL, totals=NULL,
             censor=NULL, delta=NULL, mu=NULL, shape=NULL, depend=NULL,
             shfn=FALSE, common=FALSE, preg=NULL, pshape=NULL, pdepend=NULL,
             parch=NULL, arch="additive", transform="identity",
             link="identity", autocorr="exponential", order=1,
             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))
     volatility(z, nind=NULL)

_A_r_g_u_m_e_n_t_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' (created by 'rmna'). 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.

distribution: The distribution to be fitted: binomial, Poisson,
          exponential, negative binomial, mult Poisson, double Poisson,
          Consul generalized Poisson, beta binomial, mult binomial,
          double binomial, normal, inverse Gauss, logistic, gamma,
          Weibull, Cauchy, Laplace, Levy, Pareto, beta, simplex,
          two-sided power, gen(eralized) gamma, gen(eralized) logistic,
          Hjorth, Burr, gen(eralized) Weibull, gen(eralized) extreme
          value, gen(eralized) inverse Gauss, power exponential, power
          variance function Poisson, skew Laplace, or Student t. (For
          definitions of distributions, see the corresponding
          [dpqr]distribution help.)

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

  totals: An appropriate scalar, vector, or matrix of binomial 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 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 delta values for the censored response are
          ignored.) The jacobian is calculated 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 parameter 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 function; 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 function with
          named unknown parameters. If it contains unknown parameters,
          the keyword 'mu' may be used to specify a function of the
          location parameter.

  depend: An optional user-specified regression function for the log
          dependence parameter. It may also be a formula beginning with
          ~, specifying either a linear regression function for the
          dependence parameter in the Wilkinson and Rogers notation or
          a general function with named unknown parameters. If used,
          'order' must be one.

    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 either 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 or formulae with unknowns. All parameter
          estimates must be supplied in 'preg'. If FALSE, parameters
          are distinct between the two functions and indexing starts at
          one in each function.

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

 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 latter, the 'order' must be one. If
          'depend' is a function or formula, the corresponding number
          of estimates must be supplied. Either pdepend or parch or
          both must be supplied.

   parch: Estimate for an ARCH model where the shape parameter depends
          on the square of the previous residual. Either pdepend or
          parch or both must be supplied.

    arch: If 'square', then 'shape+parch^diff*residual^2'; if 'absolute
          value', then 'shape+parch^diff*|residual|'; if 'exponential',
          then 'shape*exp(parch*residual^2*diff)', where 'diff' is the
          length of time since the previous observation and 'residual'
          is the previous residual or innovation.

  pshape: Zero to two estimates for the shape parameters, depending on
          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 (only for two-parameter
          distributions).

transform: Transformation of the response variable: 'identity', 'exp',
          'square', 'sqrt', or 'log'.

    link: Link function for the mean: 'identity', 'exp', 'square',
          'sqrt', 'log', 'logit', 'cloglog' or 'loglog' (last three
          only for binary/binomial-type data).

autocorr: The form of the (second if two) dependence function:
          '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
          Ornstein-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'; 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 'gar' and 'recursive' is returned that contains
     all of the relevant information calculated, including error codes.

     The volatility vector for models with a shape regression function
     and ARCH models contains the square root of the dispersion
     parameter at each time point.

_A_u_t_h_o_r(_s):

     J.K. Lindsey

_R_e_f_e_r_e_n_c_e_s:

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

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

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

     'carma', 'elliptic', 'finterp', 'gnlmm', 'gnlr', 'iprofile',
     'kalcount', 'kalseries', 'kalsurv', 'mprofile', 'plot.residuals',
     'read.list', 'restovec', 'rmna', 'tcctomat', 'tvctomat'.

_E_x_a_m_p_l_e_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=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.1,0.4))),
             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),name="conc")
     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)
     # generalized gamma distribution
     gar(conc, dist="gen gamma", times=1:20, mu=mu,
             preg=log(c(1,0.4,0.1)), pdepend=0.5, pshape=c(1,1))
     # (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)
     # generalized gamma distribution
     gar(conc, dist="gen gamma", times=1:20, mu=mu, shape=shape,
             preg=log(c(1,0.4,0.1)), pdepend=0.5,
             pshape=c(log(c(1,0.2)),2))
     #
     # shape function depends on location parameter
     shape <- function(p, mu) p[1]+p[2]*mu
     gar(conc, dist="gamma", times=1:20, mu=mu, shape=shape, shfn=TRUE,
             preg=log(c(1,0.4,0.1)), pdepend=0.5, pshape=c(1,0))
     # or
     gar(conc, dist="gamma", times=1:20, mu=mu, shape=~a+d*mu, shfn=TRUE,
             preg=log(c(1,0.4,0.1)), pdepend=0.5, pshape=c(1,0))

