

groupedData(nlme)                            R Documentation

_C_o_n_s_t_r_u_c_t _a _g_r_o_u_p_e_d_D_a_t_a _O_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_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 modeling and plotting functions can use
     the formula stored with a `groupedData' object to con-
     struct default plots and models.

_U_s_a_g_e_:

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

_A_r_g_u_m_e_n_t_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.

_V_a_l_u_e_:

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

_A_u_t_h_o_r_(_s_)_:

     Douglas Bates and Jose Pinheiro

_R_e_f_e_r_e_n_c_e_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://nlme.stat.wisc.edu/

_S_e_e _A_l_s_o_:

     `formula', `gapply', `gsummary', `lme'

_E_x_a_m_p_l_e_s_:

     library( nlme )
     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

