varPower                package:nlme                R Documentation

Power Variance Function

Description:

     This function is a constructor for the 'varPower' class,
     representing a power variance function structure. Letting v denote
     the variance covariate and s2(v) denote the variance function
     evaluated at v, the power variance function is defined as s2(v) =
     |v|^(2*t), where t is the variance  function coefficient. When a
     grouping factor is present, a different t is used for each factor
     level.

Usage:

     varPower(value, form, fixed)

Arguments:

   value: an optional numeric vector, or list of numeric values, with
          the variance function coefficients. 'Value' must have length
          one, unless a grouping factor is specified in 'form'. If
          'value' 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 'value' has length one, its value will be assigned to all
          grouping levels. 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, like 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 numeric vector, or list 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', '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 'varPower' object representing a 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:

     'varWeights.varFunc', 'coef.varPower'

Examples:

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

