

   CCoonnssttrruucctt aa ggrroouuppeeddDDaattaa OObbjjeecctt

        groupedData(formula, data, order.groups, FUN, outer, inner,
         labels, units)

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

    formula: a formula of the form `resp ~ cov | group' where
             `resp' is the response, `cov' is the primary
             covariate, and `group' is the grouping factor.
             The expression `1' can be used for the primary
             covariate when there is no other suitable candi-
             date.  Multiple nested grouping factors can be
             listed separated by the `/' symbol as in
             `fact1/fact2'.  In an expression like this the
             `fact2' factor is nested within the `fact1' fac-
             tor.

       data: a data frame in which the expressions in `formula'
             can be evaluated.  The resulting `groupedData'
             object will consist of the same data values in the
             same order but with additional attributes.

   order.groups: an optional logical value, or list of logical
             values, indicating if the grouping factors should
             be converted to ordered factors according to the
             function `FUN' applied to the response from each
             group. If multiple levels of grouping are present,
             this argument can be either a single logical value
             (which will be repeated for all grouping levels)
             or a list of logical values. If no names are
             assigned to the list elements, they are assumed in
             the same order as the group levels (outermost to
             innermost grouping). Ordering within a level of
             grouping is done within the levels of the grouping
             factors which are outer to it. Changing the group-
             ing factor to an ordered factor does not affect
             the ordering of the rows in the data frame but it
             does affect the order of the panels in a trellis
             display of the data or models fitted to the data.
             Defaults to `TRUE'.

        FUN: an optional summary function that will be applied
             to the values of the response for each level of
             the grouping factor, when `order.groups = TRUE',
             to determine the ordering.  Defaults to the `max'
             function.

      outer: an optional one-sided formula, or list of one-
             sided formulas, indicating covariates that are
             outer to the grouping factor(s).  If multiple lev-
             els of grouping are present, this argument can be
             either a single one-sided formula, or a list of
             one-sided formulas. If no names are assigned to
             the list elements, they are assumed in the same
             order as the group levels (outermost to innermost
             grouping). An outer covariate is invariant within
             the sets of rows defined by the grouping factor.
             Ordering of the groups is done in such a way as to
             preserve adjacency of groups with the same value
             of the outer variables.  When plotting a  grouped-
             Data object, the argument `outer = TRUE' causes
             the panels to be determined by the `outer' for-
             mula.  The points within the panels are associated
             by level of the grouping factor. Defaults to
             `NULL', meaning that no outer covariates are pre-
             sent.

      inner: an optional one-sided formula, or list of one-
             sided formulas, indicating covariates that are
             inner to the grouping factor(s). If multiple lev-
             els of grouping are present, this argument can be
             either a single one-sided formula, or a list of
             one-sided formulas. If no names are assigned to
             the list elements, they are assumed in the same
             order as the group levels (outermost to innermost
             grouping). An inner covariate can change within
             the sets of rows defined by the grouping factor.
             An inner formula can be used to associate points
             in a plot of a groupedData object.  Defaults to
             `NULL', meaning that no inner covariates are pre-
             sent.

     labels: an optional list of character strings giving
             labels for the response and the primary covariate.
             The label for the primary covariate is named `x'
             and that for the response is named `y'.  Either
             label can be omitted.

      units: an optional list of character strings giving the
             units for the response and the primary covariate.
             The units string for the primary covariate is
             named `x' and that for the response is named `y'.
             Either units string can be omitted.

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

        An object of the `groupedData' class is constructed
        from the `formula' and `data' by attaching the `for-
        mula' as an attribute of the data, along with any of
        `outer', `inner', `labels', and `units' that are given.
        If `order.groups' is `TRUE' the grouping factor is con-
        verted to an ordered factor with the ordering deter-
        mined by `FUN'. Depending on the number of grouping
        levels and the type of primary covariate, the returned
        object will be of one of three classes: `nfnGrouped-
        Data' - numeric covariate, single level of nesting;
        `nffGroupedData' - factor covariate, single level of
        nesting; and `nmGroupedData' - multiple levels of nest-
        ing. Several modelling and plotting functions can use
        the formula stored with a `groupedData' object to con-
        struct default plots and models.

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

        an object inheriting from one of the classes `nfn-
        GroupedData', `nffGroupedData', or `nmGroupedData', and
        also inheriting from  classes `groupedData' and
        `data.frame'.

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

        Douglas Bates and Jose Pinheiro

   RReeffeerreenncceess::

        Bates, D.M. and Pinheiro, J.C. (1997), "Software Design
        for Longitudinal Data", in "Modelling Longitudinal and
        Spatially Correlated Data: Methods, Applications and
        Future Directions", T.G. Gregoire (ed.), Springer-Ver-
        lag, New York.

        Pinheiro, J.C. and Bates, D.M. (1997) "Future Direc-
        tions in Mixed-Effects Software: Design of NLME 3.0"
        available at http://franz.stat.wisc.edu/pub/NLME.

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

        `formula', `gapply', `gsummary', `lme', `plot.grouped-
        Data'

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

        library( lme )
        data( Orthodont )
        Orth.new <-  # create a new copy of the groupedData object
          groupedData( distance ~ age | Subject,
                      data = as.data.frame( Orthodont ),
                      FUN = mean,
                      outer = ~ Sex,
                      labels = list( x = "Age",
                        y = "Distance from pituitary to pterygomaxillary fissure" ),
                      units = list( x = "(yr)", y = "(mm)") )
        plot( Orth.new )         # trellis plot by Subject
        formula( Orth.new )      # extractor for the formula
        gsummary( Orth.new )     # apply summary by Subject
        fm1 <- lme( Orth.new )   # fixed and groups formulae extracted from object

