

   PPoowweerr VVaarriiaannccee FFuunnccttiioonn

        varPower(value, form, fixed)

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

      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 group-
             ing 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 residu-
             als (`resid(.)') can be extracted (this allows the
             variance covariate to be updated during the opti-
             mization of an object function). When a grouping
             factor is present in `form', a different coeffi-
             cient value is used for each of its levels. Sev-
             eral 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 observa-
             tions. 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.

   DDeessccrriippttiioonn::

        This function is a constructor for the `varPower'
        class, representing a power variance function struc-
        ture. 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.

   VVaalluuee::

        a `varPower' object representing a power variance func-
        tion structure, also inheriting from class `varFunc'.

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

        Jose Pinheiro and Douglas Bates

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

        `varWeights.varFunc', `coef.varPower'

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

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

