repeated (version 1.1.9)

gar: Generalized Autoregression Models

Description

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

Usage

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 = "square",
  transform = "identity",
  link = "identity",
  autocorr = "exponential",
  order = 1,
  envir = parent.frame(),
  print.level = 0,
  ndigit = 10,
  gradtol = 1e-05,
  steptol = 1e-05,
  fscale = 1,
  iterlim = 100,
  typsize = abs(p),
  stepmax = 10 * sqrt(p %*% p)
)

Value

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.

Arguments

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.

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

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.

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|\leq1/\rho\) and zero otherwise; IOU is the integrated Ornstein-Uhlenbeck process, \((2\rho \min(t_i,t_j)+\exp(-\rho t_i) \)\(+\exp(-\rho t_j)-1 -\exp(\rho|ti-t_j|))/2\rho^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.

print.level

Arguments for nlm.

ndigit

Arguments for nlm.

gradtol

Arguments for nlm.

steptol

Arguments for nlm.

fscale

Arguments for nlm.

iterlim

Arguments for nlm.

typsize

Arguments for nlm.

stepmax

Arguments for nlm.

Author

J.K. Lindsey

Details

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.

References

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

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

Examples

# 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)
if (FALSE) # 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=1,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.3, 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.25, pshape=c(exp(-2),exp(-.57)))
# 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.3, pshape=list(b1=exp(-2),b2=exp(-.57)), 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(exp(-2),exp(-.57),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,.10)), pdepend=0.15, pshape=c(1,2))
# or
gar(conc, dist="gamma", times=1:20, mu=mu, shape=~a+d*mu, shfn=TRUE,
    preg=log(c(1,0.4,.10)), pdepend=0.15, pshape=c(1,2))