varConstPower              package:nlme              R Documentation

Constant Plus Power Variance Function

Description:

     This function is a constructor for the 'varConstPower' class,
     representing a constant plus power variance function structure.
     Letting v denote the variance covariate and s2(v) denote the
     variance function evaluated at v, the constant plus power variance
     function is defined as s2(v) = (t1 + |v|^t2)^2, where t1, t2 are
     the variance   function coefficients. When a grouping factor is
     present, different t1, t2 are used for each factor level.

Usage:

     varConstPower(const, power, form, fixed)

Arguments:

const, power: optional numeric vectors, or lists of numeric values,
          with, respectively, the coefficients for the constant  and
          the power terms. Both arguments must have length one, unless
          a grouping factor is specified in 'form'. If either argument
          has length greater than one, it must have names which
          identify its elements to the levels of the grouping factor
          defined in 'form'. If a grouping factor is present in  'form'
          and the argument has length one, its value will be assigned
          to all grouping levels. Only positive values are allowed for
          'const'. Default is 'numeric(0)', which results in a vector
          of zeros of appropriate length being assigned to the
          coefficients when 'object' is initialized (corresponding to
          constant variance equal to one).

    form: an optional one-sided formula of the form '~ v', or '~ v |
          g', specifying a variance covariate 'v' and, optionally, a
          grouping factor 'g' for the coefficients. The variance
          covariate must evaluate to a numeric vector and may involve
          expressions using '"."', representing  a fitted model object
          from which fitted values ('fitted(.)') and residuals
          ('resid(.)') can be extracted (this allows the variance
          covariate to be updated during the optimization of an object
          function). When a grouping factor is present in 'form', a
          different coefficient value is used for each of its levels.
          Several grouping variables may be simultaneously specified,
          separated by the '*' operator, as in '~ v | g1 * g2 * g3'. In
          this case, the levels of each grouping variable are pasted
          together and the resulting factor is used to group the
          observations. Defaults to '~ fitted(.)' representing a
          variance covariate given by the fitted values of a fitted
          model object and no grouping factor. 

   fixed: an optional list with components 'const' and/or 'power',
          consisting of numeric vectors, or lists of numeric values,
          specifying the values at which some or all of the
          coefficients in the variance function should be fixed. If a
          grouping factor is specified in 'form', the components of
          'fixed' must have names identifying which coefficients are to
          be fixed. Coefficients included in 'fixed' are not allowed to
          vary during the optimization of an objective function.
          Defaults to 'NULL', corresponding to no fixed coefficients.

Value:

     a 'varConstPower' object representing a constant plus power
     variance function structure, also inheriting from class 'varFunc'.

Author(s):

     Jose Pinheiro Jose.Pinheiro@pharma.novartis.com and Douglas Bates
     bates@stat.wisc.edu

References:

     Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models in S
     and S-PLUS", Springer.

See Also:

     'varClasses', 'varWeights.varFunc', 'coef.varConstPower'

Examples:

     vf1 <- varConstPower(1.2, 0.2, form = ~age|Sex)

