varIdent                package:nlme                R Documentation

Constant Variance Function

Description:

     This function is a constructor for the 'varIdent' class,
     representing a constant variance function structure. If no
     grouping factor is present in 'form', the variance function is
     constant and equal to one, and no coefficients required to
     represent it. When 'form' includes a grouping factor with M > 1
     levels, the variance function allows M different variances, one 
     for each level of the factor. For identifiability reasons, the
     coefficients of the variance function represent the ratios between
     the variances and a reference variance (corresponding to a
     reference group level). Therefore, only M-1 coefficients are
     needed to represent the variance function. By default, if the
     elements in 'value' are unnamed, the first group level is taken as
     the reference level.

Usage:

     varIdent(value, form, fixed)

Arguments:

   value: an optional numeric vector, or list of numeric values, with
          the variance function coefficients. If no grouping factor is
          present in 'form', this argument is ignored, as the resulting
          variance function contains no coefficients. If 'value' has
          length one, its value is repeated for all coefficients in the
          variance function. If 'value' has length greater than one, it
          must have length equal to the number of grouping levels minus
          one and names which identify its elements to the levels of
          the grouping factor. Only positive values are allowed for
          this argument. 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 is ignored in this variance function. When a
          grouping factor is present in 'form', a different coefficient
          value is used for each of its levels less one reference level
          (see description section below). 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 '~ 1'. 

   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. It
          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 'varIdent' object representing a constant 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.varIdent'

Examples:

     vf1 <- varIdent(c(Female = 0.5), form = ~ 1 | Sex)

