simulate.lme              package:nlme              R Documentation

Simulate results from lme models

Description:

     The model 'object' is fit to the data.  Using the fitted values of
     the parameters, 'nsim' new data vectors from this model are
     simulated.  Both 'm1' and 'm2' are fit by maximum likelihood (ML)
     and/or by restricted maximum likelihood (REML) to each of the
     simulated data vectors.

Usage:

     simulate.lme(object, nsim, seed, m2, method, niterEM, useGen, ...)

Arguments:

  object: an object inheriting from class 'lme', representing a fitted
          linear mixed-effects model, or a list containing an lme model
          specification.  If given as a list, it should contain
          components 'fixed', 'data', and 'random' with values suitable
          for a call to 'lme'. This argument defines the null model. 

      m2: an 'lme' object, or a list, like 'm1' containing a second lme
          model specification. This argument defines the alternative
          model. If given as a list, only those parts of the
          specification that change between model 'm1' and 'm2' need to
          be specified. 

    seed: an optional integer that is passed to 'set.seed'.  Defaults
          to a random integer. 

  method: an optional character array.  If it includes '"REML"' the
          models are fit by maximizing the restricted log-likelihood.
          If it includes '"ML"' the log-likelihood is maximized. 
          Defaults to 'c("REML", "ML")', in which case both methods are
          used. 

    nsim: an optional positive integer specifying the number of
          simulations to perform.  Defaults to *1*. *This has changed. 
          Previously the default was 1000.* 

 niterEM: an optional integer vector of length 2 giving the number of
          iterations of the EM algorithm to apply when fitting the 'm1'
          and 'm2' to each simulated set of data. Defaults to
          'c(40,200)'.  

  useGen: an optional logical value. If 'TRUE', numerical derivatives
          are used to obtain the gradient and the Hessian of the
          log-likelihood in the optimization algorithm in the 'ms'
          function. If 'FALSE', the default algorithm in 'ms' for
          functions that do not incorporate gradient and Hessian
          attributes is used. Default depends on the 'pdMat' classes
          used in 'm1' and 'm2': if both are standard classes (see
          'pdClasses') then defaults to 'TRUE', otherwise defaults to
          'FALSE'. 

     ...: optional additional arguments.  None are used.

Value:

     an object of class 'simulate.lme' with components 'null' and
     'alt'.  Each of these has components 'ML' and/or 'REML' which are
     matrices.  An attribute called 'Random.seed' contains the seed
     that was used for the random number generator.

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:

     'lme', 'set.seed'

Examples:

     ## Not run: 
     orthSim <-
        simulate.lme(list(fixed = distance ~ age, data = Orthodont,
                          random = ~ 1 | Subject), nsim = 1000,
                     m2 = list(random = ~ age | Subject))
     ## End(Not run)

