reStruct                package:nlme                R Documentation

Random Effects Structure

Description:

     This function is a constructor for the 'reStruct' class,
     representing a random effects structure and consisting of a list
     of 'pdMat' objects, plus a 'settings' attribute containing
     information for the optimization algorithm used to fit the
     associated mixed-effects model.

Usage:

     reStruct(object, pdClass, REML, data)
     ## S3 method for class 'reStruct':
     print(x, sigma, reEstimates, verbose, ...)

Arguments:

  object: any of the following: (i) a one-sided formula of the form
          '~x1+...+xn | g1/.../gm', with 'x1+...+xn' specifying the
          model for the random effects and 'g1/.../gm' the grouping
          structure ('m' may be equal to 1, in which case no '/' is
          required). The random effects formula will be repeated for
          all levels of grouping, in the case of multiple levels of
          grouping; (ii) a list of one-sided formulas of the form
          '~x1+...+xn | g', with possibly different random effects
          models for each grouping level. The order of nesting will be
          assumed the same as the order of the elements in the list;
          (iii) a one-sided formula of the form '~x1+...+xn', or a
          'pdMat' object with a formula (i.e. a non-'NULL' value for
          'formula(object)'), or a list of such formulas or 'pdMat'
          objects. In this case, the grouping structure formula will be
          derived from the data used to to fit the mixed-effects model,
          which should inherit from class 'groupedData'; (iv) a named
          list of formulas or 'pdMat' objects as in (iii), with the
          grouping factors as names. The order of nesting will be
          assumed the same as the order of the order of the elements in
          the list; (v) an 'reStruct' object.

 pdClass: an optional character string with the name of the 'pdMat'
          class to be used for the formulas in 'object'. Defaults to
          '"pdSymm"' which corresponds to a general positive-definite
          matrix.

    REML: an optional logical value. If 'TRUE', the associated
          mixed-effects model will be fitted using restricted maximum
          likelihood; else, if 'FALSE', maximum likelihood will be
          used. Defaults to 'FALSE'.

    data: an optional data frame in which to evaluate the variables
          used in the random effects formulas in 'object'. It is used
          to obtain the levels for 'factors', which affect the
          dimensions and the row/column names of the underlying 'pdMat'
          objects. If 'NULL', no attempt is made to obtain information
          on 'factors' appearing in the formulas. Defaults to the
          parent frame from which the function was called.

       x: an object inheriting from class 'reStruct' to be printed.

   sigma: an optional numeric value used as a multiplier for the
          square-root factors of the 'pdMat' components (usually the
          estimated within-group standard deviation from a
          mixed-effects model). Defaults to 1.

reEstimates: an optional list with the random effects estimates for
          each level of grouping. Only used when 'verbose = TRUE'.

 verbose: an optional logical value determining if the random effects
          estimates should be printed. Defaults to 'FALSE'.

     ...: Optional arguments can be given to other methods for this
          generic.  None are used in this method.

Value:

     an object inheriting from class 'reStruct', representing a random
     effects structure.

Author(s):

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

See Also:

     'pdMat', 'lme', 'groupedData'

Examples:

     data(Pixel)
     rs1 <- reStruct(list(Dog = ~day, Side = ~1), data = Pixel)
     rs1

